Runtype
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

  • OpenAI Web Search: Native web search via OpenAI models

  • Anthropic Web Search: Native web search via Anthropic models

  • xAI Web Search / X Search: Native web and X/Twitter search via xAI's Responses API

    Content generation

  • DALL-E: Image generation from text descriptions

    Knowledge and data

  • Vector Search: Semantic search across your knowledge bases

  • Runtype Record tools: Read, write, list, and delete Records directly

    Voice

  • ElevenLabs TTS: Text-to-speech synthesis

  • ElevenLabs STT: Speech-to-text transcription

    Provider-native tools (OpenAI Web Search, Anthropic Web Search, xAI Search) require the corresponding model provider. Platform tools (Exa, Firecrawl, DALL-E, Vector Search, ElevenLabs) 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.

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, or MCP 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 iterations to prevent runaway tool calling:

  • Too low: Agent gives up before completing the task

  • Too high: Expensive runaway executions

  • Recommended: 5–10 for most tasks

Error handling

If a tool returns an error or non-2xx response, the Agent sees the error message and can retry or switch tools. Set Max iterations 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

Was this helpful?