Spirit Room / Guides

How Claude Code, Codex, Grok and OpenCode load your MCP tools: what the model actually sees (2026)

You write one tools/list. Your users run it through different agent apps, and each one shows the model something different: sometimes just names, sometimes nothing until the model searches, sometimes every definition on every request. If you design tools without knowing which, you're guessing.

Leonid Bugaev · Published 21 Oct 2026

The five strategies at a glance

We connected the same 99-tool MCP server, a recording of a production server's tools/list (68,286 tokens of definitions), to five agent app setups and captured what each sent to its model.

The further right, the cheaper the first request and the more the model depends on searching with the right words. The per-app token costs are in how many MCP tools is too many.

Claude Code: names first, then select

With a normal login, Claude Code's tool search was on. The first request was 17,564 tokens and carried none of the 99 MCP tools, only built-ins, ToolSearch and a placeholder. A reminder in the first message listed the deferred tools by name only. The model picked three tools from the names alone and asked ToolSearch to select them; the next request carried just those three definitions, and it called the right one.

Two consequences: tool names carry most of the weight, and a long description's tail is never seen by the search. A lab setting that proxied the model endpoint turned tool search off and loaded everything: 143,357 first-request tokens instead of 22,446 with it forced back on. More in Claude Code tool search, seen from the wire.

Codex: search in code

Codex 0.161 in its default code mode sent the model one exec tool with a 6,471-token description and no MCP tool names; our server's name appeared nowhere. The model wrote a JavaScript filter over ALL_TOOLS; the first returned 56,619 tokens, cut to 11,244, and two narrower filters followed before the right call. The whole turn used 137,344 input tokens, mostly cached.

When the model doesn't think to search, it never sees the tools: 6 of 40 live runs on a production server ended with “no connector available”. Details in how Codex finds MCP tools.

Grok Build: BM25 search

Grok Build's first request had 28 tools, including search_tool and use_tool, and no MCP tool names. A reminder after the user's question listed connected servers and tool counts only. The model searched with keywords from the question; the client ran BM25 and returned the full input schema of every hit, 4,957 tokens for the first search. Four searches added 14,762 tokens to the history, re-read on every later request. It found the right tool on the first search.

One trap: a project-level server in an untrusted folder wasn't started in headless mode, with no warning. The model searched 9 times, found nothing, and spent 17 turns reading files. Pass --trust or trust the folder.

OpenCode 1 and 2

OpenCode 1.18.34 sent all 99 definitions, 63,245 tokens, with every model request, not just the first. In 40 live runs it averaged 3.7 requests per question, so about 230k tokens of tool definitions per question. OpenCode 2.0.31 changed this: it showed a catalog of 16 of the 99 tools, cheapest schemas first. A tool with a heavy schema may not be in that catalog, so keep the tools agents need first small, such as a one-argument get_instructions.

Beyond tools: instructions and results

Loading differs for everything else the server sends:

• Server instructions: Claude Code cuts them at 4,096 characters, Grok Build at about 2,048, Codex prepends them to every tool description, OpenCode passes them in full. See do agents read your MCP server instructions?
• Dual results: Claude Code shows the model only structuredContent, OpenCode only the text, Codex both. See structuredContent or text?
• Big results: Claude Code refused results over its limit 40 times in 23 of 40 live runs and read them back from files.
• Prompts and resources: MCP prompts weren't visible to the model in any app; resources only in some. See which MCP channels agents use.

What this means for your tools

1. Names in users' words. Claude Code chooses from names alone; the others search names and descriptions with the user's words.
2. The first line of each description says what the tool does and when to use it. It's what search shows and what truncation keeps.
3. Weight, not count. In eager apps every token is paid on every request; in Grok every search hit returns the full schema. Trim the heaviest schemas first.
4. A small, obvious place to start, such as get_instructions, that every app shows or finds: one enum argument, a hint in instructions and descriptions. See how to onboard AI agents through your MCP server.
5. Test in each app your users run. Strategies change between versions; re-check after updates. See how to test an MCP server with real AI agents.

Guides in this section

• How many MCP tools is too many?

  What the same 99 tools cost in each app, and a 4-tool vs 99-tool test.

• How Codex finds MCP tools

  Code mode, ALL_TOOLS, and the 6 of 40 runs that never found the tools.

• MCP prompts, resources and tools: which agents use

  Which MCP channels reach the model in each app.

Go deeper: What's in an agent's context window, Claude Code tool search, seen from the wire, Grok Build and MCP, OpenCode 1 vs OpenCode 2, What one MCP task costs, MCP tool-list token calculator.

Back to the overview: agent-ready tools.

How we measured

• Captures: a local mock serving a production server's recorded 99-tool list; each app's traffic to its model captured with a process-scoped proxy and a temporary certificate trusted only by that process, 16 Oct 2026 (Claude Code and Codex 13:03–13:07, Grok Build 13:19–13:24, UTC+3). Headers redacted; sizes in o200k_base; per-request input from each provider's usage report.
• Up-front deltas: the first request each app sent with and without the server connected, stopped before any model ran, 16 Oct 2026.
• Live runs: 8 read-only jobs × 5 runs per app on the production server, through a read-only allowlist proxy, 16 Oct 2026.
• Limits: one server, one version and default model per app, captured once per configuration. Apps change their loading between versions.