OpenAPI Describes Your API. But Who Tells AI Agents How to Use It Safely?

An OpenAPI description can tell an AI agent that a delete-customer operation exists, that it takes a customer ID, and that it returns a 204 status code. It can't tell the agent that the delete is permanent, that it also cancels every open order for that customer, or that nobody should call it without a human signing off first. A developer learns those things from a Slack thread or a painful incident. An agent learns them from whatever the description says, and the description is silent.

An OpenAPI description is a contract for what an API accepts and returns. It is not a usage policy: it doesn't say when an operation is safe to call, how often, in what order, or with whose approval.

That gap used to be acceptable. The consumers of an API were developers who read the docs, asked questions, and tested in staging before they shipped. AI agents read the description at runtime, pick an operation, and call it. The API description has quietly become an instruction manual for a consumer that has no other source of context.

Why AI agent safety is a platform problem

For a platform engineering lead, this isn't a documentation problem that belongs to each service team. It's a platform problem. Agents don't call one API. They call whatever the platform exposes, across every team and every gateway, and they do it at machine speed. When an agent misuses an endpoint, the incident shows up as a platform issue: a spike of writes nobody expected, a bulk export that pulled personal data into a model's context window, a retry loop that hammered a payment provider.

The question a platform lead has to answer isn't "is the description valid?" It's "if an agent follows this description exactly, what's the worst thing it can do?"

What OpenAPI describes, and what it was never built to describe

The OpenAPI Specification is a machine-readable format for describing an HTTP API's structure: its paths, operations, parameters, request and response schemas, and the authentication schemes it accepts. It answers "what can be called, and what shape is the data?" That's the job it was designed for, and it does that job well enough that whole toolchains run on top of an OpenAPI contract: documentation portals, SDK generators, contract tests, gateways.

HTTP itself adds a little meaning on top of that structure. RFC 9110 defines GET as safe and PUT and DELETE as idempotent. But those are conventions the API is supposed to follow, not guarantees the description can prove. A GET operation that starts a costly report job is still a valid OpenAPI operation.

What OpenAPI was never built to say is how an operation should be used: when, how often, in what order, with whose approval, and what happens if it goes wrong.

What AI agents need to know that OpenAPI doesn't say

Put an agent in front of a typical OpenAPI description and five kinds of information are missing.

Side effects and reversibility. The description says an operation exists. It doesn't say whether calling it changes data, whether that change can be undone, or whether it triggers something downstream (an email to a customer, a charge on a card, a webhook to a partner).

Data sensitivity. A response schema lists fields. It doesn't mark which of those fields hold personal data, payment data, or credentials. So it can't tell an agent which responses should never end up in a prompt, a log, or another tool call.

Order and preconditions. Real tasks take several calls. Create a cart, add items, apply a discount, check out. OpenAPI describes each operation on its own. It doesn't describe the sequence, the dependencies between steps, or what counts as success.

Limits and cost. Rate limits, quotas, and the cost of an expensive operation usually live in a separate docs page or in a 429 response the agent sees only after it has already hit the limit.

Error recovery. Bruno Pedro made this point in API Changelog in May 2026: a generic error gives an agent no way to tell whether a failure is temporary or permanent, or how long to wait before trying again. A human reads the error and makes a judgment call. An agent retries.

There's a sixth, quieter gap: ambiguity. API Evangelist's August 2026 piece on OpenAPI Overlays describes an agent that reads operation descriptions literally and "picks the wrong operation when two of them sound alike." Its example is "update a product" versus "cancel a product." To a developer, the difference is obvious. To an agent, both are operations that change a product.

How Overlays, Arazzo, and MCP annotations close part of the gap

The API community has noticed. Three efforts are moving in parallel, and each fills a different part of the gap.

OpenAPI Overlays and extensions. The Overlay specification lets a team apply targeted changes to a base OpenAPI document without editing the original file. The API Evangelist piece proposes using an overlay to carry agent-only context, so the human-facing docs stay lean. The agent-facing version gets imperative guidance and flags such as an x-agent-hint reading "Destructive and irreversible. Require explicit confirmation." Pedro's article proposes two more extensions: x-mcp-annotations for side-effect hints, and x-agent-trust, which declares how much trust an agent needs before it can call an operation. Its trust levels run from L0-UNTRUSTED to L4-FULL. None of these extensions are part of the core OpenAPI standard yet.

