How to Write API Docs AI Agents Can Use (llms.txt, OpenAPI and Tool Descriptions)

TL;DR

API docs for AI agents work in three layers. An llms.txt file tells the agent what exists, your OpenAPI spec tells it how to call each endpoint, and tool descriptions decide which tool it picks.

Write each layer for a reader that can't scroll, guess or ask. Then test with a real agent and keep all three in sync with your spec.

Two MCP servers do the same job. One has clear, complete tool descriptions. The other has the defaults its code generator produced.

In a February 2026 study, agents picked the well-described server 72% of the time, against a 20% baseline. Your API docs now decide which API gets called. This guide shows you how to write API docs for AI agents, layer by layer.

What does an AI agent read in your API docs?

An AI agent reads three things in your API docs, in a fixed order: an llms.txt file to find what exists, the OpenAPI spec to learn how to call it, and tool descriptions to choose between options. It rarely reads your guides the way a person does. If one layer is missing or vague, the agent guesses, and guesses become failed calls.

What is agent-readable API documentation?
‍
Agent-readable API documentation is defined as docs that an AI agent can fetch as plain text, parse without guessing and use to make a correct first call. It covers the discovery file, the API contract and the tool descriptions an agent reads.

The demand is real. Gartner predicted in March 2024 that more than 30% of the increase in API demand would come from AI and tools using large language models (LLMs) by 2026. Each of those callers reads your docs before it reads anything else.

Why do human-first API docs fail AI agents?

Human-first API docs fail AI agents because they rely on things an agent can't use: visual layout, context spread across pages and a reader who can ask for help. A developer fills gaps from experience. An agent fills them with guesses.

These are the failures that show up most often:

• Pages that need JavaScript: Many docs sites render in the browser. An agent fetching the URL gets an empty shell.
• Answers inside screenshots: Auth flows and sample responses shown as images are invisible to a text reader.
• Auth buried in a guide: If the security scheme isn't in the spec, the agent doesn't know how to authenticate.
• Vague names: An operationId like get_api_v1_users_id tells the agent nothing about intent.
• Missing error responses: Without documented 4xx responses, the agent can't recover from a failed call.
• Repeated tool names: Wang et al. scanned 10,831 MCP servers and found 73% repeated tool names. An agent can't choose between two tools called search.

The fix isn't a second set of docs. It's making the docs you have readable as text, complete in the spec and specific in the tool layer. For the design side of this, see our guide to making your APIs ready for AI agents.

What is llms.txt, and how do you write one for API docs?

llms.txt is a plain Markdown file at a known path, usually /llms.txt, that gives AI agents a short summary of your site and links to LLM-friendly pages. For API docs, it's the index an agent reads first. It points to your reference, quickstart and auth guide so the agent doesn't have to crawl your portal.

What goes in an llms.txt file?

The llms.txt specification sets a fixed order:

1. An H1 with the project name: This is the only required section.
2. A blockquote summary: One or two lines of key facts the agent needs to read the rest.
3. Optional notes: Plain paragraphs or lists, with no headings.
4. H2 file lists: Each H2 holds a list of links, written as [name](url): notes.
5. An "Optional" section: Secondary links an agent can skip when it's short on context.

What does an llms.txt example for an API look like?

Here's a short llms.txt example for a payments API:

# Acme Payments API

> REST API for charges, refunds and payouts. JSON over HTTPS. Auth is OAuth 2.0 client credentials. Base URL: https://api.acme.com/v2

Amounts are in minor units (cents). All write calls accept an Idempotency-Key header.

## Docs

