Why Your OpenAPI Spec Isn't Enough for AI Agents

OpenAPI describes an API. Agent Readiness describes whether an agent can actually use it.

Your API has a complete OpenAPI spec. Every endpoint, schema, and response code is documented. Yet when an AI agent tries to use it, the agent fails — not because the spec is wrong, but because the spec describes an interface, not an agent's experience.

This isn't about OpenAPI being bad. OpenAPI is a necessary foundation. But it's not a complete Agent Readiness layer.

"Our API has OpenAPI. Why does an AI agent still fail to use it?"

This is the question API teams ask after adding AI agent support. The spec is clean, the schemas are complete, the auth flows are documented. And yet — agents struggle.

The answer isn't that OpenAPI is insufficient as a specification. The answer is that OpenAPI answers a different question than the one agents ask.

OpenAPI answers: "What endpoints exist?"

Agents ask: "Can I discover this API? Can I authenticate autonomously? Can I understand what an operation means? Can I recover from errors? Can I trust that a claim about this API is true?"

These are different questions. And the gap between them is structural.

Consider a payments API with three endpoints:

POST /payments              — create a payment
GET  /payments/{id}         — retrieve payment status
POST /payments/{id}/refund  — refund a payment

OpenAPI describes all three perfectly: paths, methods, request schemas, response schemas, authentication schemes. A human developer reading this spec would understand how to use the API.

But an AI agent needs to answer questions that the spec doesn't address:

Can I create a payment?
When should I call it?
What must happen first?
What does "pending" mean?
When can I refund?
What happens if payment fails?
Should I retry?

Each of these questions maps to a layer beyond OpenAPI:

llms.txt

or .well-known/openapi

so the agent can find the API?POST /payments

idempotent? Does it charge money? Is it safe to retry?OpenAPI describes the interface. These questions require context that goes beyond the interface.

Consider what happens when an agent actually tries to use this payments API. The agent reads the OpenAPI spec, identifies POST /payments

, constructs a request, and sends it. So far, so good. But then:

"status": "pending"

. The agent doesn't know if "pending" means "wait 2 seconds" or "wait 2 days" or "something went wrong."400 Bad Request

with {"error": "invalid_state"}

. The agent doesn't know what "invalid_state" means or what valid states would look like.POST /payments

after a timeout. A second payment is created. The agent didn't know the operation wasn't idempotent.None of these failures are caused by a wrong OpenAPI spec. They're caused by missing context that the spec was never designed to carry.

The gap is not about model intelligence. A more capable model still can't answer "Is this operation idempotent?" if the information isn't in the spec. The gap is structural: API description ≠ agent understanding.

This is not a call for a new magic file. Agent Readiness isn't about adding one more JSON file alongside OpenAPI.

It's about cumulative layers:

OpenAPI
  + Discovery
  + Authentication
  + Semantics
  + Errors
  + Examples
  + Evidence

Each layer builds on the previous. Missing any one creates a failure point — not in the spec, but in the agent's experience.

llms.txt

, .well-known

, ai-sitemap.xml

). Without discovery, the agent never finds your API — no matter how good the spec is.securitySchemes

with flow details). Without it, the agent can't obtain credentials autonomously.POST /payments

charges money or just creates a record.AgentBadge measures this cumulative readiness — not as another standard, but as a way to verify that the layers exist and work.

A claim without evidence is a marketing statement. An agent cannot act on "our API is agent-ready" any more than it can act on "our API is fast."

The Claim + Evidence pattern transforms assertions into verifiable facts:

This is the key concept that bridges to the measurement framework. Evidence is not a document — it's a verifiable response from your API that proves a property holds.

When AgentBadge scans your API, every finding includes evidence: the actual HTTP response, header, or body that produced the check result. Not "we think your API supports discovery" — but GET /llms.txt → 200, content-type: text/plain, 847 bytes, valid format

.

This changes the conversation. Instead of debating whether an API is "agent-ready" in the abstract, you can point to specific, verifiable responses. Instead of a badge that says "ready," you get a report that says "72 checks run, 58 passed, 14 failed — here's the evidence for each."

Evidence also means reproducibility. Another agent, another scanner, another developer can run the same checks and get the same results. The claim isn't "trust us" — it's "verify yourself."

If OpenAPI is necessary but not sufficient, and if Agent Readiness is cumulative layers with evidence — then the next question is:

How do we objectively determine what an agent can actually discover, understand, and use?

That's the measurement problem. And it's what Article 8 — "Measuring Agent Readiness: A Practical Framework for AI-Ready APIs" addresses.

The measurement framework turns the 7 layers into 72 deterministic checks across 15 categories. Each check produces evidence. Each evidence item is scored. Each score is verifiable.

GET /llms.txt

return 200? Does /.well-known/openapi

exist?summary

and description

fields that explain intent, not just method?{"error": "something"}

?npx @agentbadge/cli scan https://your-api.com

— 72 checks in seconds, free, no signup.

npx @agentbadge/cli scan https://api.example.com

npx @agentbadge/cli scan https://api.example.com --format json > report.json

Every finding links to the HTTP response that produced it. Evidence, not assertions.

OpenAPI describes an API. Agent Readiness describes whether an agent can actually use it.

Originally published at

[AgentBadge]