Most API documentation is written for humans. It assumes a reader who can infer context, handle ambiguity, and make reasonable assumptions about edge cases.
Agents don’t work that way.
When an AI agent consumes your API, it reads the specification literally. Every ambiguity is a potential failure mode. Every undocumented behavior is a surprise waiting to happen.
The agent experience (AX) mindset
Just as we talk about developer experience (DX), we need to think about agent experience (AX). What does an agent need to successfully consume your API?
Explicit semantics. Don’t rely on naming conventions or implicit understanding. If status: "active" means the order is ready to ship, say that explicitly in the schema description.
Comprehensive examples. Agents use examples for few-shot learning. Provide examples for every endpoint, including edge cases and error scenarios.
Clear error taxonomy. Agents need to know how to respond to errors. A generic 400 response doesn’t help an agent decide whether to retry, modify the request, or escalate to a human.
Idempotency guarantees. Agents may retry operations. Document which operations are idempotent and provide idempotency key patterns for those that aren’t.
Schema design principles
Use enums liberally. If a field has a finite set of valid values, enumerate them. Agents struggle with freeform strings where the valid options are documented in prose.
Avoid polymorphism. Discriminated unions are fine, but avoid patterns where the same field can be completely different types based on context.
Include constraints. Minimum/maximum values, string patterns, array length limits—these belong in the schema, not just the documentation.
Document nullability explicitly. Is this field optional, or can it be present but null? These are different conditions, and agents need to know.
Operation descriptions that work
The description field in your OpenAPI spec is where agents learn what an operation does. Write these for machine consumption:
Bad: “Creates a new order” Good: “Creates a new order with the specified items. Requires at least one item. Returns the created order with assigned order_id. Fails with 409 if an order with the same idempotency_key already exists.”
Bad: “Gets user information” Good: “Retrieves profile information for the specified user_id. Returns 404 if user does not exist. Returns 403 if the authenticated user lacks permission to view this profile.”
Testing for agent consumption
Before declaring an API agent-ready, test it with actual agents:
- Give an agent only your OpenAPI spec and ask it to complete a task
- Observe where it fails or asks for clarification
- Update your spec to address those gaps
- Repeat
The goal is an API that an agent can consume successfully with zero additional context.
The payoff
Agent-ready APIs aren’t just better for AI—they’re better for humans too. The discipline of explicit semantics, comprehensive examples, and clear error handling benefits everyone who consumes your API.
Start with your most critical APIs. Make them agent-ready. Then expand from there.