{"slug": "api-docs-for-agent-tool-use-from-readable-to-callable", "title": "API Docs for Agent Tool Use: From Readable to Callable", "summary": "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.", "body_md": "*Part of the Agent Readiness course. Measure any page with the Core Agent Vitals analyzer.*\n\n## What it is\n\nAn [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`\n\n. It's the difference between prose docs a human reads and a contract a machine can consume.\n\n## Why agents need it\n\nTool-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.\n\nAn 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.\n\n## How to implement\n\nMost 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:\n\n```\n{\n  \"openapi\": \"3.1.0\",\n  \"info\": { \"title\": \"Acme API\", \"version\": \"1.0.0\" },\n  \"servers\": [{ \"url\": \"https://api.acme.com\" }],\n  \"paths\": {\n    \"/products/{id}\": {\n      \"get\": {\n        \"summary\": \"Get a product\",\n        \"parameters\": [{ \"name\": \"id\", \"in\": \"path\", \"required\": true, \"schema\": { \"type\": \"string\" } }],\n        \"responses\": { \"200\": { \"description\": \"Product\", \"content\": { \"application/json\": { \"schema\": { \"$ref\": \"#/components/schemas/Product\" } } } } }\n      }\n    }\n  }\n}\n```\n\nReference it from your docs page and, ideally, from `/.well-known/`\n\n. Write real `summary`\n\nand `description`\n\nfields — agents use them to decide *when* to call each operation.\n\n## Validate\n\n```\ncurl -s https://api.your-site.com/openapi.json | head\n```\n\nLint it with the [Swagger validator](https://validator.swagger.io/) or `npx @redocly/cli lint`\n\n. The [Core Agent Vitals analyzer](https://agentvitals.dev/analyze) checks common locations (`/openapi.json`\n\n, `/swagger.json`\n\n, `/api-docs`\n\n) and flags when no machine-readable API description is exposed.\n\n## Common mistakes\n\n**Docs but no spec.** A beautiful HTML docs site with no`/openapi.json`\n\nis 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\": \"\"`\n\nmeans the agent can't tell what the endpoint does.**Undocumented auth.** If the spec omits the`security`\n\nscheme, the agent calls unauthenticated and gets a 401 it can't diagnose.**Vague response schemas.**`\"type\": \"object\"`\n\nwith no properties tells the agent nothing about what it gets back. Define the shapes.\n\n*Next: agents.json — declaring what your site can do.*", "url": "https://wpnews.pro/news/api-docs-for-agent-tool-use-from-readable-to-callable", "canonical_source": "https://blog.r-lopes.com/posts/agent-readiness-openapi", "published_at": "2026-07-02 14:00:00+00:00", "updated_at": "2026-07-03 21:15:30.801761+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools"], "entities": ["OpenAPI", "Swagger", "FastAPI", "NestJS", "Express", "Spring", "Redocly", "Core Agent Vitals"], "alternates": {"html": "https://wpnews.pro/news/api-docs-for-agent-tool-use-from-readable-to-callable", "markdown": "https://wpnews.pro/news/api-docs-for-agent-tool-use-from-readable-to-callable.md", "text": "https://wpnews.pro/news/api-docs-for-agent-tool-use-from-readable-to-callable.txt", "jsonld": "https://wpnews.pro/news/api-docs-for-agent-tool-use-from-readable-to-callable.jsonld"}}