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 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.