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.
