MCP Tool Search
Loading tool details only when they are needed. See what it is, how it works, how it is used and what to watch for, with pictures and examples.
What it is
Tool Search saves room in the . MCP can bring many tools, and each tool has a long description called a . At the start, loads only the tool names and the server instructions. When decides to use a tool, it fetches that tool's full schema then, so servers you are not using take up little .
How it works
-
Session starts with tool names only
-
Claude needs a certain MCP tool
-
Claude searches and loads its schema
-
Claude calls the tool as usual
How to use it
-
/contextshows what uses space; deferred tools are marked as deferred or loaded on demand.
-
ENABLE_TOOL_SEARCH=false claudeturns tool search off and loads every MCP tool up front.
-
ENABLE_TOOL_SEARCH=auto:5loads tools up front until they pass 5% of the context window, then switches to search.
-
"alwaysLoad": truein a server's
.mcp.jsonentry, keeps that server's tools always visible.
Watch out
Tool search is on by default, but it works only on newer such as Claude Opus 4, Sonnet 4, Haiku 4.5 and later; on older models all tools load up front. Every tool you load up front with alwaysLoad uses context on every turn, so use it for only a few tools. Server authors should write clear, short instructions, because Claude reads them to know when to search for their tools.
Related terms
Original and official docs
This page explains the term in plain words. The original is the authority: if they differ, follow the original.
- See this term in the originalClaude Code Docs — Glossary Anthropic · checked 2026-10-19
- Anthropic — Claude Code docs: Connect Claude Code to tools via MCP — Scale with mcp tool search(opens in a new window)
- Anthropic — Claude Code docs: Connect Claude Code to tools via MCP — Configure tool search(opens in a new window)
- Anthropic — Claude Code docs: How Claude Code works — When context fills up(opens in a new window)