Agents

Agent tools

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

How tool selection works

The Agent reads tool descriptions and invokes the best match autonomously. You don’t specify when tools are called.

Tool types for Agents

Built-in tools

Runtype provides ready-to-use platform integrations and provider-native tools:

Web search and scraping

  • Exa: Neural and keyword web search with summaries and highlights
  • Firecrawl: Scrape and extract content from any URL as markdown
  • Massive Web Render: Fetch hard-to-retrieve pages via JavaScript rendering, captcha solving, and a residential network
  • OpenAI Web Search: Native web search via OpenAI models
  • Anthropic Web Search: Native web search via Anthropic models
  • Anthropic Web Fetch: Fetch and extract content from URLs via Anthropic models
  • xAI Web Search / X Search: Native web and X/Twitter search via xAI models

Content generation

  • GPT Image 2: Image generation from text descriptions

Knowledge and data

  • Semantic Search: Semantic search across your knowledge bases
  • Runtype Record tools: Read, write, list, and delete Records directly
  • Agent Memory: Persist facts across sessions, recall them by meaning, and summarize what the Agent knows (save_memory, recall_memory, memory_summary). Available as a bundle when memory is enabled on the Agent

Browser

  • Browser tools: Screenshot, scrape, extract content, and convert pages to markdown using a headless browser. Session tools provide persistent browser sessions for multi-step interactions.

File outputs

  • Store Asset: Upload files to the CDN and get a shareable URL
  • Publish Page: Publish an HTML page with a shareable URL
  • Generate PDF: Render HTML or Markdown to a PDF document

Provider-native tools (OpenAI Web Search, Anthropic Web Search, xAI Search) require the corresponding model provider. Platform tools (Exa, Firecrawl, Massive, GPT Image 2, Semantic Search, Browser) work across any model and use your platform key or BYOK configuration. Enable platform integrations in Settings → Integrations.

Custom tools

JavaScript or Python code you write for specialized tasks. Custom tools run in a sandbox with no network access (Cloudflare Worker) or in a configurable container (Daytona). See Creating custom tools.

External tools

HTTP API endpoints the Agent calls with dynamic parameters. See Creating external tools.

Flow tools

Any published Flow can become a tool. The Agent invokes the Flow like a function, passing parameters and receiving the Flow’s final output.

  1. Create and publish a Flow
  2. Add it to the Agent’s tools list
  3. The Agent can now invoke that Flow

This is useful for reusing complex multi-step logic across multiple Agents.

MCP tools

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

Subagent tools

Spawn a focused child Agent with a subset of tools and an isolated context. Subagents let a parent Agent delegate a specific subtask to a smaller, more focused Agent. You can use saved Agents, define inline Agent configurations, or enable dynamic spawning via spawn_subagent.

Attaching tools to an Agent

Add tools to an Agent from the Agent editor:

  1. Open the Agent you want to configure
  2. Go to the Tools section
  3. Click Add Tool
  4. Select from built-in, custom, external, Flow, MCP, or subagent tools
  5. Save the Agent

Writing effective tool descriptions

Tool descriptions guide Agent decision-making. Be specific:

Good:

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.

Poor:

Gets order data

Include:

  • What the tool does
  • When to use it
  • What it returns
  • Any limitations or requirements

Tool parameters

Agents need to know what parameters tools expect. Parameter names, types, and descriptions are forwarded to the model automatically. Write descriptions as clear instructions — the Agent reads them to decide what values to pass.

Multi-step tool usage

Agents can chain tools without explicit orchestration. For example, an Agent with lookup_customer and create_ticket tools can resolve a refund request end-to-end.

Monitoring tool usage

Review execution logs to see which tools the Agent called, in what order, and with what parameters. This helps you understand Agent reasoning and identify wrong tool selections.

Tip: If an Agent repeatedly calls the wrong tool, improve that tool’s description or add examples of when to use it.

Tool call limits

Set Max Tool Calls to limit how many tool calls the Agent can make in a single turn, and enable Agent Loop with a Max Turns setting to control how many reasoning iterations the Agent can perform:

  • Too low: Agent gives up before completing the task
  • Too high: Expensive runaway executions
  • Recommended: 5–10 max turns for most tasks

Most Agents do not need Agent Loop. A single turn already lets the Agent call several tools in sequence (up to Max Tool Calls) to finish a task that takes multiple steps. Turn on Agent Loop only when the Agent must reason across multiple rounds — re-planning or reflecting after seeing earlier results, or holding a back-and-forth conversation.

Tool call strategy

Tool call strategy controls whether the Agent is forced to use a tool. Keep it on Auto for almost every Agent: the model decides when to call a tool and when to answer with text. Use Required only for a single forced tool call (with Max Tool Calls set to 1 and no Agent Loop), such as forcing a structured-output or routing tool. Avoid Required on a multi-step or looping Agent — the model is then forced to call a tool on every step and can never finish with a text answer, so the Agent returns an empty result.

Error handling

If a tool returns an error or non-2xx response, the Agent sees the error message and can retry or switch tools. Use Max Turns and Cost Budget on the Agent to prevent runaway loops. Make tool error messages clear so Agents can respond appropriately.

Best practices

  • Start with 2–5 tools. Too many tools confuse the Agent.
  • Avoid overlapping tools. Similar tools lead to poor selection.
  • Descriptive names. search_orders is better than search.
  • Test tool selection by running the Agent and checking the execution log for the tool call sequence.
  • Monitor costs. Each tool call = LLM reasoning + tool execution.
  • Use managed secrets. Never expose credentials in tool configs or descriptions.

Next steps