API Docs for Agent Tool Use: From Readable to Callable

OpenAPI documents provide machine-readable contracts that enable AI agents to call HTTP APIs with precise endpoints, parameters, and response formats, replacing guesswork from prose documentation. Frameworks like FastAPI and NestJS auto-generate these specs, which agents use to perform actions such as checking inventory or creating orders. Exposing a validated OpenAPI spec at a stable path is critical for agent tool use, while common mistakes include missing specs, drift from code, empty summaries, undocumented auth, and vague response schemas.

Part of the Agent Readiness course. Measure any page with the Core Agent Vitals analyzer. What it is An OpenAPI https://www.openapis.org document formerly Swagger is a machine-readable description of your HTTP API — every endpoint, its parameters, request bodies, response shapes, and auth — as one JSON or YAML file, typically at /openapi.json . It's the difference between prose docs a human reads and a contract a machine can consume. Why agents need it Tool-using agents don't just read your content; they act . When an agent decides to call your API — check inventory, create an order, run a query — it needs to know the exact endpoint, the required parameters, and the response format. Prose documentation forces it to guess, and guessed request formats fail: wrong field names, missing params, misread auth. The failures are quiet — a 400 the agent can't recover from. An OpenAPI spec hands the agent the typed contract directly. This is also the foundation newer protocols build on: agents.json and WebMCP the next two lessons reference or wrap your OpenAPI operations so agents can discover and invoke them uniformly. How to implement Most frameworks generate OpenAPI from your route definitions — FastAPI, NestJS, Express via swagger-jsdoc , Spring, and others emit it automatically. Serve it at a stable path: { "openapi": "3.1.0", "info": { "title": "Acme API", "version": "1.0.0" }, "servers": { "url": "https://api.acme.com" } , "paths": { "/products/{id}": { "get": { "summary": "Get a product", "parameters": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } , "responses": { "200": { "description": "Product", "content": { "application/json": { "schema": { "$ref": " /components/schemas/Product" } } } } } } } } } Reference it from your docs page and, ideally, from /.well-known/ . Write real summary and description fields — agents use them to decide when to call each operation. Validate curl -s https://api.your-site.com/openapi.json | head Lint it with the Swagger validator https://validator.swagger.io/ or npx @redocly/cli lint . The Core Agent Vitals analyzer https://agentvitals.dev/analyze checks common locations /openapi.json , /swagger.json , /api-docs and flags when no machine-readable API description is exposed. Common mistakes Docs but no spec. A beautiful HTML docs site with no /openapi.json is readable but not callable. Ship the machine-readable file too. A spec that drifts from the API. Hand-maintained OpenAPI rots fast. Generate it from the code so it stays true. Empty summaries/descriptions. Agents pick operations by their text. "summary": "" means the agent can't tell what the endpoint does. Undocumented auth. If the spec omits the security scheme, the agent calls unauthenticated and gets a 401 it can't diagnose. Vague response schemas. "type": "object" with no properties tells the agent nothing about what it gets back. Define the shapes. Next: agents.json — declaring what your site can do.