Back to all articles
APIs as a ProductPart 10
AI agentsAPI designMCPIdempotency

APIs as a Product, Part 10: Designing APIs for Agents, Not Just Developers

Janahan Thavendran3 min read

TL;DR

  • An AI refunds worker read "accepted" as "done" and issued a second partial refund; the fix was honest states and checking earlier requests.
  • For agents, states must be honest, calls safe to repeat, errors actionable by a model, permissions narrow and money movement approved by a person.
  • MCP is a layer, not a fix: expose tools shaped around jobs, with descriptions written as the only documentation the agent will read.
In this article

APIs as a Product, Part 10 of 10 · What changes when the caller is an AI agent.

The refund was marked successful. The payment gateway had accepted the request, so the AI digital worker we had built for refunds and chargebacks did what any careful system would do: it recorded the refund as done and moved on.

But the refund hadn't actually gone through. The merchant's balance was too low, and the gateway hadn't executed it yet. The customer, seeing no money back, asked again. The worker saw a new, valid request and issued a second partial refund. Both went through once the balance cleared. We found it a month later, in reconciliation.

No one had written bad code. The API said "accepted", and the agent read that as "done". A human operator might have paused and checked. The agent took the word at face value, because that is all an agent can do.

What changes when the caller is an agent

Everything in this series so far has been about consumers you never meet: partner developers and the teams down the corridor. An agent is the extreme version of that user. It reads your descriptions literally, it never opens a support ticket, and it will retry, loop and combine calls in ways no partner developer would.

That changes what good design means in a few specific places.

States have to be honest. "Accepted", "pending" and "completed" must mean different things, and the API must say which one is true. Our fix for the double refund was exactly this: nothing was marked successful until the balance had cleared, and before acting on a new request, the worker checked the status of earlier ones for the same order.

Repeating a call has to be safe. Agents retry. If a retry can create a second charge or a second refund, it eventually will. Every action that moves money or changes state needs to be safe to send twice.

Errors have to explain themselves. A developer can read an unclear error, open the docs and work it out. An agent will guess. A good error says what went wrong and what to do next, in words a model can act on.

Permissions have to be narrow. An agent that only needs to read orders should not hold a key that can issue refunds. And anything that moves money should have a step where a person approves it. Our refunds worker had a human approval step for exactly that reason.

Where MCP fits

The Model Context Protocol gives agents a standard way to discover and call tools. It is a useful layer, but it is a layer, not a replacement. An MCP server wrapped around a confusing API gives agents a confusing set of tools, just with better packaging.

The design choices that matter are the same ones from Part 4. Expose tools shaped around jobs, such as "find unreconciled payments" or "check refund status", not one tool per endpoint. Write descriptions as if they are the only documentation the caller will ever read, because for an agent, they are. Keep the same versioning promises, limits and audit trail you would give any partner.

Agents are the partners who never read your docs twice and never call to ask. If you already built your API for users you never meet, you are most of the way there. If you didn't, agents will find every gap, faster than any developer ever did.


Related reading: Building an AI Digital Worker for Refunds and Chargebacks.