An OpenAPI document describes an HTTP API in a fixed schema: the paths, the methods, the parameters and their types, the request and response shapes, and the security schemes (OpenAPI Specification). The usual reason to publish one is developer experience, since a schema drives reference docs, client generation, and a working try-it console. That reason is sound and it undersells what the artifact is. Documentation is written to be read and interpreted. A schema is written to be executed, and the distinction is what makes it matter for agents.
The mechanism is direct enough that it barely needs tracing. Given a schema, a model can locate the operation that matches an intent, read the required parameters and their types, construct a request that conforms, apply the declared auth scheme, and know the shape of what comes back before it arrives. Without one, the same model is reverse-engineering an interface from prose and examples, inferring parameter names from a curl snippet and hoping the response matches what the page described. As a result, the first path fails loudly with a validation error you can act on. The second fails quietly with a malformed request or a misread response.
This has become more load-bearing as tool-calling has become the normal way models interact with systems. Function and tool definitions in the major model APIs are JSON Schema in a thin wrapper, and the Model Context Protocol describes tools in the same terms, so an OpenAPI document is close to a direct source for the definitions an agent needs. Meaning the schema is no longer only about generating a client library for a human developer, it is increasingly the thing that decides whether your API can be wired into an assistant at all.
However, there is a caveat worth stating rather than hiding, since the audit tries not to overclaim. Publishing a schema does not make your API safe for autonomous use on its own. Auth, rate limits, idempotency, and clear error semantics all matter, and an agent that can construct a call is not automatically an agent that should be allowed to make it. What the schema removes is ambiguity about the interface, which is a necessary condition for agent use rather than a sufficient one.
MachineRead scores openapi.json inside the machine_surfaces group at 3 points and counts it among the default agent-readiness probes. The check is discovery-oriented: it verifies that a schema is reachable at a predictable location and parses as a valid document, because a schema that exists only behind a docs portal or is generated client-side is not discoverable by the systems that would use it.
So here is what I would do. If your framework generates a schema, publish it at a stable, predictable path and confirm it is served as JSON rather than rendered only inside an interactive console, since FastAPI, among others, produces one automatically and it is easy to leave it reachable only through the docs UI. Fill in the parts that generators leave thin, particularly descriptions, examples, and error responses, because those are exactly what a model uses to choose between two similar endpoints. Then link it from your machine-readable catalogs so it can be found without being guessed, which is the subject of the next post in this series.
See also
- Methodology reference - documents the openapi.json probe and the machine_surfaces check group
- Launch post - covers how OpenAPI fits the four agent-consumable surfaces
- Related: api-catalog.json and ai-catalog.json