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 what each capability does and expects, and the machine-readable signposts like llms.txt that let a model orient itself without guessing. So much of our documentation assumes prior context that a developer carries in their head, and an agent has none of that, so anything implicit becomes a failure point. The business value is that legible surfaces get adopted correctly the first time, which cuts support load and abandoned integrations, and legibility is really just good hygiene that helps our human consumers too. I would rather invest in clarity once than pay for confusion on every automated call.
APIs Are Legible to Automated Consumers
Policies
Operations Are Agent-Legible
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 ba...
Tool Definitions Provided
I require that APIs publish explicit tool definitions that describe each callable capability as a discrete tool an agent can select, with clear names, descriptions, and typed inputs and outputs. Th...
Agent Readiness with llms.txt
I require that every API publishes an llms.txt file at a predictable, well-known location so that large language models and the agents built on them can find a concise, curated map of what the API ...
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...
Discovery
The average enterprise maintains approximately 0.5 APIs per employee, making it a constant challenge to track the growing inventory of HTTP APIs being produced and consumed. Enterprises often addre...
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...
