Tool Search and Context Window Management

The context window tax of too many connected servers

Every MCP server you connect adds its tool schemas to Claude's context window at session start. A single server with twenty tools can consume thousands of tokens before you type your first prompt. Connect ten servers and you have meaningfully reduced the context budget available for your actual work. This was the hidden cost of MCP integrations before tool search was introduced.

How tool search works

Tool search changes what loads at session start. Instead of loading every tool's full schema upfront, Claude Code loads only two things: tool names and server instructions. Claude uses a built-in ToolSearch tool to find relevant schemas when a task needs them. Only the tools Claude actually calls during a session consume schema tokens in context.

From your perspective, MCP tools work exactly as before — Claude uses them when relevant, asks for permission on first call, and shows results in the session. The deferred loading is invisible during normal use. The practical difference is that connecting ten servers has minimal context impact instead of a significant one.

Tool search is enabled by default. Claude Code does not impose a fixed per-server tool cap; the practical limit is your context window budget for the session.

ENABLE_TOOL_SEARCH: five modes

Control tool search behavior with the ENABLE_TOOL_SEARCH environment variable:

When tool search is off by default

Two environments disable tool search by default. On Google Cloud's Agent Platform, tool search is off because most GCP deployments route through the platform's own API layer. On non-first-party ANTHROPIC_BASE_URL hosts — API proxies, local model routers — tool search is off because most proxies do not forward the tool_reference blocks that tool search requires.

If you are running on GCP or through a proxy and want tool search, set ENABLE_TOOL_SEARCH=true explicitly. Be aware that this requires a model that supports tool_reference blocks. Haiku models do not support tool search anywhere. On GCP, Claude Sonnet 4.5 and Opus 4.5 are the minimum supported versions.

In configurations without tool search — GCP without ENABLE_TOOL_SEARCH=true, custom ANTHROPIC_BASE_URL — Claude Code uses the WaitForMcpServers tool instead of ToolSearch to ensure servers have finished connecting before Claude proceeds. You can also disable the ToolSearch tool directly via a deny rule in your permission settings.

alwaysLoad: tools that must be upfront

Some tools need to be visible to Claude on every turn without a search step — a tool Claude uses as part of every response, or one whose absence would cause Claude to miss a critical capability. Set alwaysLoad: true on a server entry to load all of that server's tools upfront regardless of the ENABLE_TOOL_SEARCH setting:

{"type": "http", "url": "https://mcp.example.com/mcp", "alwaysLoad": true}

When alwaysLoad is true, Claude Code also blocks session startup until that server connects — capped at the standard 5-second connect timeout. All other servers continue to connect in the background. Use alwaysLoad sparingly: each upfront tool consumes context that would otherwise be available for your conversation.

Individual tools can also be marked for upfront loading using the anthropic/alwaysLoad: true annotation in the tool's _meta object. This is useful when only a subset of a server's tools need to be upfront.

Writing effective server instructions

When tool search is enabled, Claude decides whether to search for tools from a particular server based on the server's instructions field. This field is the signal that tells Claude when your tools are relevant to the current task. Think of it as guidance for when to search, not a description of what the tools do:

• Effective: "Use these tools when the user asks about database queries, schema exploration, or SQL optimization."
• Less effective: "This server provides tools for database access including query, schema, and index management."

Claude Code truncates both tool descriptions and server instructions at 2,048 characters. Put the most critical information at the start of both fields — if your description is truncated, the end is what gets cut.