--- title: Claude Code Tool Search, Seen From the Wire description: Captured Claude Code traffic: 113 tool names only, select: by exact name, 3 definitions loaded on demand. What tool search means for your MCP tool names. canonical: https://spiritroom.app/blog/claude-code-tool-search-explained/ published: 2026-10-21 updated: 2026-10-21 --- > Markdown version of https://spiritroom.app/blog/claude-code-tool-search-explained/ for agents. Index: /llms.txt [Blog](/blog/) / [How agents load MCP tools](/guides/how-agents-load-mcp-tools/) # Claude Code tool search, seen from the wire: the model picks your tool from its name The docs tell you how to turn tool search on. This is what it looks like on the wire, with a 99-tool server: what the model sees, how it chooses, and what that means for your names and descriptions. Leonid Bugaev · Published 21 Oct 2026 **TL;DR** - **Nothing up front:** the first request had 13 tools and none of the 99 MCP tools. Debug log: “0/113 deferred tools included”. - **Names only:** the model got a reminder listing 113 tool names (about 1,258 tokens), no descriptions. - **Picked by name:** the model called ToolSearch with `select:` and 3 exact names. No keyword search ran. It chose the right tool. - **Loaded on demand:** only those 3 definitions, about 573 tokens each, were sent in the next request. - **alwaysLoad** on one start-here tool cut the cost before the first call from 15–28k to 6–7k tokens. [What's on the wire](#wire)[How the model chooses](#choose)[What it means for your tools](#means)[alwaysLoad and searchHint](#alwaysload)[How we measured](#how-we-measured)[FAQ](#faq) Official docs: [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp), including the section for MCP server authors. Below is what the traffic showed. ## What's on the wire Claude Code 2.1.301, normal login, a stub server with 99 tools, one prompt that needed one of them. 1st request: 13 tools, 0 MCPreminder: 113 namesToolSearch select: 3 namesnext request: +3 definitionsright tool called - **First request:** 13 tools, 17,564 tokens. Core tools, ToolSearch, and a `DeferredToolPlaceholder` stub. None of the 99 MCP tools. - **The reminder:** “The following deferred tools are now available via ToolSearch. Their schemas are NOT loaded…”, then 113 names: 99 MCP tools and 14 built-ins. About 1,258 tokens. - **The search:** `ToolSearch` with `select:` and 3 full tool names. The client answered with `tool_reference` blocks. - **The load:** the next request carried those 3 definitions in full, about 573 tokens each, 16 tools in total. Then the model called the right tool. **See what Claude Code sees of your server.** We capture the real requests agent apps send with your MCP server attached, and show which of your tools get found, loaded and called. [Capture your MCP →](/#contact) ## How the model chooses It picked from the names. No keyword search ran, so descriptions played no part in which tools got loaded. Descriptions matter after loading, when the model decides which loaded tool to call and how. When keyword search does run, it may not read all of a long description. In our marker tests, a word near the end of a long description wasn't found by search. Default max results was 5. ## What it means for your tools 1. **Names carry the decision.** Use the words users use: `list_invoices`, not `ar_docs_query`. See [name tools the way users talk](/blog/mcp-tool-naming-for-agent-search/). 2. **Put the key words first** in each description, so a search that reads only the start still matches. See [put the meaning in the first line](/blog/mcp-tool-descriptions-first-line/). 3. **Don't count on descriptions for discovery.** If two tools have similar names, the model may load the wrong pair. 4. **Tool count costs little here:** about 1.7k extra tokens for 99 tools with tool search on. It costs much more in apps that preload: see [how many MCP tools is too many](/blog/how-many-mcp-tools-is-too-many/). ## alwaysLoad and searchHint In a later test we added one `get_instructions` tool with: ``` "_meta": {"anthropic/alwaysLoad": true, "anthropic/searchHint": "start here, playbook, instructions, how to use"} ``` Without alwaysLoad *2–3 requests, 15–28k tokens* With alwaysLoad *1 request, 6–7k tokens* Tokens before the first MCP call. Claude found the tool either way; alwaysLoad saved a search round trip. Codex ignores the hint. More: [make agents read your instructions first](/blog/get-instructions-first-24-of-24/). **Go deeper:** [Tool search in other apps](/blog/claude-code-mcp-tools-not-found/), [How Codex finds MCP tools](/blog/how-codex-finds-mcp-tools/), [MCP context window usage](/blog/mcp-context-window-usage/). Back to [how agents load MCP tools](/guides/how-agents-load-mcp-tools/). ## How we measured - **Capture:** Claude Code 2.1.301 with a normal login, traffic recorded through a temporary, process-scoped proxy against a local 99-tool stub server; secrets redacted; one prompt. - **Tokens:** o200k\_base counts of the captured parts; the ~573 figure is one measured definition, used for all three. - **alwaysLoad:** from the instructions-first trial on a mock server, Claude Code 2.1.302, 18 Oct 2026. - **Limits:** one capture; Claude Code changes often. ## FAQ ### How does tool search work in Claude Code? MCP tools are deferred: the model first sees only their names in a reminder. When it needs some, it calls the built-in ToolSearch tool, either with keywords or with select: and exact names, and Claude Code then sends those definitions in full in the next request. ### Does Claude Code send all MCP tool definitions on every request? Not with tool search on. In our capture, unloaded MCP tools weren't sent at all; a placeholder kept deferred loading active, and only the 3 loaded tools were sent. ### Why does the tool name matter so much? Because the name is all the model sees before it decides what to load. In our capture it picked 3 tools from 113 names without running a keyword search. ### What does anthropic/alwaysLoad do? Set in a tool's \_meta, it makes Claude Code send that tool's definition up front. We used it on one get\_instructions tool: Claude called it in its first request, 1 model request and 6–7k tokens before the first call, instead of 2–3 requests and 15–28k. ### How do I turn tool search on or off? See the official Claude Code MCP docs. In our captures it was on by default with a normal login. **See what Claude Code sees of your server.** We capture the real requests agent apps send with your MCP server attached, and show which of your tools get found, loaded and called. [Capture your MCP →](/#contact) ## Keep reading - Up[How agent apps load MCP tools: what the model sees (guide)](/guides/how-agents-load-mcp-tools/) - Related[Claude Code can't see your MCP tools? Check the proxy and --tools settings first](/blog/claude-code-mcp-tools-not-found/) - Related[Write MCP tool descriptions agents actually see: put the meaning in the first line](/blog/mcp-tool-descriptions-first-line/) - Related[Name MCP tools the way users talk: how names-only, regex and BM25 search pick tools](/blog/mcp-tool-naming-for-agent-search/) - Related[Make the agent read your playbook first: 24 of 24 runs in Claude Code and Codex](/blog/get-instructions-first-24-of-24/)