Custom Tools

Custom Tools let you define callable functions that Agent blocks can invoke at runtime. Each saved tool has a title, a JSON function schema that describes its inputs, and a JavaScript function body that runs when the tool is called. The title is saved as entity metadata outside the function schema.

Studio assigns the tool a stable entity ID when it is created. Agent blocks reference that entity internally as custom_<entityId>, so renaming the title does not change the saved reference.

Tool schema

The editor validates the function schema as you edit it. A schema does not contain the tool's title or a function.name field; those are replaced by the saved entity identity described above.

{
  "type": "function",
  "function": {
    "description": "Add one quantity of a food item to the order.",
    "parameters": {
      "type": "object",
      "properties": {
        "itemName": {
          "type": "string",
          "description": "The name of the food item to add to order"
        }
      },
      "required": ["itemName"]
    }
  }
}

• type must be "function".
• function.description tells the agent when to use the tool.
• function.parameters is a standard JSON Schema object describing the inputs.
• function.parameters.type must be "object", and properties must be an object. The required array is optional.

Tool code

The code tab contains only the body of an async function(params, environmentVariables). Do not include the function wrapper or imports. Two referencing conventions are available inside the editor:

• Parameters — wrap the parameter name in angle brackets, for example <itemName>. The editor provides autocomplete from the schema.
• Environment variables — use double-brace syntax: {{API_KEY}}.

The function should return a value when the tool is expected to produce output. External imports are not supported; use fetch or built-in APIs.

Creating and editing tools

Import and Export

Custom tools use the shared TradingGoose export JSON format. Each exported record contains a top-level title, schema, and code. Export a tool from the Custom Tool Editor and import it from the Custom Tool List widget. Imported titles are normalized, and title collisions are renamed so the import can complete without manual cleanup.

How agents invoke custom tools

When you add a custom tool to an Agent block's tool list, Studio stores the stable custom_<entityId> reference. At runtime, the saved title becomes the model-facing tool name, while the title and function.description form its description and function.parameters defines its input schema. The agent decides whether and when to call the tool from that information and the conversation context, then Studio executes the JavaScript body with the resolved parameters.

Custom Tools vs MCP

For external tool integrations using MCP, see the MCP utility page.

Related