Blog / 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

Official docs: Claude Code MCP documentation, 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.

• 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.

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.
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.
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.

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"}

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.

Go deeper: Tool search in other apps, How Codex finds MCP tools, MCP context window usage.

Back to 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.