Spirit Room / Guides

How to make your MCP server or API agent-ready, with proof

Your MCP server can pass every protocol check and still lose the agent. On a 99-tool production server that returned correct data on every probe, agents missed the tools, choked on oversized results and stopped on a typo. This guide maps what agent-ready actually takes, step by step, with the numbers.

Leonid Bugaev · Published 21 Oct 2026

Agent-ready tools are MCP servers, APIs and CLIs that AI agents such as Claude Code, Codex, Grok Build and OpenCode can find, understand, use correctly and recover from. Most checklists stop at the spec. This hub goes one step further: every recommendation links to what we measured when real agents ran real jobs.

What agent-ready means: four steps every agent takes

When a user asks an agent to do something with your product, the agent goes through the same four steps every time. Each step fails in its own way, and each one needs a different fix.

The server in these runs returned correct data on every direct probe. Nothing was “broken” in the usual sense. The failures came from how the tools met the agent.

1. Discover: can the agent find your tool?

Agent apps don't all show the model your tool list. Some send every tool definition up front. Others show a few names and let the model search for the rest. What the model sees first decides whether your tool is found at all.

Searching keeps context small but adds a new failure: the search can miss. That is what happened in the 8 Codex runs above. Use the words your users say in tool names and the first line of each description, and test paraphrases of the same job.

Go deeper: how Claude Code, Codex, Grok and OpenCode load MCP tools, how many MCP tools is too many, how to optimise your MCP tools by knowing how agents call them.

2. Understand: does the agent know where to start?

A tool that is found can still be misread. Two things matter most: the meaning has to be visible in the part of the description the agent actually sees, and your vocabulary has to match across the product. When a list counted leads under a UI label that mixed two API stages, agents in all three tested apps gave that mixed number as the answer to a per-stage question in some runs.

For multi-step jobs, tell the agent where to start. On a mock of the same 99-tool server, adding a get_instructions(job) tool did little on its own: Claude Code called it first in 1 of 24 runs (1–20%) and Codex in 9 of 24 (21–57%). With a one-line hint in the server instructions, a flag that keeps the tool loaded in Claude Code and the hint repeated in tool descriptions, both called it first and followed its first step in 24 of 24 runs (86–100%).

Go deeper: onboarding agents through the MCP server, make the agent read your playbook first (24 of 24 runs), do agents read MCP server instructions?.

3. Act: is the result small and clear enough to use?

Agents usually call a tool with default arguments first. On the production server, the default list call returned 46,253 tokens, more than half of it the same data sent twice (once as text, once as structured content). Each agent app handled that differently:

• Claude Code refused results over its 25,000-token limit and saved them to a file. That happened to 40 results in 23 of 40 runs, and the model then made 138 extra file reads and searches to recover.
• Codex cut what the model's code printed to about 10,000 tokens. The model recovered by filtering, sometimes calling the server again for the same data.
• OpenCode kept the first 51,200 bytes and saved the rest.

Page by default, return compact records with a total and a cursor, and say what to do next. Then measure what the model actually receives, not just the bytes on the wire.

Go deeper: tool results and errors agents can use, how to reduce MCP tool response size, which half of an MCP result the model sees.

4. Recover: can the agent fix its own mistakes?

Agents make argument mistakes all the time. What the error says decides whether the agent fixes the call in one step or stops the job. On the production server, one malformed ID returned the tool's entire input specification, 12,689 tokens, and every refusal, including a routine retry, carried the same instruction: a human must decide before you continue.

A useful error names the failing field, the expected value, where to get a valid one, and whether a retry makes sense. Keep “ask the user” for real decisions, like spending money.

Go deeper: how to write error messages for AI agents, why AI agents call the wrong tool.

The agent-ready checklist

Use this as a starting point. The thresholds are our design budgets from these runs, not guarantees for every agent app.

How to prove your tools are agent-ready

Spec linters and protocol debuggers check that your server works. They can't tell you whether an agent finishes the job. For that you need runs:

1. Write the jobs. Real requests your users make, with expected answers taken from fixed probes of your own data.
2. Run the apps your users run. Same prompt, several runs each, default settings. Record the agent version and model.
3. Record every call. Discovery, arguments, results, errors, retries and the final answer.
4. Score, then read. Score against the expected answers, then read the failures and a few passes by hand to check the scorer.
5. Report pass/N with a range. 34 of 40 is 71–93% at 95% confidence. One good run proves nothing.

Go deeper: how to test an MCP server with real AI agents, how to measure MCP server quality.

All guides

• Test and measure MCP servers with real agents

  Methods, metrics and pass rates for agent testing, from scorecards to confidence ranges.

• How agent apps load tools and context

  What Claude Code, Codex, Grok Build and OpenCode actually show the model, measured from the wire.

• Agent-ready MCP and API design

  Names, descriptions, annotations and workflows, tied to failures we recorded.

• Tool results and errors agents can use

  Response size, error messages, refusals and next-step hints.

• Onboarding agents through the MCP server

  Getting the agent to the right playbook on its first call, with nothing installed on the agent side.

• Agent experience (AX) and the business case (coming soon)

  How to measure agent experience and what it costs you.

How we measured

• Live, read-only (16 Oct 2026). A 99-tool production MCP server, one workspace. Codex CLI 0.161.0 (gpt-6-astra) and Claude Code 2.1.301 (claude-opus-5-5), 8 read-only jobs × 5 runs, two rounds (80 runs each). Every call went through a proxy that only forwarded read tools; 0 write attempts. Answers were scored against fixed probes of the same data and every failure was read by hand.
• Server measurements. Direct tool calls with fixed inputs, repeated 3 times with identical results. Sizes in o200k_base tokens.
• First-request loading. The first request each app sent to its model, captured before any model ran, with and without the 99 tools. Counts are each app's own usage figures; single runs.
• Onboarding experiment (mock, 18 Oct 2026). A local stand-in serving the same 99 tool definitions, 232 runs of Claude Code 2.1.302 and Codex 0.161.0. Mock results show how agents start a job, not live outcomes.
• Ranges are 95% Wilson intervals. Results describe these versions on these dates; agent apps change often.