- [Quickstart](https://docs.acme.com/quickstart.md): Get a token and make a first charge
- [Authentication](https://docs.acme.com/auth.md): Scopes, token lifetime and errors
- [OpenAPI spec](https://docs.acme.com/openapi.json): Full contract for every endpoint

## Reference

- [Charges](https://docs.acme.com/reference/charges.md): Create, capture and void charges
- [Refunds](https://docs.acme.com/reference/refunds.md): Full and partial refunds

## Optional

- [Changelog](https://docs.acme.com/changelog.md): Breaking changes by version

Point each link at a Markdown version of the page, not the HTML. The spec suggests serving it at the same URL with .md added. Many docs platforms also generate an llms-full.txt with every page in one file. That's a common convention, not part of the spec.

Does llms.txt work?

llms.txt works best for coding agents and assistants that fetch docs on demand, and less for search crawlers. As of November 2026, no major AI provider has confirmed that its search crawler uses llms.txt to rank or answer. But OpenAI, Anthropic and Google publish llms.txt files for their own developer docs, and Chrome's Lighthouse now checks for the file in its agentic browsing audits.

The file takes an hour to write and costs nothing to serve. For API docs, where coding agents are the main readers, it's worth doing.

How do you make an OpenAPI spec agent-readable?

You make an OpenAPI spec agent-readable by filling in the fields agents rely on: a clear operationId, a description that says when to use the operation, typed parameters with examples, error responses and the security scheme. Agents treat the spec as the contract. Anything not in it, they have to guess.

• operationId: Use a verb and a noun the agent can match to a task, such as createRefund, not post_refunds_1.
• summary vs description: The summary is a short label. The description says what the operation does, when to use it and when not to.
• Parameters: Give every parameter a type, a format, an example and, where values are fixed, an enum.
• Responses: Document the 4xx and 5xx responses with an example body, so the agent knows how to recover.
• Security: Declare the auth scheme in securitySchemes and apply it to each operation.
• Examples: Add a request and response example to every operation. Agents copy examples closely.

If you're turning specs into MCP tools, the details matter even more. Our guide to OpenAPI spec best practices for MCP covers naming, meta-tools and large APIs.

How do you write tool descriptions AI agents choose?

You write tool descriptions agents choose by making them accurate, saying what the tool does and when to use it, covering every input and output, and keeping them short. These four tests come from Wang et al.'s study of 10,831 MCP servers, a preprint not yet peer-reviewed. Descriptions that passed them were picked 72% of the time against a 20% baseline.

What is a tool description?
‍
A tool description is defined as the plain-language text an AI agent reads to decide whether a tool fits its task. In the Model Context Protocol (MCP), it sits next to the tool's name and input schema.

The study found two tests mattered most. Fixing functionality, meaning what the tool does and when to use it, raised selection by 11.6%. Fixing accuracy raised it by 8.8%.

Each strong description does four things:

1. States the action: One verb and the object it acts on.
2. Says when to use it, and when not to: Name the sibling tool for the other case.
3. Names the inputs and outputs: Use the exact field names from the schema.
4. Flags side effects: Say "read-only" or what changes, so the agent knows what's safe to retry.

What does an agent-readable API docs checklist look like?

An agent-readable API docs checklist covers ten checks across the three layers, from serving plain text to testing with a real agent. Run it once per API, then add the automated checks to CI so the docs don't drift.

1. Serve docs as text: Every docs page loads without JavaScript, or has a .md version.
2. Publish llms.txt: Put it at your docs root, with links to Markdown pages.
3. Keep one source of truth: Generate reference docs and tool definitions from the same OpenAPI spec.
4. Name operations by intent: Every operationId is a verb and a noun.
5. Describe when to use each operation: Not only what it does.
6. Type every parameter: Format, example and enum where it applies.
7. Document errors: Every operation lists its 4xx responses with an example.
8. Declare auth in the spec: Not only in a guide.
9. Make tool names unique: No two tools share a name or a near-identical description.
10. Test with an agent: Measure first-call success before every major release.

How do you test whether agents can use your API docs?

You test API docs for AI agents by giving an agent a real task, access to nothing but your docs and a sandbox, then checking whether its first call succeeds. First-call success is the clearest single measure. If the agent needs three tries, your docs have a gap.

• Pick five common tasks: Such as "refund the last charge for this customer".
• Give the agent only your docs: Your llms.txt, the spec or your MCP server. No hints in the prompt.
• Log every call: Note which tool it picked, which parameters it sent and whether the call worked.
• Fix the layer that failed: Wrong tool means a tool description problem. Wrong parameters means a spec problem. Couldn't find the docs means an llms.txt problem.
• Automate the static checks: Lint the spec in CI and run Lighthouse against your docs site.

This is right for you if partners or customers already use coding assistants to integrate with your APIs, you're exposing APIs as MCP tools, or your docs live in more than one place.

This is not right for you if you have a handful of internal APIs used by one team. Good OpenAPI hygiene is enough at that size.

How does DigitalAPI make API docs agent-ready?

Keeping three layers in sync by hand breaks the first time a spec changes. Teams using DigitalAPI generate all three from the same specs, so llms.txt, reference docs and MCP tools stay current across Apigee, Kong, AWS and Azure.

• Docs from your specs: Generate documentation from OpenAPI specs, with endpoints, schemas, authentication and sample payloads.
• A machine-readable layer: The portal publishes a stable spec and an llms.txt index, so agents can find and parse your docs.
• Specs to MCP tools in one click: Every OpenAPI operation becomes an MCP tool with full schemas and examples, served through a governed MCP gateway.
• The same audit trail: Every MCP call goes through the same audit and metering as your other API traffic.

See how it works on our API documentation page, or compare options in our roundup of API documentation tools.

See how agents read your APIs today, and what it takes to fix it

‍Book a DigitalAPI demo!

API docs for AI agents: FAQs

What is llms.txt?

llms.txt is a Markdown file, usually at /llms.txt, that gives AI agents a short summary of a website and links to its most useful pages. For API docs, it points agents to the quickstart, auth guide, reference and OpenAPI spec, so they don't have to crawl the whole portal.

Is llms.txt the same as robots.txt?

No. robots.txt tells crawlers which pages they're allowed to access. llms.txt tells AI agents what a site offers and where its best content is. A site can use both, and they don't conflict.

Does Google use llms.txt?

As of November 2026, Google hasn't confirmed that its search ranking or AI answers use llms.txt. Google does publish llms.txt files for some developer docs, and Chrome's Lighthouse checks for the file in its agentic browsing audits.

What is llms-full.txt?

llms-full.txt is a single file that contains the full text of a site's docs, so an agent can load everything at once. It's a convention many docs platforms use, not part of the llms.txt specification. Use it when your docs are small enough to fit in an agent's context.

Do AI agents read OpenAPI specs?

Yes. Coding agents and MCP tools use OpenAPI specs as the contract for how to call an API: the operations, parameters, auth and responses. A complete spec, with descriptions and examples, is a major factor in whether an agent's first call works.

How long should an MCP tool description be?

An MCP tool description should be long enough to say what the tool does, when to use it, its key inputs and outputs, and any side effects. For most tools, that's two to four sentences. Longer descriptions waste context, and shorter ones leave the agent guessing.

Final word

Your API docs have a new first reader, and it can't scroll, guess or ask. Give it an llms.txt to find you, a complete spec to call you and tool descriptions that say exactly when to use each tool. Then test, because the only proof is a first call that works.

If you want agent-ready docs across every gateway without maintaining three layers by hand!
‍
See how DigitalAPI does it.