Documenting APIs for AI Agents: OpenAPI, llms.txt, and MCP, and When Each One Matters

The first reader of your API docs is increasingly not a developer. It is an agent: a coding assistant writing an integration, a chat assistant answering "how do I paginate this endpoint?", or an autonomous tool deciding whether your API can do the job at all. It reads fast, never skims, and believes everything — including the example that stopped working two releases ago.

The good news is that the formats agents need mostly already exist. The OpenAPI Specification, now at 3.2.1 as of September 2026, still defines itself as a standard interface that lets "both humans and computers" discover a service's capabilities "without access to source code." The Model Context Protocol gives agents a standard way to call tools and read resources. And llms.txt gives them a map of your prose docs. The mistake is treating these as competing choices. They answer different questions.

This guide covers what each format gives an agent, which one to build first for your situation, how to write descriptions an agent can act on, and the maintenance problem that multiplies once you publish the same API in four formats.

Four formats, four different questions#

An agent working with your API needs to answer a sequence of questions: what is this, what can it do, exactly how do I call it, and can I just do it for the user. Each format is best at one of them.

Two of these are machine contracts (OpenAPI and MCP), and two are prose (llms.txt and Markdown). Contracts prevent wrong calls; prose prevents wrong decisions. An agent with a perfect OpenAPI file but no prose will call your bulk endpoint correctly for a job it should never be used for.

How an agent moves through them#

flowchart TD
  Q["Developer asks an agent to integrate your API"] --> L["Agent reads llms.txt"]
  L --> D["Opens the Markdown quickstart and auth guide"]
  D --> O["Loads the OpenAPI description for exact shapes"]
  O --> C["Writes the integration code"]
  L --> M["Or: the host app has your MCP server installed"]
  M --> T["Agent calls your tools directly"]

The first branch is the common one today: an agent writing code against your API. The second is the one MCP opened up: an agent using your API as a tool. Most companies need the first branch before the second.

Which one to build first#

1. You have an API and no machine-readable description. Start with OpenAPI. It is the highest-leverage artifact because everything else can be derived from it: reference pages, SDKs, and the tool definitions for an MCP server later. Generate it from the code or route definitions rather than hand-writing it, so it cannot silently disagree with the implementation.

2. You have OpenAPI but agents still write bad integrations. Add prose. The failure is usually not the call shape but the judgment around it: rate limits, idempotency, which of three similar endpoints to use. Write Markdown pages for auth, errors, pagination, and the top workflows, and publish a clean .md version of each page.

3. Assistants give wrong answers about your product. Add an llms.txt that points at those Markdown pages, with notes that say what each page is for and a short section stating the facts assistants most often get wrong. The free llms.txt generator builds a first draft from your sitemap, and the llms.txt validator checks it against the spec. Our llms.txt guide covers the format in detail.

4. Your users want agents to act, not just write code. Build an MCP server. The protocol lets servers offer tools (functions the model can execute), resources (context and data), and prompts (templated workflows). If you are new to it, start with what an MCP server is.

5. Make everything discoverable. Link the pieces together so an agent that finds one finds the rest: reference the OpenAPI file from your docs, add rel="describedby" link headers pointing at llms.txt, and list your MCP server in your docs and llms.txt. We do this on our own site with a Link header on the homepage that points at an API catalog, the OpenAPI description, the MCP service docs, and llms.txt.

Writing descriptions an agent can act on#

Formats are the easy part. The words inside them decide whether an agent calls the right thing. Agents choose endpoints and tools almost entirely from names and descriptions, so the description fields in OpenAPI and MCP are the most important docs you write.

A few rules make the difference:

• Say when not to use it. The most valuable sentence in a description often points at the alternative.
• State side effects and costs. Charges, emails sent, rate-limit weight, irreversible deletes.
• Give the recovery path for each error. An agent that knows how to fix a 422 fixes it; one that does not retries it.
• Keep examples real. An example request an agent copies is a test case. If it no longer works, it is a bug in your docs.

