API Docs for Agent Tool Use: From Readable to Callable

Part of the Agent Readiness course. Measure any page with the Core Agent Vitals analyzer.

What it is #

An OpenAPI 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 or npx @redocly/cli lint

. The Core Agent Vitals analyzer 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 thesecurity

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.