Chapter 10 of 10
Descriptions an Agent Can Use
What a coding agent reads out of an OpenAPI document, the four questions a description has to answer, and why the fields people treat as decoration are the ones that decide whether the call succeeds.
An agent reading your API has exactly one source, which is the document. It cannot ask a colleague, it will not find the wiki page, and it does not know which of your two order endpoints the team stopped using last spring.
That makes description fields the part of the contract with the highest leverage, and they are usually the part filled in last.
The four questions
A description that answers these four is enough for somebody to make the call correctly on the first attempt, whether that somebody is a person or a model.
What does this actually do. The answer is not a restatement of the method and the path, since POST /orders reads as create an order without any help. What a reader does not know is that prices are taken from the catalog at the moment of the call, so the totals in the response are the authoritative ones.
What has to be true first. Preconditions are invisible in a schema, and none of them are derivable from types. A cancellation may only work while the order is unshipped, an endpoint may require a verified account, and a call may have to follow another one.
What do the values mean. An enum value carries its meaning only for the person who invented it. PARTIALLY_FULFILLED needs one line saying what the caller should do about it.
What happens when it fails. A documented 422 with a description saying which condition produces it and what to change is the difference between a retry that works and a retry loop.
The fields that carry it
Descriptions live in more places than people use, and the ones closest to the value are the most effective.
The operation summary is one line and appears in navigation, so it should name the action rather than the resource. The operation description is where the four questions get answered. Parameter descriptions say what a value is for and what range is sensible, which is where a default belongs in prose as well as in the schema. Property descriptions explain fields whose names are ambiguous, and every API has more of those than its authors think. Enum descriptions carry the meaning of each value. Response descriptions say what caused this outcome rather than repeating the status code.
The useful discipline is that the answer goes where the question is asked. A note about idempotency belongs on the operation that needs it, not on a concepts page a reader reaches later or never.
What makes descriptions decay
Descriptions rot for a specific reason, which is that nothing breaks when they go wrong.
A type change breaks a client, and a stale sentence about a precondition that no longer applies breaks nobody until somebody follows it. That asymmetry means description quality has to be maintained deliberately. Two things work, which are a lint rule that requires them and a review step where the person approving a change reads the prose alongside the schema.
Writing for an agent is writing for a stranger
There is no separate register for machine readers, and the advice people give for it is the advice good technical writing already followed.
Be specific rather than complete. Say the constraint rather than gesturing at it. Name the other operation when there are two similar ones. Put the unit in the description of a numeric field, because total of 30.75 is ambiguous and a sentence saying the totals are in the currency named by the currency field is not.
The one thing that is genuinely different is the cost of ambiguity. A person who does not understand a description asks or experiments, while a model fills the gap with the most plausible thing and returns it with the same confidence as a correct answer. Our post on API descriptions an LLM can use goes into that further, and the documentation for agents chapter covers the portal side of the same question.
In Routebase
The description field in the designer is an editor rather than a text box, because for many operations the description is the documentation. The product page for agent-ready APIs shows how descriptions, errors and the published portal fit together.
Callouts, tables, code blocks and Mermaid diagrams all render in the published reference and travel in the exported document as Markdown. Enum values carry a label and a description per value, which export as x-enumNames and x-enumDescriptions. Style-guide rules cover the presence of summaries, descriptions on operations, parameters and schemas, so the gaps are a list rather than an impression.
The same document is what the MCP server hands an agent, so the descriptions a person reads in the portal and the ones an agent works from are the same strings. The Endpoints guide covers the editor, and the MCP Quickstart covers the agent side.
Frequently asked questions
How do you write OpenAPI descriptions for an LLM?
Write them for a competent stranger who cannot ask a follow-up question, because that is what an agent is. Say what the operation does, what the preconditions are, what the values mean and what happens when it fails. The difference from writing for a person is that an agent will not infer the missing half from context and will confidently produce something wrong instead.
What does an agent read from an OpenAPI file?
The same fields a reference renderer reads, which are the summary, the description, parameter and property descriptions, enum values, examples and the documented responses. An agent has no other source, so anything your team knows and the document does not say is simply absent from what it can work with.
Do enum descriptions matter for AI tools?
More than almost anything else of that size. A status field listing five uppercase strings tells a model the spelling and nothing about which one to send or what it implies. A one-line meaning per value turns a guess into a decision, and it is a few minutes of work per enum.
Is a good OpenAPI document enough for an agent to call an API?
For a single call, often yes, since the document holds the URL, the shape and the auth requirement. For a sequence it usually is not, because ordering, idempotency and which of two similar operations to use are rarely written down anywhere. Those belong in the description of the operation they apply to rather than in a separate page.
Last reviewed by The Routebase Team.