AI Agents Don't Read Your API Docs Like Developers Do

AI Agents Don't Read Your API Docs Like Developers Do

I have spent a lot of my time writing API documentation, and I used to think that I understood what makes an OpenAPI specification good until AI came into the picture. Good API docs are pretty straightforward: you define paths correctly, write the right types for parameters, and explicitly mark required fields, etc. These are still important. But it starts to feel incomplete when a large share of your docs traffic comes from AI agents; good suddenly needs to mean something more.

The Problem with AI Agents

Look at my Mintlify dashboard. More than 50% of the traffic to my documentation site now comes from AI agents, and that changes the way I write the documentation. When you give an API to an AI agent, you will notice different kinds of problems that did not exist before. It needs to decide things like which operation matches a user's request, figure out what arguments are needed, understand relationships between operations, and sometimes recover when the API rejects its request.

The Difference Between Human and AI Understanding

Another problem is that an AI cannot build a mental model the way human developers do. Most AI has a tool definition and a context window. That difference changes how I think about OpenAPI now. I'm not saying that an OpenAPI document magically becomes an LLM's system prompt. It doesn't. Depending on the stack, the specification may be transformed into function definitions, JSON Schema, MCP tools, or another representation before the model sees it. The important part is what happens in between. The information in your API contract can become part of the information the model uses to decide what to do.

The Importance of API Documentation for AI Agents

Once you look at it that way, a few things that seemed like minor documentation details start looking more like API design decisions. The endpoint can be technically correct and still be bad for agents. Consider this example as a normal endpoint:

post:
  summary: Create encounter
  description: Creates an encounter.

There is nothing wrong with this OpenAPI. A developer who already knows the product might understand exactly what it means. But imagine an agent has access to several operations:

GET /encounters/{encounter_id}
GET /encounters/{encounter_id}/sessions
GET /encounters/{encounter_id}/artifacts
POST /encounters/{encounter_id}/complete

Now the user says: "Start a new visit for this patient." The agent has to work hard to figure out that POST /encounters is the right operation. The summary "Create encounter" gives it very little help. It doesn't tell the LLM that this is the operation it needs to use when starting a new visit. It also doesn't say what an encounter represents in this particular API. A more useful description would be:

post:
  summary: Start a new patient visit
  description: >
    Creates a new encounter for a patient visit. Use this endpoint when starting a new visit.
    The returned encounter_id identifies the visit and is required by the endpoints used to retrieve the visit session and complete the encounter.
    Do not use this endpoint to retrieve an existing encounter.

Workflow Documentation

APIs have always had workflows, but we didn't always put them in the contract. What I mean when I say this, well, let's figure it out. Look at a simplified clinical workflow as an example from my documentation:

Create encounter ↓ Start session ↓ Send audio ↓ Complete session ↓ Generate note

A developer working through the integration will usually discover the steps pretty quickly. The quick start probably shows it. The API reference explains the individual endpoints. There may be a tutorial that ties everything together. But AI does not necessarily get that same experience. It may see five separate tools. Now suppose the model tries to send audio before a session has been created. The API returns an error. AI has to figure out what happened and what operation should come next. As humans, we can make this easier by putting the relationship where it matters:

description: >
  Uploads audio for an existing visit session.
  The session must already exist and must be active.
  Use the session_id returned when creating the session.
  Do not call this endpoint before a session has been created or after the session has been completed.

Error Handling

Traditional API documentation often focuses on the happy path, like here's what this endpoint does. Agent-facing documentation has another job: here's when this operation is valid, and here's when it isn't. These are not the same thing. The string problem is bigger than it looks. There is another pattern I see frequently in OpenAPI specifications:

status:
  type: string

This is technically valid, but it can throw away information that the API already knows. If the only valid values are:

status:
  type: string
  enum:
    - active
    - completed
    - cancelled

The reason is obvious for request validation, SDK generation, and documentation. It also matters when an agent is constructing the request. If the schema says string, the model has to determine what string belongs there. It may have seen the allowed values elsewhere, but there is no reason to make it guess when the API already has a finite set of valid values.

