I require that every operation in an OpenAPI carries a description rich enough that an agent can decide, from the definition alone, what the operation does, when to call it, and what it will get back. A terse summary that satisfies a human skimming the docs is not sufficient when the reader is a model reasoning about which call to make next. I insist on this at design time because agents do not have the benefit of a support channel or institutional knowledge, and a vague description quietly produces a wrong integration nobody notices until it fails in production. APIs should write operation descriptions as if the only reader is a capable machine that will take every word literally.
Operations Are Agent-Legible
Rules
OpenAPI Operation Description Agent Sufficient Warn
Every operation should have a description long enough for an AI agent to understand what the operation does and call it correctly. Short or missing operation descriptions leave agents guessing abou...
Strategies
APIs Are Legible to Automated Consumers
I want our APIs to be legible to the automated consumers reading them, not just to the humans who wrote them. That means operations that describe themselves clearly, tool definitions that spell out...
APIs Are Ready for AI Agents
I want every API we operate to be ready for the agents that are now showing up as first-class consumers alongside our human developers. That means our APIs publish the machine-readable signposts ag...
Experiences
Agent Experience
Agent experience is developer experience for machines. As AI agents become first-class consumers of APIs, the experience they have discovering, understanding, authenticating, and calling an API mat...
Consistency
Achieving consistency in the design, delivery, and maintenance of HTTP APIs across an enterprise is a significant challenge—one that often complicates API operations. Small differences, such as var...
Lifecycle
design_services Design Design
Design is where the human experience of an API is won or lost. I work design-first, shaping the paths, schema, errors, and naming in the contract before development begins, so that consistency is b...
