AI Agent 不会像开发者那样阅读你的 API 文档

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. 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. 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. 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. Enter fullscreen mode Exit fullscreen mode 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: POST /encounters GET /encounters/{encounter_id} GET /encounters/{encounter_id}/sessions GET /encounters/{encounter_id}/artifacts POST /encounters/{encounter_id}/complete Enter fullscreen mode Exit fullscreen mode 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 something like: 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. Enter fullscreen mode Exit fullscreen mode The above API description is not prompt engineering but better API documentation written for LLMs. The difference is that it contains information about intent and boundaries, not just implementation. That distinction becomes important when an LLM has to read and choose between several operations that make the same sense. 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 Enter fullscreen mode Exit fullscreen mode 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. Enter fullscreen mode Exit fullscreen mode 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: active completed cancelled then the specification should say that: status: type: string enum: - active - completed - cancelled Enter fullscreen mode Exit fullscreen mode 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. The same applies to dates, identifiers, numeric ranges, and other constrained values. If something is a date, use a date format. If there is a known pattern, express the pattern. If certain values are accepted, use an enum. Required fields must be marked as required. This sounds almost too basic to be worth writing about, but there is an important principle behind it: Every rule that exists only in prose is another rule the model may have to infer. That does not mean every possible business rule should be added to JSON Schema. Some rules are too dynamic or too complex for that. But when a constraint can be represented accurately in the schema, there is little benefit in leaving it implicit. 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. summary: Get patient 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 Enter fullscreen mode Exit fullscreen mode 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. Enter fullscreen mode Exit fullscreen mode It tells the reader not only what the endpoint does, but how it differs from a nearby capability. That is extremely useful when a tool set contains many operations with overlapping concepts. There is a limit, though: don't turn OpenAPI into a prompt Once you realise descriptions influence tool selection, there is a natural tendency to write big descriptions. Something like: description: > You are an expert healthcare API agent. Carefully analyse the user's request before using this tool. Think step by step about whether this tool is appropriate. If the user is asking about... Enter fullscreen mode Exit fullscreen mode In the above example, the API contract is carrying instructions that really belong in the agent layer. This is where tools like Mintlify are handy. It features a ' For agents ' tag, allowing technical writers to include agent-specific instructions that remain hidden from human readers. Also, maintaining such descriptions is a headache. As soon as the API changes, the description becomes stale, and suddenly your "prompt" is giving the model instructions that are no longer true. I prefer a simpler rule: Put facts and constraints in the API contract, whereas put general reasoning behaviour in the agent. The API description should tell the truth about the operation. It should explain when it applies, what it requires, what it returns, and what can make it fail. The agent should decide how to reason over that information. That separation makes the system much easier to maintain. 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" } Enter fullscreen mode Exit fullscreen mode 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" } } Enter fullscreen mode Exit fullscreen mode 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 and that is why I think error design deserves more attention when APIs are exposed to LLMs. A vague error like: { "message": "Bad request" } is not only frustrating for a developer but also a dead end for an agent. A structured error such as: { "code": "SESSION_NOT_ACTIVE", "message": "Audio can only be uploaded while the session is active.", "field": "session_id" } Enter fullscreen mode Exit fullscreen mode gives the agent context to reason about. While it doesn't guarantee the model won't make mistakes, it provides actionable information instead of forcing it to guess. The other problem nobody talks about: too many tools There is one more lesson that becomes obvious when you write a lot APIs. 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. This is also where OpenAPI and MCP start to overlap in interesting ways. Modern documentation and API tooling can selectively expose operations as tools instead of treating the entire API as one giant agent interface. Mintlify, for example, supports selecting OpenAPI operations for MCP exposure. The underlying idea is broader than any one documentation platform Good agent design is partly about deciding what not to expose 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? A checklist you should keep in mind 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 OpenAPI did not change, but its audience did. I don't think we need to change a lot in how we used to write OpenAPI docs. But when it comes to AI, the approach needs a little tweak. Developers still benefit from tutorials and cross-page context, but agents rely on the immediate, machine-readable facts in your documentation. You should aim to make intent, constraints, workflows, and errors clear. Try this, and your API will be easier for both humans and LLMs to use.