@mastra/core/dist/docs/references/reference-editor-tools.md

> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# Tool configuration

Editor stores tool selections as part of an agent version. A stored configuration can add registered tools, tools from integration providers, and tools from Model Context Protocol (MCP) clients.

See [Editor tools](https://mastra.ai/docs/editor/overview) for the Studio workflow and common uses.

## Tool sources

| Source                                                             | Description                                                                          |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| Registered tools                                                   | Tools registered in the Mastra runtime tool registry                                 |
| MCP clients                                                        | Tools exposed by stored local or remote MCP server configurations                    |
| Integration tools                                                  | Tools resolved by legacy integration-provider configuration                          |
| [Tool providers](https://mastra.ai/reference/editor/tool-provider) | Tools resolved by providers registered on `MastraEditor`, such as Composio or Arcade |

Code-defined agents keep their existing tools. The [`editor` override setting](https://mastra.ai/reference/agents/agent) controls whether Editor can add and remove tools or only change descriptions.

## Description overrides

Each selected tool can store an agent-specific description. The description changes what the model sees without modifying the original tool definition.

In description-only mode, Editor applies overrides only to tools that already exist on the code-defined agent. For MCP tools, an agent-level description takes priority over the description stored on the MCP client.

If two sources resolve the same tool ID, the later source replaces the complete earlier tool, including its description. See [Resolution order](#resolution-order).

## Conditional tool sets

Editor can store conditional variants for the `tools`, `mcpClients`, `integrationTools`, and `toolProviders` fields. At runtime, matching variants are shallow-merged based on request-context values.

The rule language uses the same operators and nesting behavior as [prompt block display conditions](https://mastra.ai/reference/editor/prompt-blocks).

Conditions apply to a tool field variant or MCP client reference. Per-tool `rules` values in stored tool entries aren't evaluated by the current Editor resolver.

## Stored MCP clients

The `editor.mcp` namespace manages reusable MCP client configurations. See the [`mcp` namespace](https://mastra.ai/reference/editor/mastra-editor) for CRUD method signatures.

`@mastra/mcp` is an optional peer dependency of `@mastra/editor`. Install it before configuring stored MCP clients so Editor can load their tools at runtime:

**npm**:

```bash
npm install @mastra/mcp
```

**pnpm**:

```bash
pnpm add @mastra/mcp
```

**Yarn**:

```bash
yarn add @mastra/mcp
```

**Bun**:

```bash
bun add @mastra/mcp
```

### Transports

| Transport | Stored configuration                                 |
| --------- | ---------------------------------------------------- |
| `stdio`   | `command` with optional `args`, `env`, and `timeout` |
| HTTP      | `url` with optional `timeout`                        |

Stored HTTP definitions don't accept arbitrary headers. When the reserved `mastra__authToken` value is present in request context, Editor forwards it as an `Authorization: Bearer` header.

### Filtering

MCP tools can be allowlisted at two levels:

1. **Server level**: The stored server's `tools` map limits tools for every agent that uses the client.
2. **Agent level**: The agent's MCP client reference limits the remaining tools for that agent.

Agent-level tool names can use namespaced or bare names. An explicit empty `tools` map selects all tools. With the current resolver, omitting `tools` from an agent-level MCP reference selects none.

### Namespacing

MCP tools use `serverName_toolName` IDs to avoid conflicts. A `search` tool from the `docs` server becomes `docs_search`.

## Resolution order

Editor merges tool records in the following order. Later records replace earlier records with the same ID.

1. Code-defined tools
2. Registered stored tools
3. MCP tools
4. Legacy integration tools
5. V1 tool-provider tools

Standalone stored agents use the same order without code-defined tools. Static code-agent overrides stop after legacy integration tools.

Use unique tool IDs across sources when possible. A collision replaces the complete earlier tool rather than merging its fields.