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 do not define the call order.

Tool types for Agents

Built-in tools

Runtype provides platform integrations and provider-native tools. Use the following built-in tools for web search and scraping:

  • Exa: Search the web with neural and keyword algorithms, with optional summaries, highlights, and full text.
  • Firecrawl: Scrape and extract content from a URL as Markdown.
  • Massive Web Render: Fetch hard-to-retrieve pages by rendering JavaScript, solving CAPTCHAs, and using a residential network.

Use the following provider-native tools for web search and web content retrieval:

  • OpenAI Web Search: Search the web with compatible OpenAI models.
  • Anthropic Web Search: Search the web with compatible Anthropic models.
  • Anthropic Web Fetch: Fetch and extract content from URLs with compatible Anthropic models.
  • xAI Web Search: Search the web with compatible xAI models.
  • xAI X Search: Search X posts with compatible xAI models.

Use the following tool for content generation:

  • GPT Image 2: Generate images from text descriptions.

Use the following tools for knowledge and data:

  • Semantic Search: Search your knowledge bases by meaning.
  • Record management tools: Create, update, read, list, and delete Records directly.
  • Agent Memory: Store facts across sessions, recall them by meaning, and summarize stored memory with save_memory, recall_memory, and memory_summary. Runtype adds this bundle when you enable memory on the Agent.

Use the following tools to browse web pages:

  • Browser tools: Capture screenshots, extract content, scrape selectors, and convert pages to Markdown. Session tools keep browser state across multiple actions.

Use the following tools to create file outputs:

  • Store Asset: Upload files to Runtype storage and return a shareable URL.
  • Publish Page: Publish an HTML page and return a shareable URL.
  • Generate PDF: Render HTML or Markdown as a PDF.

Provider-native tools require a compatible model from the corresponding provider. Platform tools such as Exa, Firecrawl, Massive Web Render, GPT Image 2, Semantic Search, and Browser tools work with any model. Depending on the tool, use a Runtype platform key or connect your own provider key. To configure platform integrations, open Settings > Integrations.

Custom tools

Write JavaScript, TypeScript, or Python code for specialized tasks. Runtype runs custom tools in a Cloudflare Worker or a configurable Daytona container. Cloudflare Worker tools have no network access. 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.

To use a Flow as a tool, follow these steps:

  1. Create and publish a Flow.
  2. Add the Flow to the Agent’s tools.
  3. Run the Agent. The Agent can invoke the Flow with parameters and receive its final output.

Use Flow tools to reuse multi-step logic across Agents.

MCP tools

Connect an external Model Context Protocol (MCP) server to expose its tools to your Agent. Configure an MCP integration in Settings > Integrations, then add individual MCP tools to the Agent.

Subagent tools

Add a subagent tool to spawn a focused child Agent with a subset of tools and an isolated context. Use a saved Agent, define an inline Agent configuration, or enable dynamic spawning through spawn_subagent.

Attaching tools to an Agent

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

  1. Open the Agent that you want to configure.
  2. Open Tools in the Agent editor.
  3. Click Add Tool or Configure Tools.
  4. Select built-in, custom, external, Flow, MCP, or subagent tools.
  5. Click Apply Changes.

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

Review execution 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. Enable Agent Loop and set Max Turns to cap the number of turns in one execution.

Max Turns is a cap, not a required number of turns. The loop stops when the Agent completes the task or reaches the cap. The Agent can take another turn after the current turn reaches Max Tool Calls. It can also take another turn after a Skill load or tool search adds tools for the next turn.

A turn that runs out of output tokens while the model is still writing a tool call ends the whole execution as a failure, with the stop reason length. The cut-off tool call is reported as a failed tool call rather than left unanswered. Raise the Agent’s max output tokens for that case; raising Max Turns does not help.

If the Agent still produced a closing sentence before it was cut off, that text is delivered with the failed result rather than replaced by a generic error message.

To keep the older behavior, where such a turn reported success with empty output, set loopConfig.treatLengthCutoffAsFailure to false on the Agent. It defaults to true. The cut-off tool call is still reported as a failed tool call either way, so use this only as a temporary measure 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 because repeated tool calls or retries can continue until the cap.
  • Start with 5 to 10 max turns for most tasks.

Most Agents do not need Agent Loop. One turn can call several tools in sequence, up to Max Tool Calls. Enable the loop when the Agent must re-plan after receiving results. Enable it when one turn lacks enough tool calls. Also enable it when a Skill load or tool search adds tools for a following turn.

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.

Do not use Required on a looping Agent. The model must call a tool on every step, so the Agent cannot return a final text answer and reaches Max Turns with empty output.

Error handling

When a tool returns an error, the Agent receives the error message and can retry or choose another tool. Use Max Turns and Cost Budget 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. Do not expose credentials in tool configurations or descriptions.

Next steps