Turning OpenAPI specs into agent tools

The usual way to give an agent access to a backend is to write a tool definition per endpoint. It works, and it stops working at about twenty endpoints. Every new route means a code change, a review, and a deploy before the model can use it, which puts the AI team in the critical path of every backend change.

Backends already describe themselves. An OpenAPI document has the path, the method, the parameters, the types, and usually a summary. That is most of a tool definition already, so the generation step is mechanical.

What the spec does not tell you

Mechanical generation gets you a model that can call any single endpoint and has no idea which ones belong together. A spec describes endpoints in isolation. It does not say that checkout must follow cart validation, that a search call is cheap and a reindex call is not, or that one route is safe to retry and another is not.

So the generated tool needs a second layer on top of the spec - annotations that carry the things the planner has to know:

• ›Chaining: which calls typically precede or follow this one
• ›Cost and latency class, so the planner can prefer a cheap path
• ›Idempotency, so a retry is not a second order
• ›Business rules the API enforces but does not document

x-agent:
  chains-after: [cart.validate]
  cost: high
  idempotent: false
  note: "Fails closed if the cart was modified after validation."

Keeping these as vendor extensions in the spec itself matters more than the format. The annotation lives next to the endpoint, so the team that changes the endpoint is the team that updates the annotation. Move it into a separate registry and it goes stale within a quarter.

The part that pays for itself

Once this is in place, a new backend endpoint becomes an agent capability with no AI-side code change at all. The backend team ships a route with its annotation and the planner can compose it into multi-step flows it has never been shown.

The test is not whether the agent can call your API. It is whether adding an endpoint requires the AI team at all.

The cost is that a badly annotated endpoint is worse than a missing one, because the planner will confidently use it wrongly. Annotation quality becomes a backend review concern, which is a reasonable trade for removing the bottleneck.