Claude Code Tool Search: How the AI Agent Finds an MCP Tool

If you have connected several MCP servers to Claude Code, tool search lets it load the tools it needs on demand, without loading every definition in advance. At startup, the agent receives the names of deferred tools and the servers' instructions, then searches the catalog for what it needs. This helps it work with a large set of tools: Anthropic's documentation states that selection accuracy drops when more than 30-50 tools are loaded at once. This is general guidance, not a measurement of your session. Tool search is enabled by default when the model supports it, but the platform, a proxy, or settings can disable it.

Ailoot documentation: API, keys, and setup.

How do MCP tool definitions affect Claude Code context?#

Each connected MCP server adds its tools to the list of things the agent can call. Without tool search, their definitions — name, description, and parameter schema — are loaded into context in advance. Servers connect in the background when a session starts. If a tool is needed from a server that has not finished connecting, Claude Code waits through the internal WaitForMcpServers tool. You can assess how many tools and tokens a particular server adds separately for each connection.

Anthropic's official documentation gives two approximate figures (general numbers, without a stated measurement method):

• 50 tools can take up 10-20 thousand context tokens;
• accuracy in selecting the right tool drops when more than 30-50 are loaded at once.

How to assess tool search from the settings#

To understand whether tool search should work in the current session, check these conditions:

• which model is responding — Sonnet/Haiku/Opus 4.5 or newer: the mechanism is available; an older model: it is not;
• whether ANTHROPIC_BASE_URL is set to a nonstandard host — in that case, the mechanism is off by default unless explicitly enabled through ENABLE_TOOL_SEARCH;
• the value of the ENABLE_TOOL_SEARCH variable — false disables the mechanism completely; auto/auto:N enables it only when the volume of definitions reaches a threshold;
• whether CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS is set — without the organization's managed settings, it keeps tool search off even if the user has set ENABLE_TOOL_SEARCH;
• whether the ToolSearch tool is blocked through permissions.deny in the settings — such a restriction disables search;
• which platform is used — the mechanism is unavailable on Microsoft Foundry deployments in Azure, while on Google Cloud Agent Platform its behavior depends on the Claude Code version and model.

This check lets you assess the state from the configuration, but not observe it inside the session. The MCP section and the tool search section in the Agent SDK documentation do not describe a direct “tool search: on/off” indicator in the interface. The absence of a mention in these two documents does not prove that no such indicator exists anywhere.

You can set the variable before starting a session, for example ENABLE_TOOL_SEARCH=auto:15 claude. To ensure that a specific server's tools are always loaded, use the alwaysLoad: true field in that server's configuration. It is available for all server types; the conditions and limitations are described in the alwaysLoad section below.

How tool search works#

When tool search is enabled, only the names of deferred tools and the server's instructions are loaded into context at session startup. Server instructions describe which tasks the server is useful for. When a task requires a capability that is not yet in context, the agent searches the catalog for a suitable tool itself.

The Agent SDK documentation describes the search mechanism in more detail: by default, a single search loads up to five of the most relevant tools from the catalog. They remain available for subsequent turns in the session until the SDK compacts the messages in which the agent found them. After compaction, previously discovered tools may drop out of context, and the agent searches for them again the next time they are needed. The catalog supports up to 10 000 tools. The MCP documentation for Claude Code itself does not give these specific figures, but describes the same principle of deferred loading.

According to the Agent SDK documentation, each search adds one extra round-trip. The documentation does not specify exactly what that round-trip includes. For Claude Code, the MCP documentation also describes a difference in error reporting: without tool search, Claude Code does not tell the model about failed server connections. When search is enabled, the model receives information about which server failed to connect and what the error was.

Claude Code does not impose a fixed limit on the number of tools from a single server. The practical limit is the context window budget for the particular session.

Configuring tools is one of the tasks involved in managing an AI agent's context.

When tool search is disabled by default#

The mechanism is enabled by default, but its operation depends on the model, API host, and platform.

Model. Tool search requires a model that supports tool_reference blocks: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5, or later. For older models, Claude Code loads tool definitions in advance.

API host. Claude Code disables tool search when the ANTHROPIC_BASE_URL variable points to a third-party host: most proxies do not pass through the special tool_reference blocks. This applies when connecting to Claude through your own gateway or proxy server instead of directly through Anthropic's address. The reason for disabling it is a nonstandard ANTHROPIC_BASE_URL; the way the subscription is paid for does not itself cause this. You can explicitly set ENABLE_TOOL_SEARCH to override this behavior. If the proxy itself does not support tool_reference blocks, forcing the mechanism on results in a request error. It will not fall back to loading definitions in advance in this case.

