From Documentation to Process: Making APIs Work for Agents
For two decades, API adoption followed a simple formula: beautiful documentation, interactive playgrounds, and clear examples. A human developer could read your docs, understand the endpoints, and mentally fill in the gaps with their domain knowledge. They knew how to sequence API calls because they understood their business problem.
Agents cannot do this.
An agent cannot infer a workflow from documentation. It cannot creatively combine API calls to solve a problem. An agent needs explicit, prescriptive instructions: exactly what to do and in what order. Show an agent a REST API and ask it to process a payment, and it might skip steps, call operations out of sequence, or fail silently when it encounters an error. A human would know to validate the payment method first. An agent has no domain knowledge. It needs to be told.
This changes everything about how we should document APIs.
The Problem: Documentation Written for Humans
A human reading Stripe’s API mentally executes a process: create customer → validate payment method → create charge. They understand the dependencies. An agent sees only isolated endpoints. It doesn’t know that a refund requires the original charge to be settled first, or that a 409 conflict means “try a different approach.”
Most API documentation is written for humans who fill in gaps with judgment. That no longer works when the consumer is a deterministic system.
The Solution: A Protocol Stack
The industry is responding by building layers on top of traditional APIs—not replacing them, but wrapping them with the process logic agents need.
MCP (Model Context Protocol) from Anthropic is the foundation. It wraps APIs as tool definitions that encode what agents can do. Instead of pointing an agent at the raw Stripe API, an MCP server says: “This tool creates a payment intent. Required: customer ID, amount, currency. If it fails with 409, a payment is pending—escalate to a human. If successful, store the ID for the next step.” That’s prescriptive instruction agents need.
A2A (Agent-to-Agent) protocols—still emerging—standardise how agents communicate and delegate tasks. In a real system, you may have multiple agents: triage agent, fulfilment agent, support agent. A2A lets them coordinate. When the triage agent sends work to fulfilment, it specifies: “Wait for confirmation before notifying the customer.” This sequencing logic is explicit, not assumed.
Emerging payment verification approaches address the highest-stakes problem: agents making payments. Traditional payment APIs assume a human clicks “buy.” They don’t ask, “Does this agent have permission?” or “Who’s liable if something goes wrong?” New approaches propose cryptographically verifiable user intent. Before an agent charges a customer, the user signs an authorisation: “Buy these items, up to this price, from this vendor.” The agent knows exactly what it’s authorised to do. No ambiguity. No room for hallucination.
How They Stack
These layers sit on top of each other:
User-signed Intent (verifiable)
↓
Payment Verification (high-stakes operations)
↓
A2A (agent-to-agent coordination)
↓
MCP (agent-to-tool interaction)
↓
Traditional APIsAn agent uses MCP to call Stripe. It uses A2A to coordinate with other agents. But before it charges a customer, it needs user-signed intent. Each layer is prescriptive in its own way.
What API Documentation Must Now Include
Traditional assessment: Is the documentation clear? Are there examples? Is the SDK good?
Agentic assessment: Does the API specify preconditions? Are mutating operations idempotent? For each error, what should the agent do? Can permissions be fine-grained? Is the state queryable? Is it exposed via MCP?
An API can score 9/10 for humans but 3/10 for agents if it lacks machine-readable preconditions, idempotent operations, and explicit error recovery paths.
What’s Next
This isn’t a minor tweak. As agents move from prototypes to production—handling real transactions—API documentation needs to evolve fundamentally. MCP from Anthropic is shipping. A2A and payment verification are emerging. Organisations that expose their APIs through these layers—wrapping, not replacing—will be ahead.
For human developers, keep building beautiful docs. For agents, add the prescriptive layer: machine-readable specs, precondition definitions, error recovery guidance, and MCP wrappers.
The split is permanent. APIs must serve both humans and agents. The ones that do both well have the best chance of survival. The other question that's going to come up is how granular these APIs should be?