Describe Your API For Agents



For agents to use APIs effectively, they need clear context on the API and how to navigate it. Every API needs a full, structured, supporting document that covers in detail every endpoint, parameter, and possible response. These guardrails allow agents to find their way and call APIs without unexpected side effects or token-maxxing surprises. The big surprise is: that agent standard already exists, and its name is OpenAPI.

OpenAPI could have been designed for agents, the fit for the use case is so good. If I were to write the requirements for a standard for describing APIs, we'd be pretty much there ... let's see.

  • Machine Readable OpenAPI is JSON or YAML format, entirely designed to be parsed and processed for a variety of use cases.
  • Structured Data From structured payloads and outwards to requests/responses, OpenAPI is an onion model of structured data at every level. Schemas use JSONSchema format.
  • Security Included The information on how to authenticate API calls is right there in the OpenAPI description.
  • Descriptions for Discoverability OpenAPI was originally designed as a documentation format, you can add words everywhere. For agents the key features are a meaningful API description in info.description so that an agent knows what this API is useful for, and per-operation descriptions so the agent can understand which API call does what.
  • Precise and constrained Every operation needs an operationId for unambiguous API navigation. Every field can include data type information including min/max values, formats, required (or not), read/write or both so that your agent doesn't get lost or burn tokens trying the wrong thing.
  • Examples To show intent, put an example with your request and response. The example shows the agent how to format the data, what sort of values are expected, and what gets returned. Just like for humans, examples for agents are worth a thousand words (or something like that).
  • Standards-Compliant OpenAPI plays very nicely with other standards. Built on top of existing HTTP standards and with specific support for OAuth2, OIDC and other related standards, everything your API needs is available. This is one area which does change over time so keeping up with newer releases of OpenAPI (3.2 is latest as of now, November 2026), is recommended.
  • Feedback Loop The responses section is designed to give lots of context about the different possible outcomes, including many kinds of errors. For agents to self-manage, understand if they've made a mistake and correct it themselves, really detailed error response documentation is important, and OpenAPI gives ways to do that.
  • Composable An API description doesn't have to be all in one file. The $ref syntax is a great way to reuse sections within a file, but it can also reference sections from other files just as easily.
  • Decomposable You don't need to serve up your whole OpenAPI all at once for every output, or every agent. Use an Overlay to create an OpenAPI document that only contains the endpoints you want your agent to know about or use. Especially in combination with unique operation IDs and detailed per-operation descriptions, this is a way to create instant custom recipes without having to maintain anything extra.
  • Extensible OpenAPI has always allowed, and even encouraged, extending the base specification. The project maintains registries of recognised extensions and documentation on their use.
  • Enhanceable Context Use the externalDocs feature to give agents more context about the API. Then use it again on every operation (also supported on schemas and tags) so that the agent can find just the context it needs at each step of its journey.

Your next step for agentic APIs

Agents are a new technology and we're looking for new solutions when the existing, boring technologies are already there and you probably already have an OpenAPI description for your API. I recommend investing energy into making the OpenAPI description into something an agent can run with, literally and figuratively, and you can continue to improve over time. By keeping the improvements central to the API itself, the rest of your API practice also benefits.

The best API description for agents is the API description you already (should have) had!


In: APIs
Tags: #api #openapi #ai