Skip to navigation
Agents

Agent tools

Attach tools to an Agent so it can call APIs, run code, or query knowledge bases during a run. The model selects tools from their descriptions.

How tool selection works

The model uses each tool description to choose a matching tool and decide when to call it. You don’t define the call order.

Tool types for Agents

Built-in tools

Runtype provides platform integrations and provider-native tools. The built-in tools cover the following categories:

  • Web search and scraping, such as Exa, Firecrawl, and Massive Web Render.
  • Provider-native search, such as OpenAI Web Search, Anthropic Web Search and Web Fetch, xAI Web Search and X Search, and Google Search with compatible Gemini models.
  • Image generation with GPT Image 2.5.
  • Knowledge and data, such as Semantic Search, Record management tools, and Agent Memory. Runtype adds the Agent Memory tools when you enable memory on the Agent.
  • Browser tools that capture screenshots, extract content, and keep a browser session across actions.
  • File outputs, such as Store Asset, Publish Page, and Generate PDF.
  • Messaging, such as Send Email.
  • Third-party APIs, listed in the API category of the tool picker.

Provider-native tools require a compatible model from the corresponding provider. Platform tools such as Exa, Firecrawl, Semantic Search, and Browser tools work with any model. Depending on the tool, use a Runtype platform key or connect your own provider key. Configure provider keys in Settings > Models or platform integrations in Settings > Integrations, depending on the tool. For the full list and each tool’s requirements, see Built-in tools.

Custom tools

Write JavaScript, TypeScript, or Python code for specialized tasks. The language determines where the tool can run. JavaScript can run in a Cloudflare Worker, which has no network access unless the tool turns it on. TypeScript and Python run in Runtype Sandbox or Daytona Sandbox. For each execution environment, see Creating custom tools.

External tools

Call HTTP API endpoints with parameters that the Agent supplies. See Creating external tools.

Flow tools

Publish a Flow to use it as a tool. The Agent calls the Flow like a function and receives its final output. Use Flow tools to reuse multi-step logic across Agents.

In the tool picker, the Flows category lists two kinds of entries:

  • Saved bindings: Flow tools with preconfigured parameters.
  • Flows: Runtype derives the tool parameters from the Flow’s steps.

MCP tools

Connect an external Model Context Protocol (MCP) server to expose its tools to your Agent. Configure an MCP integration in Settings > Integrations. In the MCP servers category of the tool picker, select the server to attach each of its current tools, or select individual tools. Tools that the server adds later aren’t attached automatically.

Subagent tools

Add a subagent tool to delegate a focused task to a child Agent with a subset of tools and an isolated context. In the tool picker, the Sub-agents category lists saved bindings with preconfigured handoff parameters and saved Agents whose parameters Runtype derives.

To let the Agent choose what to delegate at run time, turn on Dynamic spawning in the Subagents section of the Agent editor. Runtype adds the spawn_subagent tool. For the subagentConfig options, see Runtime tools.

Advisor

Select Advisor in the tool picker and choose a model. The Agent gets an advisor tool that consults that model for strategic guidance. The advisor receives the full conversation history, including tool calls and results. Each advisor call is an additional model call, so choose the advisor model with cost in mind.

Artifact tools

The Artifacts category adds tools that stream Markdown or component content to supported clients. Runtype adds the matching model instructions when you enable them.

Attach tools to an Agent

To attach tools from the Agent editor, follow these steps:

  1. Open the Agent that you want to configure.
  2. Click Add on the Agent’s Tools page, or click the + button in the tools bar. The tool picker opens.
  3. Select the tools to attach. Each selection applies to the Agent’s draft.
  4. Close the tool picker and save the Agent.

To manage the same configuration in code, set the tools block of the Agent definition. The following example attaches a built-in tool and a saved tool, and sets the tool call limit and strategy:

Agent tools configuration
{
  "tools": {
    "toolIds": ["builtin:exa", "tool:order-lookup"],
    "maxToolCalls": 10,
    "toolCallStrategy": "auto"
  }
}

For tool ID formats, see Manage Agents as code. To supply tools with a single dispatch request instead, use runtime tools.

Require approval for tool calls

To pause before a tool runs until a person approves it, turn on Tool approval in the Agent editor. Choose All tools or Only selected to set which calls need approval. For patterns, remembered approvals, and how each Surface shows the prompt, see the Safety section of Creating and configuring Agents.

Code mode

Code mode lets the model call several tools from one sandboxed JavaScript program instead of one tool call at a time. Use it when the work loops or branches between tool calls.

To enable code mode, follow these steps:

  1. In the Agent editor, open the Code mode section.
  2. Turn on Code execution.
  3. In Tool pool, select the tools the program can call. The pool lists only tools that are already attached to the Agent. Local tools aren’t available.
  4. Optional: Set Timeout (s) for one sandbox run. The value ranges from 1 to 600 seconds. The default is 60 seconds.

In an Agent definition, set tools.codeModeConfig with a toolPool array and an optional timeoutMs from 1000 to 600000.

Tool search is on by default for Agents that have Agent loop turned on, which means loopConfig.maxTurns of 2 or more. When such an Agent has 20 or more tools, Runtype holds some of its tools back from the model and adds a tool_search tool. The model calls tool_search with a query and receives up to 5 matching tools, or up to 10 when it sets max_results. The matching tools load on the next turn, and that turn counts toward Max turns.

Tool search holds back only inline runtime tools (tools.runtimeTools). The following tools are always sent:

  • Saved tools and built-in tools in tools.toolIds.
  • MCP server tools.
  • Memory tools, the advisor, and subagent tools.
  • Tools that you list in tools.toolSearch.alwaysLoaded.