Descriptions Should Answer the Question the Model is Actually Trying to Solve

One of the biggest changes I would make to API descriptions is to stop thinking of summary and description as places where we simply repeat the endpoint name. For a human reader, this might be enough to start navigating. But for a model choosing between tools, it is much less useful. Imagine an API has:

GET /patients/{id}
GET /patients/{id}/encounters
GET /patients/{id}/notes
GET /patients/{id}/medications

A user asks: "What happened during the patient's last visit?" Which one should the model call? The answer is probably not obvious from the endpoint names alone. The API reference might have hundreds of pages explaining the system, but the model's immediate problem is much smaller: Which tool is relevant to this intent? So write descriptions that explain not just what an operation returns, but what kind of request should lead to that operation. For example:

summary: Get encounters for a patient
description: >
  Returns the clinical encounters associated with a patient.
  Use this endpoint when you need to identify a patient's visits or determine which encounter to use for a follow-up operation.
  Use GET /patients/{id}/notes instead when the user is asking specifically for clinical notes.

Error Design

Your error response is part of the conversation now. This is probably the part of agent-oriented API design that I find most interesting. For a traditional integration, an error response is often treated as the end of a failed request. For an agent, it can become the input to the next decision. Suppose the agent calls:

POST /sessions/123/audio

and receives:

{
  "error": "Invalid request"
}

There is not much context for the agent to act on that. It might think: Should it retry or change the session ID? Ask the user? Check the session? Call another endpoint? Now imagine the API returns:

{
  "error": {
    "code": "SESSION_NOT_ACTIVE",
    "message": "Audio can only be uploaded while the session is active.",
    "field": "session_id",
    "current_status": "completed"
  }
}

That response gives the agent useful state. It knows the request failed because of the session state and understands which field is involved. Most importantly, it understands that simply retrying the same request is not going to help.

Selective Exposure

Making every endpoint available to an agent is not necessarily a good idea. Imagine a mature API with 300 operations. A human developer might appreciate having all of them documented. They can search the reference, jump between resources, and use the API according to their needs. An agent does not necessarily benefit from seeing all 300 operations at once. Suppose the user asks: "Get the note for this encounter." If the model has five tools related to notes, three related to encounters, and several generic document operations, tool selection becomes harder before the actual API call even happens. So, we need to separate two ideas: Your API surface is not necessarily your agent tool surface. Your full OpenAPI specification can remain the source of truth for the API. But the set of operations you expose to an agent can be deliberately selected.

Checklist for Agent-Friendly API Documentation

If I were reviewing an OpenAPI specification and knew it would be consumed by an agent, I would take a different approach. Here is a checklist you can follow:

• Can I tell why this operation exists from its description? If the answer is just "creates X" or "gets X," there may not be enough context for tool selection.
• Can I distinguish this endpoint from similar endpoints? If several operations deal with the same resource, say what makes each one different.
• Are the constraints represented in the schema? Don't leave an enum, date format, numeric range, or required field as tribal knowledge.
• Are workflow dependencies visible? If one operation requires a resource or state created by another operation, document that relationship.
• Can an error tell the caller what went wrong? A status code is useful, but a structured error can provide the information needed for recovery.
• Does the agent really need every operation? A complete API is useful for developers. A focused tool set is often better for agents.

Conclusion

What changed for me when writing API documentation? The reason I find this topic interesting is that none of these ideas is really new. Strong API documentation has always needed clear descriptions, accurate schemas, good examples, sensible errors, and understandable workflows. What changed is the audience reading it. When I used to write API documentation primarily for developers, I could assume that the reader would connect information across the documentation. A developer can read an endpoint reference, notice an unfamiliar field, search for it, open the related guide, and come back. When an agent is choosing a tool, the cost of missing context is different. The model may never discover the missing page. It may simply choose the wrong operation. And that changes what I consider a good description now. I no longer want an endpoint description to answer only: What does this endpoint do? I also want it to answer: When should I use it? What needs to be true before I use it? What should I use instead when this is not the right operation? What information do I get back that I will need later?