A new study from Spirit Room exposes a critical friction point in the current agentic landscape: Model Context Protocol (MCP) tool discovery is broken. Published on October 16 and updated on October 19, 2026, the report by Leonid Bugaev details how leading agentsβ€”Claude Code 2.1.301, Codex 0.161, OpenCode 2.0.31, and Grok Build 1.0.60β€”failed to locate or correctly utilize tools in a production server containing 99 valid endpoints. The findings challenge the assumption that simply exposing tools via MCP guarantees agent usability, revealing that metadata truncation, naming conventions, and output size limits create significant barriers to automation.

The Discovery Gap in Agent Architectures

The study highlights that different agents employ vastly different strategies for tool discovery, leading to inconsistent reliability. For instance, Claude Code initially exposed tool names in a reminder of approximately 1,258 tokens, requiring the model to call a specific ToolSearch function to load full definitions. In contrast, OpenCode 1.x loaded all 99 definitions, consuming 63,245 tokens per request, while OpenCode 2.0.31 started with a partial catalog of just 16 tools, forcing the model to search for the rest. Codex 0.161, operating in code mode, relied on the model to filter ALL_TOOLS metadata, a process that frequently resulted in 56,619 tokens of data being truncated, making precise selection difficult.

Naming Conventions and Metadata Limits

A major takeaway is that tool names must align with the specific lexical paths agents use to search. The report argues that abstract names like ledger_dispatch often fail when users or models search for terms like bill or invoice. The recommended fix is descriptive naming such as invoice_send, paired with a description that includes synonyms. Furthermore, because many clients truncate descriptions to roughly 120 characters in the initial catalog view, essential prerequisites and constraints must appear in the first sentence. Boilerplate phrases like This tool provides functionality that allows waste valuable token budget and obscure the tool’s actual utility before the agent even selects it.

Output Size and Context Poisoning

The research also quantifies the impact of oversized tool outputs on agent performance. A default list result from the production server measured 46,253 tokens, triggering refusals and truncation in several environments. Claude Code 2.1.301, for example, saves results over 25,000 tokens to a file, requiring an additional recovery step for the agent to access the data. Codex 0.161 has a default limit of about 10,000 tokens per execution output, while OpenCode caps outputs at 2,000 lines or 51,200 bytes. The study suggests a design budget of 5,000 tokens for tool responses, emphasizing that returning less noise is more efficient than forcing agents to parse massive JSON blobs or recover from truncated context.

Key Takeaways

  • Discovery is not guaranteed: Agents like Codex and Claude Code use different search mechanisms (BM25, lexical matching, or code filtering), requiring MCP servers to optimize for multiple discovery paths.
  • First-line importance: Due to metadata truncation (e.g., ~120 chars in OpenCode 2), the most critical information must be in the very first sentence of the tool description.
  • Token budgets matter: Large outputs (46k+ tokens) cause truncation and recovery loops; developers should aim for <5,000 tokens and use pagination with cursors.
  • Name for intent: Use user-facing vocabulary (e.g., invoice_send vs. ledger_dispatch) to match the model's internal search queries.

The Bottom Line

Spirit Room’s data proves that MCP integration is not a set-and-forget protocol; it requires rigorous, agent-specific optimization of metadata and output shapes to prevent silent discovery failures.