Claude Code, Codex and OpenCode Find MCP Tools

A blog post on MCP optimization reports that a server with 99 tools returning correct data still failed to get agents to find and use the right tools across Claude Code, Codex, OpenCode and Grok Build. In the versions inspected, Claude Code 2.1.301 initially exposed tool names rather than full descriptions, OpenCode 2.0.31's initial catalog included 16 of the 99 tools with descriptions shortened to roughly 120 characters, Codex wrote code to filter tool metadata, and Grok Build used BM25 keyword ranking. The post recommends naming tools after user vocabulary (e.g. invoice_send instead of ledger_dispatch), front-loading purpose and constraints in the first line, and treating tool output as prompt design so agents can complete multi-step jobs.

Blog https://spiritroom.app/blog/ / MCP optimization 5 ways to optimize your MCP so agents find the right tools and finish the job If an agent cannot find your tool, the rest of your documentation cannot help. Once it finds the tool, every description, result and error helps shape what it does next. The lesson: design your MCP around the user's job, from discovery to completion. Then test that journey in the environments your users actually run. We repeatedly tested production read-only jobs with Claude Code, Codex and OpenCode, and inspected tool-discovery behavior across those agents and Grok Build. The server had 99 tools and returned correct data. Agents could still miss the tools, misread a result or take a long recovery path. 1. Match tool names to user intent and vocabulary The user describes a job. The model turns that request into a tool choice or a search query. Your tool has to be discoverable through the words the model chooses. In the versions we inspected, Claude Code initially saw tool names and selected definitions to load. Codex wrote code to filter tool metadata. Grok Build used BM25 keyword ranking. OpenCode 1.x loaded all definitions, while OpenCode 2 started with a partial catalog and searched for the rest. The model may understand synonyms; the search it invokes may still require a literal or lexical match. If a user asks to send a bill, the model might search for bill , invoice or send . A name like ledger dispatch makes that connection harder. A name like invoice send , paired with a description that includes “bill,” gives it clearer paths. Illustrative rewrite Before ledger dispatch “Dispatches the document to the configured recipient.” After invoice send “Email an invoice bill to a customer. Requires an existing invoice ID.” Start with the language in support questions, onboarding calls and actual user prompts. Include useful synonyms naturally. Avoid repeating unrelated keywords across every tool: that creates competing matches and makes selection harder. Test paraphrases of the same job, including requests that do not mention your product. Inspect the search terms and candidate tools the agent actually saw. A missed discovery is evidence of a broken path; it is not automatically proof that renaming a tool will fix it. 2. Put essential meaning in the first line An excellent description is useful only if the agent sees the relevant part. Before a tool is selected, a client may expose names alone, a short description snippet, or matching metadata. Full schemas may arrive later. In our OpenCode 2.0.31 capture, the initial catalog included 16 of the 99 tools, with descriptions shortened to roughly 120 characters. Claude Code 2.1.301 initially exposed names rather than full descriptions. There is no universal “first N characters” limit across agents. Inspect the catalog and search results in each environment. Make the opening stand on its own: User vocabulary + action . Essential prerequisite or constraint . “Email an invoice bill to a customer. Requires an existing invoice ID.” Put purpose and the constraint most likely to cause a wrong call before background detail. Keep longer examples and edge cases available after that opening. Do not spend the visible prefix on boilerplate such as “This tool provides functionality that allows…” For a multi-step job, a discoverable get instructions job tool can expose a compact playbook. But adding the tool alone does not make an agent call it. Its entry point must be visible in the channels that client actually loads. 3. Use every output to guide the next useful step Tool output is part of prompt design. The model reads it before deciding what to do next. A response that only dumps data leaves the agent to reconstruct your workflow. A useful response explains what happened, what it means for the job and how to proceed. Design the journey across successful calls, empty results, incomplete work and errors. Keep the guidance close to the data the agent will actually receive. Success: provide a conditional continuation { "summary": "20 of 47 matching invoices returned", "items": "…compact records…" , "next cursor": "c 20", "next step": "If you need the remaining invoices, call invoice list with cursor c 20." } Failure: explain the cause and the repair { "error": "groupId does not identify an available group", "next step": "Call groups list, choose the group matching the user's request, then retry with its ID.", "retryable": true } These are illustrative response bodies, not MCP protocol envelopes. Use your actual tool names and arguments. Mark tool execution failures appropriately, and put essential guidance in the representation your target client exposes to the model. Be explicit about completion too: “The draft is saved; no email has been sent” communicates a different state from “The invoice was sent.” A next step should advance the user's goal, not manufacture extra work or authorize an action the user did not request. Repeat critical workflow guidance where it is needed. If an agent can enter through several tools, each response can remind it of the relevant next step. The useful repetition is short and specific to the current state, rather than a full manual pasted into every result. Tool annotations can also describe read-only, destructive and idempotent behavior. Treat them as hints to the client, not guarantees of confirmation or retry behavior. Describe the real operation accurately, and make necessary workflow constraints explicit in tool behavior and results. 4. Keep results small and measure what the model sees A default list result from the production server measured 46,253 tokens in the captured response representation. Large outputs triggered refusals, truncation and extra recovery work. Returning less useful noise is usually easier than asking an agent to recover from an oversized result. - Page by default, with a total and a cursor. - Support useful filters and field selection. - Put the answer summary and continuation information first. - Leave verbose logs and records of the agent's own calls out unless requested. Use roughly 5,000 tokens as a starting design budget, not a compatibility guarantee. Also check bytes and lines. A token count does not map to a fixed byte count, and different clients cap different representations. What crosses the wire is not necessarily what reaches the model A tool can return both text content and structuredContent . Seeing the same data in both fields does not prove that the model received or paid for both. | Two-marker probe and source checks, 16 October 2026 | | |---|---| | Environment | Representation exposed to the model | |---|---| | Claude Code 2.1.301 | Structured content in the observed tool result. | | OpenCode 1.18.34 | Text content in the observed tool result. | | Codex 0.161 code mode | Whatever the script prints. Printing the raw object can expose both fields, subject to output truncation. | The MCP specification recommends a serialized text representation alongside structured content for backward compatibility. Replacing that text with only a short summary can deprive a text-only client of the records it needs. Preserve compatibility and optimize the data shape, then measure the actual model-visible result. Correction, 19 October: an earlier version treated duplicated wire fields as a general model-context cost and recommended removing the text copy. Our representation checks do not support that blanket advice. Wire size, model-visible tokens and billed usage must be reported separately. 5. Maintain tests for real jobs and inspect every call Tool-level checks tell you whether an endpoint accepts inputs and returns data. Your users need a job completed correctly. Maintain a suite of those jobs, with written expectations, and run it regularly and after changes to tools, models or agent apps. 1. Define the job and its expectations. Record realistic prompts, alternative phrasings, expected answers or state changes, and constraints such as “draft only” or “do not spend credits.” 2. Run the environments your users use. Record the agent version, model, settings, connection mode and relevant permissions. Verify that the tools reached the agent before interpreting a failure. 3. Capture the whole journey. Inspect discovery queries, candidate tools, call arguments, returned results, errors, retries and the final answer. A correct answer can still hide avoidable calls or a fallback outside the intended workflow. 4. Compare outcomes and efficiency. Score the written expectations. Track discovery success, wrong-tool calls, unnecessary steps, token usage and completion time. Review representative passing and failing traces to check the scorer itself. 5. Change one thing, rerun and keep regressions. Try a name, opening description or response hint against the same jobs. Keep failures as regression cases. Repeat runs because agent behavior varies; evaluate changes across the suite rather than trusting one successful demonstration. Consider a failed count question. Did the agent fail to discover the tool, choose the wrong filter, misread a state label, lose records through truncation, or report the answer incorrectly? Each cause calls for a different fix. A single pass/fail score will not tell you which one. Find where agents fail. Test what fixes it. Bring your MCP and the jobs your users need completed. Spirit Room simulates those jobs across selected models and agent apps, inspects the tool calls, and returns measured gaps and proposed fixes. Test my MCP https://spiritroom.app/ contact What actually failed in the recorded jobs? Discovery failures: Codex sometimes reported no connection and tried browser or plugin discovery instead of reaching the server through the MCP tool path. The initial request did not name the server, and the required tool search did not lead to an MCP call. This establishes a discovery gap; it does not establish that every such miss was caused by a wrong keyword. Answer failures after discovery: another failure involved a “To review” summary that combined qualified records with records still needing review. The agent treated that aggregate as the narrower category the user asked for, or concluded that the requested split was unavailable. Here the repair is consistent state names and explicit counts, rather than better discovery keywords. Elsewhere in the captures, oversized results forced agents to filter and retry or read saved files. A malformed ID produced a 12,689-token validation response. An ambiguous status summary merged categories that the user wanted counted separately. These are different failure mechanisms, and they should remain separate in the analysis. The dedicated Codex truncation follow-up showed recovery through filtering and correct final answers, so those captures establish extra work rather than explaining its scored answer failures. We also encountered setup failures: Grok Build did not start a project-configured server until the project was trusted; OpenCode 2's interactive and headless behavior differed. Those problems need a connection or harness fix, not a keyword rewrite. Method and limits The original research combined repeated production read-only jobs with direct server probes and request captures. Discovery captures also used a local stub serving the recorded production tool list; result-size probes and answer checks used the live server. OpenCode 2 had additional live interactive checks. We compared final answers with recorded ground truth and manually reviewed failures. Follow-up experiments used a local mock for controlled instruction changes. Coverage differed across agents; the results are not a ranking of models or agent products. Request captures used a process-scoped proxy. Saved evidence was redacted to remove credentials. Token-size comparisons used the o200k base tokenizer; provider-reported usage is labeled separately. A proxy can change client defaults, so settings and tool-loading behavior were checked rather than assumed. The production findings come from one server, with different default models in different agents. The original capture date was 16 October 2026; the instructions-first follow-up was 18 October. Agent versions and configuration matter. Proposed response examples in this article are design examples, not measured before/after improvements. Technical reference: discovery paths, output caps and configuration How each agent discovers and calls tools The server exposed 99 tools. The following snapshots show what the inspected versions revealed to the model. They illustrate the mechanism; they are not universal costs or guarantees. Configuration changes the discovery path - Claude Code: deferred loading exposed names first. Disabling tool search or removing ToolSearch caused eager loading in the tested setup. A custom model API endpoint also changed the default, so verify tool-search settings behind a gateway. - Codex: the initial model request in code mode did not name the server. Discovery depended on the model searching ALL TOOLS . A broad filter produced 56,619 tokens of metadata, which was truncated; narrower filters were easier to use. - Grok Build: the model chose a query for a local BM25 index. Search returned schemas as text in history. Confirm project trust and server startup before judging search quality. - OpenCode 1: all 99 definitions accounted for 63,245 tokens per model request in the captured setup. Eager loading avoids the search step but carries that context repeatedly. - OpenCode 2: the interactive catalog showed a subset with short descriptions and offered code-based search. The headless registry behavior differed in follow-up checks; its cause was not established. Observed output caps | Defaults in the inspected versions, 16 October 2026 | | | |---|---|---| | Agent | Limit | What happens beyond it | |---|---|---| | Claude Code 2.1.301 | 25,000 tokens; separate text-size handling also applies | Saves oversized results to a file for recovery. | | Codex 0.161.0 | About 10,000 tokens per exec output by default; adjustable per call | Keeps the start and end, omitting the middle. Code can filter before printing. | | OpenCode 1.18.34 / 2.0.31 | 2,000 lines or 51,200 bytes | Shows a prefix and saves the full output to a file. | | Grok Build 1.0.60 | 20,000 bytes, from source inspection | Shows a prefix and saves full output; this cap was not hit in our captured task. | These limits apply at different points in the path from server response to model context. Check the actual client output, including summaries and wrappers, rather than comparing raw server JSON with a nominal token limit. Find where agents fail. Test what fixes it. Bring your MCP and the jobs your users need completed. Spirit Room simulates those jobs across selected models and agent apps, inspects the tool calls, and returns measured gaps and proposed fixes. Test my MCP https://spiritroom.app/ contact Sources - Claude Code MCP documentation https://code.claude.com/docs/en/mcp : tool search, server instructions and result handling. - Codex code-mode runtime https://github.com/openai/codex/blob/main/codex-rs/code-mode-runtime/src/runtime/globals.rs : tool metadata available through ALL TOOLS . - Grok Build tool index https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-shell/src/session/tool index.rs and MCP documentation https://docs.x.ai/build/features/mcp-servers : keyword search and tool invocation. - OpenCode 2 MCP documentation https://opencode.ai/v2/docs/mcp-servers : code mode and tool discovery. - MCP tool specification https://modelcontextprotocol.io/specification/2025-06-18/server/tools structured-content : structured results, compatibility and tool annotations. - Spirit Room production captures, two-marker representation probe and manual failure reviews, 16 October 2026; controlled instructions-first mock experiments, 18 October 2026.