Skip to navigation
Tools

What are Tools?

Tools give your Agents and Flows access to capabilities such as web search, API calls, custom code, and external services. Add a Tool when your workflow needs to do more than generate text.

How Tools work

When you add Tools to an Agent or a Flow prompt step, the model selects Tools based on their descriptions and the incoming message. The sequence is:

  1. The model selects a Tool whose description matches the request.
  2. The model generates the required parameters and sends the call.
  3. If the Agent requires approval for that Tool, the run pauses until a person approves or denies the call.
  4. Runtype runs the Tool and returns its result.
  5. The model uses the result to continue the response.

If the Tool fails, the model receives the error message and a failure class, such as timeout or invalid_args. It can then retry, correct its arguments, or choose another Tool. For approval settings, see the Safety section of Creating and configuring Agents. For failure classes, tool call limits, and tool call strategy, see Agent tools.

Write each Tool description to state what the Tool does and when to call it.

Example

Dana adds Exa to a research Agent. When Dana asks about a topic, the model calls Exa, receives search results, and uses them in the response.

Tool types

Runtype organizes Tools by how you define and run them, as the following table shows.

Tool typeWhere you define itWhat runs itUse it for
Built-inProvided by Runtype; configure keys in SettingsRuntype or the model providerWeb search, scraping, images, knowledge bases
CustomTools page, as code, or inline in a requestRuntype, in the execution environment you pickCalculations, transformations, validation
ExternalTools page, as code, or inline in a requestThe HTTP API that you configureThird-party APIs, internal services, webhooks
FlowTools page, as code, or inline in a requestRuntype runs the FlowMulti-step logic that several Agents or Flows share
SubagentTools page, as code, or inline in a requestA child Agent with a subset of ToolsDelegating a focused task with its own context
MCP serverTools page, or inline in a requestThe external MCP serverTools that an MCP server exposes
LocalInline in a request, or as codeYour SDK clientCode that must run in your own application

Built-in tools

Runtype provides built-in Tools for common capabilities, such as GPT Image 2.5, Exa, Firecrawl, provider web search, and Semantic Search. The tool picker shows only Tools that are compatible with the selected model.

Some built-in Tools work with a Runtype platform key, and others need your own key in Settings > Models or Settings > Integrations. For each Tool’s compatible models and key requirements, see Built-in tools.

To call a built-in Tool at a fixed point in a Flow, use a Tool Call step and set its toolId to the catalog ID, for example builtin:exa.

Custom tools

Custom Tools run code that you write. You choose an execution environment for each custom Tool, and the environment determines which languages and network access are available. For the options, see Creating custom tools.

External tools

External Tools call HTTP API endpoints. Configure authentication with bearer tokens, API keys, or custom headers. Store credentials as managed secrets and reference them as {{secret:NAME}}, so that the key never appears in the Tool configuration. For details, see Creating external tools.

Flow tools

Flow Tools let other Agents and Flows call a Flow like a function. The caller receives the Flow’s final output. If you repeat the same logic in multiple Flows, move that logic into a separate Flow and use it as a Flow Tool.

To create a Flow Tool, on the Tools page, click Create Tool and select Flow Tool in the Type list, or call POST /v1/tools/flows/{flowId}/convert-to-tool, which generates the Tool parameters from the Flow’s steps. For how Agents use Flow Tools, see Agent tools.

Subagent tools

Subagent Tools delegate a focused task to a child Agent that has a subset of Tools and an isolated context. For setup, see Agent tools.

MCP servers

MCP (Model Context Protocol) servers expose Tools from external services. Connect an MCP server by URL, and Runtype discovers its Tools. To save a server, click Create Tool on the Tools page and select MCP Server in the Type list. For setup and authentication, see MCP servers.

To expose your own Product to MCP clients instead, see Setting up an MCP Surface.

Runtime tools

You can define custom, external, Flow, subagent, and local Tools inline in an API request, such as a dispatch request, without saving them. Use runtime Tools for dynamic or temporary configurations, SDK-driven Flows, and testing. A request can include any number of runtime Tools, up to 1 MB of Tool definitions across all steps. For details, see Runtime tools.

Create and test a saved Tool

Saved Tools appear on the Tools page. To create one, click Create Tool and select a type in the Type list. Built-in Tools do not appear in this list.

To check a saved Tool before you attach it, open it, enter sample values in the Test Tool panel, and click Run Test, or call POST /v1/tools/{id}/execute. For details, see Test a Tool.

To manage Tools from a codebase, use defineTool and Runtype.tools.ensure(). For instructions, see Manage tools as code.

Next steps