---
title: How to Make Your API and MCP Server Agent-Ready (2026)
description: Agent-ready means agents find your tools, understand them, act correctly and recover. What failed in real Claude Code and Codex runs, and how to fix it.
canonical: https://spiritroom.app/guides/agent-ready-tools/
published: 2026-10-21
updated: 2026-10-21
---

> Markdown version of https://spiritroom.app/guides/agent-ready-tools/ for agents. Index: /llms.txt

[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

**TL;DR**

- **Agent-ready** means an agent can *discover* your tools, *understand* them, *act* correctly and *recover* from errors, in the agent apps your users actually run.
- **Discovery fails silently.** Codex never found a 99-tool server's tools in 8 of 80 live runs (5–19%), even though the server listed them.
- **Size breaks the direct path.** One default list call was 46,253 tokens; Claude Code refused those results 40 times, in 23 of 40 runs (42–71%), because they exceeded its 25,000-token limit.
- **Errors can cost more than the job.** One malformed ID produced a 12,689-token error that told the agent to stop and ask a human.
- **Fixes are measurable.** A short server instruction plus a `get_instructions` tool made Claude Code and Codex fetch the right playbook first in 24 of 24 runs each (86–100%), on a mock of the same server.
[What agent-ready means](#what)[Discover](#discover)[Understand](#understand)[Act](#act)[Recover](#recover)[Checklist](#checklist)[How to prove it](#prove)[All guides](#guides)[How we measured](#how-we-measured)[FAQ](#faq)

**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 agent-ready model, with what we saw fail on a 99-tool production MCP server (16 Oct 2026)

| Step | The agent has to… | What failed in recorded runs |
| --- | --- | --- |
| **1. Discover** | find your server and the right tool for the request | Codex never found the tools in 8 of 80 live runs and tried a browser instead |
| **2. Understand** | know what the tool does, what it needs and where to start | Agents read a UI label (“To review”) as an API stage and gave wrong counts |
| **3. Act** | call it with the right arguments and get a usable result | A 46,253-token default result was refused by Claude Code 40 times |
| **4. Recover** | fix its own mistakes and know when to ask the user | A malformed ID returned a 12,689-token error that said “ask a human” |

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.

What the same 99-tool list (68,286 tokens) added to the first model request, “say hi” prompt, 16 Oct 2026, each app's own token count

| Agent app | How it loads MCP tools | Extra tokens in the first request |
| --- | --- | --- |
| Codex 0.161.0 | Hidden behind code mode; the model searches tool metadata | +0 |
| Claude Code 2.1.301, default | Tool search: names only, definitions loaded on demand | +1,715 |
| OpenCode 1.18.34 | All definitions, on every request | +73,415 |
| Claude Code 2.1.301, tool search off or behind a custom API URL | All definitions | +107,541 |

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](/guides/how-agents-load-mcp-tools/), [how many MCP tools is too many](/blog/how-many-mcp-tools-is-too-many/), [how to optimise your MCP tools by knowing how agents call them](/blog/optimise-mcp-tools-for-agents/).

## 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](/guides/onboard-agents-through-mcp/), [make the agent read your playbook first (24 of 24 runs)](/blog/get-instructions-first-24-of-24/), [do agents read MCP server instructions?](/blog/do-agents-read-mcp-server-instructions/).

**Find where agents fail on your tools. Measure what fixes it.**

Bring your MCP server, CLI or API and the jobs your users need done. We run real agents against them, read every call, and hand back measured gaps and fixes.

[Test your MCP →](/#contact)

## 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](/guides/tool-results-and-errors-for-agents/), [how to reduce MCP tool response size](/blog/reduce-mcp-tool-response-size/), [which half of an MCP result the model sees](/blog/mcp-structuredcontent-vs-text/).

## 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](/blog/error-messages-for-ai-agents/), [why AI agents call the wrong tool](/blog/why-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.

Agent-ready checklist for MCP servers and APIs

| Step | Check | Why (measured) |
| --- | --- | --- |
| Discover | Tool names and the first line of each description use the user's words | Search-based apps pick tools from names and snippets; Codex missed the tools in 8/80 runs |
| Discover | You know what each target app loads up front | The same list cost +0 to +107,541 tokens depending on app and settings |
| Understand | Server instructions are under ~2,000 characters, most important rule first | Claude Code kept 4,096 characters, Grok Build about 2,048 |
| Understand | A `get_instructions` entry point with a hint the agent can see | 24/24 first calls in Claude Code and Codex vs 1/24 and 9/24 without a hint (mock) |
| Understand | One vocabulary across UI, API fields and counts | A mixed “To review” label produced wrong per-stage answers |
| Act | Default results are small (start with a ~5,000-token budget) and paged | A 46,253-token default was refused in 23/40 Claude Code runs |
| Act | Tools that spend money are annotated as destructive and not idempotent | Two credit-spending tools were marked non-destructive |
| Recover | Errors name the field, the expected value and the next step | A 12,689-token error buried a one-field mistake |
| Recover | Refusals say whether to retry, fix the arguments or ask the user | Every refusal said “ask a human”, even a retryable conflict |
| Prove | A suite of real jobs runs in the apps your users use, scored as pass/N | The only way the failures above showed up |

## 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](/guides/test-mcp-servers-with-agents/), [how to measure MCP server quality](/blog/measure-mcp-server-quality/).

## All guides

- [Test and measure MCP servers with real agents](/guides/test-mcp-servers-with-agents/)

  Methods, metrics and pass rates for agent testing, from scorecards to confidence ranges.
- [How agent apps load tools and context](/guides/how-agents-load-mcp-tools/)

  What Claude Code, Codex, Grok Build and OpenCode actually show the model, measured from the wire.
- [Agent-ready MCP and API design](/blog/optimise-mcp-tools-for-agents/)

  Names, descriptions, annotations and workflows, tied to failures we recorded.
- [Tool results and errors agents can use](/guides/tool-results-and-errors-for-agents/)

  Response size, error messages, refusals and next-step hints.
- [Onboarding agents through the MCP server](/guides/onboard-agents-through-mcp/)

  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](/guides/agent-experience-ax/)

  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.

## FAQ

### What does agent-ready mean for an API or MCP server?

An API or MCP server is agent-ready when an AI agent can find the right tool for a user's request, understand what it does and what it needs, call it correctly, and recover when something fails, without a human stepping in. It is a property you measure by running agents on real jobs, not a badge you get from a spec check.

### Is a good OpenAPI spec enough to make my API agent-ready?

No. A complete spec is necessary, but agents meet your tools through an agent app that decides what the model sees. In our captures the same 99-tool list cost 0 extra tokens up front in Codex, about 1.7k in Claude Code with tool search and 73k in OpenCode 1. Discovery, result size and error handling all behave differently per app, so you have to test in the apps your users run.

### How do I test whether my MCP server works with AI agents?

Write down the real jobs your users need done, with expected answers. Run each job several times in the agent apps your users use (for example Claude Code and Codex), record every tool call and result, score the answers against ground truth, and read the failures by hand. Report pass rates as k/N with a confidence range, never a single run.

### How many tools can an MCP server have before agents get worse?

There is no single number, because agent apps load tools differently. A 99-tool list measured 68,286 tokens. Some apps load all of it on every request, others search for tools on demand. Once the server told agents where to start, a 4-tool and a 99-tool version scored the same in our mock test (12/12 and 24/24).

### Do AI agents read MCP server instructions?

Yes, but not all of them. Claude Code put the first 4,096 characters into its system prompt, Grok Build about 2,048, Codex repeated them in front of every tool description, and OpenCode kept them in full. Keep instructions under about 2,000 characters and put the most important rule first.

**Find where agents fail on your tools. Measure what fixes it.**

Bring your MCP server, CLI or API and the jobs your users need done. We run real agents against them, read every call, and hand back measured gaps and fixes.

[Test your MCP →](/#contact)

## Keep reading

- Related[How to optimise your MCP tools by knowing how agents call them](/blog/optimise-mcp-tools-for-agents/)
- Related[How to test an MCP server with real AI agents (guide)](/guides/test-mcp-servers-with-agents/)
- Related[How agent apps load MCP tools: what the model sees (guide)](/guides/how-agents-load-mcp-tools/)
- Related[Tool results and errors for AI agents (guide)](/guides/tool-results-and-errors-for-agents/)
- Related[How to onboard AI agents through your MCP server (guide)](/guides/onboard-agents-through-mcp/)
- Related[Agent experience (AX): how to measure it (guide)](/guides/agent-experience-ax/)
- In this guide[Agent-ready tools glossary](/glossary/)