For MCP specifically, remember that tool descriptions are model-facing instructions. The MCP specification itself warns that tool descriptions should be treated as untrusted unless they come from a trusted server; we covered the security side in MCP security risks explained.

The trap: four copies of the truth#

Publish the same API as OpenAPI, Markdown pages, llms.txt, and an MCP server, and you now have four descriptions of one set of behaviors. They start out in agreement. Then an engineer adds a required field, updates the handler and the OpenAPI annotation, and ships. The Markdown quickstart still shows the old request. The llms.txt note still says "no auth required for sandbox." The MCP tool description still describes last month's defaults.

None of this fails a build. The OpenAPI file is valid, the Markdown renders, the llms.txt parses, the MCP server starts. Every artifact is well-formed and one of them is wrong, and the agent has no way to know which. That is documentation drift multiplied by the number of formats, and it is why generating contracts from code matters so much: a generated OpenAPI file cannot drift from the routes it was generated from. Prose can, and does.

The practical defense is to decide which artifact is the source of truth for each fact. Shapes come from code. Everything else — the judgment, the workflows, the "use this, not that" — lives in prose that has to be reviewed whenever the code it describes changes. A docs-as-code workflow gets you the review; it does not tell you which pages a given change made false.

Keeping the prose in sync with the code#

That last gap is where Moxie Docs fits. It indexes your GitHub repository into living, source-cited documentation, flags docs that have fallen behind the code, and opens reviewable pull requests to bring them back — it never merges for you. Coding agents get the same context through the Moxie MCP server, so an agent changing an endpoint can see which docs describe it before it commits, and call moxie.review_change to catch the docs that change makes false. Try it on one repository with the free plan, no card required.

Measuring whether it's working#

• Agents write working integrations on the first try. Ask a coding agent to call your three most-used endpoints from scratch; count the corrections it needs.
• The OpenAPI file matches production. Contract tests or a schema diff in CI catch the gap between the description and the handlers.
• Every example request runs. Execute the examples in your docs against a sandbox on a schedule.
• Assistants answer your top support questions correctly. Ask two or three assistants the five questions your support team hears most and check what they cite.
• Docs change in the same PR as the endpoint. If an endpoint changed this month and no doc did, look at it.

None of these need a dashboard.

Frequently asked questions#

How do I make my API documentation AI-friendly?#

Publish a machine-readable OpenAPI description generated from code, clean Markdown versions of your guides, and an llms.txt file that maps the important pages. Then rewrite descriptions so each one says what the endpoint does, when not to use it, its side effects, and how to recover from its errors. Agents choose what to call almost entirely from names and descriptions.

Do I need an MCP server if I already have an OpenAPI spec?#

Not always. OpenAPI is enough for agents that write code against your API. An MCP server matters when you want agents inside apps like Claude or an IDE to call your API directly on a user's behalf, with tools designed around user tasks rather than one tool per endpoint.

Should AI agents read llms.txt or OpenAPI?#

Both, for different jobs. llms.txt is a curated map of your prose docs that helps an agent understand what your product is and which pages to read. OpenAPI is an exact contract for requests, responses, and errors. Link to the OpenAPI file from llms.txt so an agent that starts with one can find the other.

What is the latest version of the OpenAPI Specification?#

As of September 2026, the latest published version is OpenAPI 3.2.1, released on September 10, 2026. Check the specification site for the current version before upgrading tooling, since generators and validators often lag a release behind.

How do I keep API docs in sync with code?#

Generate contracts such as OpenAPI from the code so they cannot drift, keep prose docs in the same repository and pull requests as the code they describe, run the examples in CI, and use tooling that flags which docs a code change makes stale. The prose is what drifts, so that is where review effort should go.

The short version#

Agents need four things from an API: a map, prose that explains judgment, an exact contract, and sometimes a way to act. llms.txt, Markdown pages, OpenAPI, and MCP each cover one of them, and most teams should start with the contract, generated from code, then add the prose, the map, and finally a server. Write descriptions that say when not to use something and how to recover when it fails. Then plan for the real cost: every format you publish is another copy of the truth, and the copy an agent happens to read is the one it will believe.