> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# 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](/user-guide/agents/creating-and-configuring-agents). For failure classes, tool call limits, and tool call strategy, see [Agent tools](/user-guide/agents/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 type  | Where you define it                                 | What runs it                                   | Use it for                                          |
| ---------- | --------------------------------------------------- | ---------------------------------------------- | --------------------------------------------------- |
| Built-in   | Provided by Runtype; configure keys in **Settings** | Runtype or the model provider                  | Web search, scraping, images, knowledge bases       |
| Custom     | **Tools** page, as code, or inline in a request     | Runtype, in the execution environment you pick | Calculations, transformations, validation           |
| External   | **Tools** page, as code, or inline in a request     | The HTTP API that you configure                | Third-party APIs, internal services, webhooks       |
| Flow       | **Tools** page, as code, or inline in a request     | Runtype runs the Flow                          | Multi-step logic that several Agents or Flows share |
| Subagent   | **Tools** page, as code, or inline in a request     | A child Agent with a subset of Tools           | Delegating a focused task with its own context      |
| MCP server | **Tools** page, or inline in a request              | The external MCP server                        | Tools that an MCP server exposes                    |
| Local      | Inline in a request, or as code                     | Your SDK client                                | Code 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](/user-guide/tools/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](/user-guide/tools/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](/user-guide/tools/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](/user-guide/agents/agent-tools#flow-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](/user-guide/agents/agent-tools#subagent-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](/developer-guides/integrations/mcp-servers).

To expose your own Product to MCP clients instead, see [Setting up an MCP Surface](/user-guide/products-surfaces/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](/user-guide/tools/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](/user-guide/tools/creating-custom-tools#test-a-tool).

To manage Tools from a codebase, use `defineTool` and `Runtype.tools.ensure()`. For instructions, see [Manage tools as code](/user-guide/tools/manage-tools-as-code).

## Next steps

* [Agent tools](/user-guide/agents/agent-tools): set tool call limits, strategy, and error handling for an Agent
* [Working with tools](/developer-guides/guides/working-with-tools): add Tools to a Flow and pass secrets
* [Built-in tools](/user-guide/tools/built-in-tools): configure provider and platform Tools
* [Creating custom tools](/user-guide/tools/creating-custom-tools): write code that Agents can run
* [Creating external tools](/user-guide/tools/creating-external-tools): connect an HTTP API
* [Runtime tools](/user-guide/tools/runtime-tools): define Tools inline in a dispatch request
* [MCP servers](/developer-guides/integrations/mcp-servers): connect external MCP servers to Agents and Flows
* [Manage tools as code](/user-guide/tools/manage-tools-as-code): define and converge saved Tools from your repository
* [Creating and configuring Agents](/user-guide/agents/creating-and-configuring-agents): add Tools to an Agent
* [Designing tools for agents](/user-guide/tools/designing-tools-for-agents): write tool names, descriptions, and parameters that Agents use well
* [Tool approvals](/user-guide/tools/tool-approvals): require approval before a tool runs, and approve or resume from the API