# API Docs for Agent Tool Use: From Readable to Callable

> Source: <https://blog.r-lopes.com/posts/agent-readiness-openapi>
> Published: 2026-07-02 14:00:00+00:00

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