Agents without Agent loop and Flow prompt steps never hold tools back. The model receives every configured tool on every request, because a tool that it found could only be called on a later turn.

To change tool search, set tools.toolSearch in the Agent definition:

Tool search configuration
{
  "tools": {
    "toolSearch": {
      "threshold": 30,
      "alwaysLoaded": ["lookup_customer"]
    }
  }
}

The tools.toolSearch object accepts the following fields:

  • enabled: Set to false to send every tool on every turn. Set to true to turn on tool search below the threshold.
  • threshold: The tool count at which tool search turns on. The default is 20.
  • alwaysLoaded: The names or IDs of tools that are always sent.

A dispatch request that references a saved Agent can override its setting for one run, for example with agent.tools.toolSearch set to { "enabled": false }.

The model finds a held-back tool only by searching for it, and each search costs a turn. Give every tool a specific name and description, add tools that the Agent needs on most runs to alwaysLoaded, and check the tool-call sequence in Logs.

Writing effective tool descriptions

The model uses tool descriptions to choose when to call a tool. Write specific descriptions that state the tool’s purpose, usage condition, and output.

The following description gives the tool a clear purpose and usage condition:

lookup_customer_order(orderId: string) -> Order
Retrieves detailed order information by order ID. Returns order status,
items, shipping address, and tracking number. Use this when users ask about
specific orders.

Avoid vague descriptions such as the following:

Gets order data

Include the following details:

  • The tool’s purpose.
  • When to use it.
  • What it returns.
  • Limitations and requirements.

Tool parameters

Runtype sends tool parameter names, types, and descriptions to the model as part of the tool definition. Write each parameter description as an instruction that tells the model what value to provide.

Multi-step tool usage

An Agent can call tools in sequence without explicit orchestration. For example, give it lookup_customer and create_ticket tools. After the first call, it can use the result to call the second tool.

Monitoring tool usage

Open the run in Logs to see which tools the Agent called, the call order, the parameters, and the results. Use the logs to improve tool descriptions when selection is wrong.

If the Agent repeatedly selects the wrong tool, improve that tool’s description or add examples that explain when to use it.

Tool call limits

Set Max tool calls to cap the number of tool calls in a single turn. The default is 10. The dashboard control accepts 1 to 50, and Agent configuration accepts 1 to 100.

Enable Agent loop and set Max turns to cap the number of turns in one execution. The dashboard control accepts 2 to 20 turns, and Agent configuration accepts 1 to 100. Max turns is a cap, not a required number of turns.

Within one turn, the model sees each tool result and can call more tools, up to Max tool calls. The loop starts another turn in the following cases:

  • The turn reached Max tool calls.
  • A Skill load added tools for the next turn.
  • A tool_search call found tools to load for the next turn.
  • The model returned an error.
  • The model ran out of output tokens while it wrote a tool call.

When the model ends its turn with an answer, the execution ends. Enabling Agent loop doesn’t give the model extra turns to re-plan.

If the model runs out of output tokens while it writes a tool call, Runtype reports that tool call as failed. If turns remain and the cost budget isn’t used up, the Agent continues. Otherwise, the execution fails with the stop reason length. Any text that the Agent wrote before the cutoff is returned with the failed result. Raise the Agent’s max output tokens if this happens repeatedly.

To end such a turn as a success and stop the loop instead, set loopConfig.treatLengthCutoffAsFailure to false. It defaults to true. The cut-off tool call is still reported as failed, so use this setting only while you raise max output tokens.

Use these guidelines when setting Max turns:

  • Set the cap high enough for the Agent to finish the task.
  • Pair a high cap with a Cost budget (USD) because repeated tool calls or retries can continue until the cap.
  • Start with 5 to 10 max turns for most tasks.

Most Agents don’t need Agent loop. One turn can call several tools in sequence, up to Max tool calls. Enable Agent loop when one turn doesn’t allow enough tool calls, or when the Agent loads Skills that add tools. With Agent loop on, an Agent that has 20 or more tools, including inline runtime tools, uses tool search.

Tool call strategy

The Tool call strategy setting controls whether the model calls a tool. Set it to Auto for most Agents so the model can call a tool or answer with text.

Use Required for a single forced tool call, such as a structured-output or routing tool. Set Max tool calls to 1 and leave Agent loop off.

Don’t use Required on a looping Agent. The model must call a tool on every step, so the Agent can’t return a final text answer and reaches Max turns with empty output.

None turns off tool calling, so the Agent answers without its attached tools.

Require a committed intent

Set tools.intent to mandatory so that a tool that isn’t idempotent runs only after Runtype records its intent. If the intent can’t be recorded, the tool doesn’t run, and the model receives a TOOL_INTENT_NOT_COMMITTED error that says the call had no effect. The default is best-effort. For details, see Require a committed intent before a tool runs.

Error handling

When a tool returns an error, the Agent receives the error message and a failure class (errorType): auth, rate_limited, upstream_4xx, upstream_5xx, timeout, invalid_args, not_configured, aborted, or unknown. The Agent can then retry, correct its arguments, or choose another tool. Runtype doesn’t tell the Agent whether to retry, because a timed-out call that writes data may already have taken effect. Use Max turns and Cost budget (USD) to cap repeated retries. Write clear tool error messages so the Agent can respond appropriately.

Best practices

Apply the following practices when you configure tools:

  • Start with two to five tools. A smaller set narrows tool selection.
  • Avoid overlapping tools. Similar tools make selection less reliable.
  • Use descriptive names. search_orders tells the model more than search.
  • Test tool selection by running the Agent and checking the execution log for the tool-call sequence.
  • Monitor costs. Each tool call adds model and tool-execution cost.
  • Use managed secrets. Don’t expose credentials in tool configurations or descriptions.

Next steps