Arazzo. The OpenAPI Initiative's Arazzo specification, now at version 1.1.0, describes sequences of API calls: the steps, the dependencies between them, and the success criteria for each. The specification's own page says "AI agents become first-class API consumers" and lists "safe, predictable AI agent execution" as a use case. Its roadmap includes "actor-in-loop support (human or agent) for workflows requiring approval or intervention." Arazzo fills the order-and-preconditions gap directly: instead of guessing that checkout comes after add-to-cart, the agent follows a declared workflow.

MCP tool annotations. Many teams now expose APIs to agents as tools through the Model Context Protocol. MCP defines annotations such as readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The defaults lean cautious. If a tool doesn't declare otherwise, it's assumed to be potentially destructive and to reach outside its own environment.

When a platform team adds destructive flags, workflow definitions, and sensitivity markers, agents get a much better chance of doing the right thing. There is a cost: Pedro notes that a larger definition raises token costs, because the full definition goes into the model's context window.

Why agent-facing descriptions still can't enforce safety

All three efforts make the description richer. None of them make it binding.

The MCP specification says this directly: clients "MUST consider tool annotations to be untrusted unless they come from trusted servers." An annotation is a hint. A tool that deletes records can still declare itself non-destructive, and nothing in the protocol stops the call. The same holds for an x-agent-hint in an overlay or a success criterion in an Arazzo workflow. They tell a well-behaved agent what it should do. They can't make an agent behave.

And agents don't always behave. A model can misread an instruction, follow a prompt injection hidden in a document it just retrieved, or decide that a destructive operation is the fastest route to the goal it was given. The description was written for the agent that reads carefully. The risk comes from the one that doesn't.

There's also drift: the gap between what a description says and what the API does in production. A description is written once and edited when someone remembers. The API keeps changing: an endpoint gains a side effect, a field starts returning a customer's email address, a deprecated route keeps receiving traffic. The description may still tell the agent what was safe last quarter, not what the API does today.

So the answer to "who tells AI agents how to use an API safely?" has two parts: the description tells them, and the runtime has to check.

Why the runtime decides whether agents use an API safely

The MCP specification's own security section points in this direction. It says servers must validate inputs, enforce access controls, and rate limit tool calls, and that clients should log tool usage for audit. Those are runtime controls, not description fields.

For a platform team, the runtime layer has three jobs.

Enforce what the description declares. If an operation is flagged as destructive, the platform requires an approval step or a scoped credential before the call goes through, regardless of what the agent decided. If a field is marked sensitive, the response is masked before it reaches the agent. The description becomes the policy source; the gateway or the service applies it.

See what agents actually do. The platform needs to know which consumers are agents, which operations they call, in what order, how often, and with what data in the payload. Without that, a platform lead is trusting that agents follow the description without any evidence that they do. With it, misuse shows up as a pattern in traffic: an agent calling the cancel operation where it should have called update, a workflow skipping a step, a response carrying personal data to a consumer that shouldn't see it.

Feed reality back into the description. Runtime traffic records what an API does, not what someone wrote down about it. Traffic can show an endpoint returning a field the schema doesn't list, or an operation with a side effect the description doesn't mention. Either one is a signal to update the description, the overlay, or the Arazzo workflow. Treblle compares live traffic against the uploaded OpenAPI spec and flags undocumented endpoints, missing fields, and behavior changes, so the gap shows up in traffic data instead of in the next incident review. The description stops drifting because the runtime keeps checking it.

Where a platform team should start

A platform lead doesn't need to wait for these standards to settle to reduce the risk now. Four steps cover the gaps described above:

1. List every operation that is destructive, irreversible, or triggers an external side effect. Mark them in an overlay so the human docs stay unchanged. It's a small amount of agent-specific context, and it covers the operations where a mistake can't be undone.
2. Write Arazzo workflows for the multi-step tasks agents perform most often. Start with the ones where getting the order wrong costs money or data.
3. Treat every hint as untrusted. Require approval for destructive operations, mask sensitive fields, and enforce rate limits at the platform, not in the description alone.
4. Watch agent traffic and compare it with the description. Where they disagree, either the agent is misbehaving or the description is wrong. Both are worth finding before an incident does.

For more on getting APIs ready for agent consumers, see the ebook Preparing your APIs for AI Agents.

OpenAPI tells an agent what an API can do. Overlays, Arazzo, and MCP annotations are starting to tell it what it should do. Only the runtime can show what it actually did.