MCP Documentation Beyond Reference

About this paper

The most expensive assumption in the current wave of API operations is a quiet one: that AI will figure out how to use your MCP server. It won’t. Teams generate a server from their existing reference docs, watch an agent make one clean call in a demo, and ship — and then it meets production. A rate limit. A retry after a timeout. A read that comes back empty because the write hasn’t propagated. A call that needed a different call to happen first. The agent fails in exactly the places the demo never tested, because reference documentation describes the interface and agents don’t fail on the interface. They fail on the behavior.

This paper draws the line between the two and shows you how to close the gap. Reference tells an agent a tool exists, what it takes, and what comes back — necessary, and generated straight from your OpenAPI. Operational documentation tells it what a call does to the world, what its failures mean, whether a read after a write can be trusted, what must be true before it acts, and what a finished task looks like. A human developer reconstructs all of that from scattered prose and a support ticket or two; an agent has exactly the context you give it and no instinct to fall back on. So you get the five-part operational layer to attach to each tool, the AI-scrapable delivery half that makes it ingestible — markdown endpoints, llms.txt, predictable structure — the pipeline discipline that keeps it from rotting in a parallel system, a per-tool operational-context template you can drop into your repo, and a provider self-assessment. It is all APIs; we’re just writing documentation, at last, for a second audience that does not read.

What's inside

1. Reference describes the interface; operational docs describe the behavior
2. Side effects and safety — read-only, destructive, idempotent
3. Behavior under failure — timeouts, 429s, partial writes
4. The consistency model — because agents chain calls
5. Preconditions and sequencing — teach the agent what to ask
6. Worked task examples — walkthroughs, not endpoint samples
7. Deliver it so agents can read it — markdown, llms.txt, predictable structure
8. Flow it through the pipeline you already run
9. Anti-patterns and a provider self-assessment

What you get for $25.00