Deployment platform. Tool search does not work on Microsoft Foundry deployments hosted on Azure: the server rejects the request, and ENABLE_TOOL_SEARCH does not override this. On Google Cloud Agent Platform, before Claude Code version 2.1.221, the mechanism was off for all models unless ENABLE_TOOL_SEARCH=true was explicitly set. Starting with that version, it is enabled by default for Opus/Sonnet/Haiku 4.5 and newer. For older models on the platform, Claude Code still loads all tools in advance because their server infrastructure rejects the required internal header.

The ENABLE_TOOL_SEARCH variable has five possible settings:

• unset — the standard behavior, with the exceptions listed above;
• true — the mechanism is enabled on models that support it, except for two cases: Azure Foundry and older Agent Platform models; requests sent through a proxy without support for tool_reference blocks will fail;
• auto — Claude Code loads tools in advance while their combined definitions take up less than 10% of the context window, and switches to deferred loading once that threshold is reached;
• auto:N — the same principle, with a manually specified percentage threshold;
• false — the mechanism is completely disabled and all tools are loaded in advance.

There is also the CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS variable: if it is set, tool search stays off, and a user setting ENABLE_TOOL_SEARCH does not change this. The exception is when the organization keeps tool search enabled through managed settings, available starting with Claude Code version 2.1.227.

What alwaysLoad does and how it affects context and startup#

The alwaysLoad: true field in a server's configuration is available for all server types. With it, all of that server's tools are loaded into context at startup regardless of the ENABLE_TOOL_SEARCH setting. The agent does not need to search for them before use.

Always loading tools has two consequences. Each tool loaded in advance takes up some of the context that would otherwise be available for the task itself. In addition, session startup waits for this server to connect, within the standard five-second timeout.

The exception is a remote server with a valid cached entry: it supplies the tools from the cache without connecting and does not delay startup. The discovery cache is off by default unless it has already been enabled for the account during the gradual rollout of the feature. You can also enable it explicitly through MCP_DISCOVERY_CACHE=1. The fast-startup exception applies when the cache is active and contains a valid entry. Tools with alwaysLoad still occupy context permanently, regardless of whether the agent would have needed them when working through search.

For anyone writing their own MCP server: server instructions help Claude understand when to search for its tools, much as Skills do. Claude Code truncates each tool's description and each server's instructions to 2048 characters by default, so place critical details at the beginning.

Choosing how to extend Claude Code depends on more than the number of connected MCP servers. The guides Claude Code: how many extensions to keep at once and What to choose in Claude Code: Skills, Subagents, MCP, or Plugins examine Skills, Subagents, MCP, and Plugins for different tasks. For step-by-step setup of specific MCP servers, see MCP servers for Claude Code: ready-made combinations.

What next#

For a set of fewer than roughly 10 tools whose definitions fit into context without difficulty, the Agent SDK documentation notes that loading them all at once is usually faster. However, in Claude Code's default behavior, when the variable is unset and none of the limitations above apply, tool search is enabled and loading MCP tools is deferred until search, except for servers with alwaysLoad.

Here, you can explicitly set ENABLE_TOOL_SEARCH=auto: definitions will be loaded in advance while their combined volume is less than 10% of the context window, and search will be enabled once the threshold is reached. Another option is ENABLE_TOOL_SEARCH=false if you know the set will not grow. In that case, Claude Code will stop telling the model about server connection failures, as described above.

In other cases, check the operating conditions again when the environment changes:

• switch to Sonnet/Haiku/Opus 4.5 or newer if the session is using an older model;
• if the connection uses a nonstandard ANTHROPIC_BASE_URL, explicitly set ENABLE_TOOL_SEARCH=true only when the proxy itself passes through tool_reference blocks;
• make sure the deployment platform is not on the list of exceptions: Azure Foundry or older Google Cloud Agent Platform models.

If the conditions are met and search is not blocked by the settings, you can connect the MCP servers you need. Use alwaysLoad only for those whose tools are needed on every turn of the session; leave the others to load through search.

If you need access to AI models through Ailoot, take a look at Ailoot.