# OpenAPI vs Agent Readiness | AgentBadge > OpenAPI is necessary but not sufficient for agent readiness. Agents need discovery, guides, error handling, and consistency beyond a spec file. Skip to content [![](https://agentbadge.xyz/icons/logo-32.webp) AgentBadge](https://agentbadge.xyz/) ![](https://agentbadge.xyz/icons/arc.png) Arc Mainnet [Scanner](https://agentbadge.xyz/services/scanner) [Passports](https://agentbadge.xyz/services/passports) [Marketplace](https://agentbadge.xyz/services/marketplace) [Blog](https://agentbadge.xyz/blog) [Dashboard](https://agentbadge.xyz/dashboard) [DataHub](https://agentbadge.xyz/hackathon/datahub) [WebMCP](https://agentbadge.xyz/hackathon/webmcp) [KeeperHub](https://agentbadge.xyz/hackathon/keeperhub) [AI Builders](https://agentbadge.xyz/hackathon/ai-builders) [CTC](https://agentbadge.xyz/hackathon/ctc) [FX Delta](https://agentbadge.xyz/hackathon/fxdelta) [Agent Allowance](https://agentbadge.xyz/hackathon/agent-allowance) [Agents](https://agentbadge.xyz/ui/agents) [Search](https://agentbadge.xyz/ui/search) [Catalog](https://agentbadge.xyz/ui/catalog) [A2A Inbox](https://agentbadge.xyz/ui/a2a) [Marketplace](https://agentbadge.xyz/ui/market/tasks) [Help](https://agentbadge.xyz/ui/help) [Rules](https://agentbadge.xyz/rules) [Contact](https://agentbadge.xyz/contact) [FAQ](https://agentbadge.xyz/faq) Services [Scanner](https://agentbadge.xyz/services/scanner) [Passports](https://agentbadge.xyz/services/passports) [Marketplace](https://agentbadge.xyz/services/marketplace) [Blog](https://agentbadge.xyz/blog) Hackathons [DataHub](https://agentbadge.xyz/hackathon/datahub) [WebMCP](https://agentbadge.xyz/hackathon/webmcp) [KeeperHub](https://agentbadge.xyz/hackathon/keeperhub) [AI Builders](https://agentbadge.xyz/hackathon/ai-builders) [CTC](https://agentbadge.xyz/hackathon/ctc) [Agent Allowance](https://agentbadge.xyz/hackathon/agent-allowance) [FX Delta](https://agentbadge.xyz/hackathon/fxdelta) Platform [Dashboard](https://agentbadge.xyz/dashboard) [Passport](https://agentbadge.xyz/passport) [Agents](https://agentbadge.xyz/ui/agents) [Search](https://agentbadge.xyz/ui/search) [Catalog](https://agentbadge.xyz/ui/catalog) [A2A Inbox](https://agentbadge.xyz/ui/a2a) [Marketplace](https://agentbadge.xyz/ui/market/tasks) [Medical Demo](https://agentbadge.xyz/ui/medical-demo) [Help](https://agentbadge.xyz/ui/help) [Rules](https://agentbadge.xyz/rules) [Contact](https://agentbadge.xyz/contact) [FAQ](https://agentbadge.xyz/faq) [Home](https://agentbadge.xyz/) / OpenAPI vs Agent Readiness # OpenAPI vs agent readiness — is OpenAPI enough? OpenAPI is necessary but not sufficient for agent readiness. An OpenAPI spec describes endpoints, but agent readiness also requires discoverability (robots.txt, llms.txt), an agent guide, structured error responses, rate limit declarations, pricing information, and consistency between documentation and implementation. ## Explanation OpenAPI is the foundation of agent readiness — but it is only the foundation. Many teams assume that publishing an OpenAPI spec makes their API agent-ready. It does not. OpenAPI describes what endpoints exist; agent readiness ensures agents can find, understand, and successfully use those endpoints. **What OpenAPI covers well:** endpoint paths, HTTP methods, request parameters, request body schemas, response schemas, authentication schemes, and status codes. A well-written OpenAPI spec tells an agent exactly what to call and what to expect back. This is necessary and valuable. **What OpenAPI misses entirely:** - **Discovery** — OpenAPI does not tell agents where to find the spec itself. An agent needs `robots.txt` or `llms.txt` to discover the OpenAPI URL. Without discovery, the spec is invisible. - **Agent guide** — OpenAPI describes the "what" but not the "how." An agent guide explains authentication flows in practice, common usage patterns, idempotency keys, pagination conventions, and workflow sequences. Agents need this context to use the API correctly. - **Error handling** — OpenAPI can define error response schemas, but it does not enforce structured error formats. An agent-ready API returns RFC 7807 Problem Details (`application/problem+json`) with consistent fields. Many APIs with OpenAPI specs still return plain text errors or inconsistent JSON error shapes. - **Rate limits** — OpenAPI can document rate limits in the description, but the actual enforcement happens via headers. Agent-ready APIs return `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `Retry-After` headers. Agents use these to self-throttle. - **Pricing** — OpenAPI has no standard way to declare pricing. An agent needs to know if an endpoint costs money before calling it. Agent-ready APIs expose a `pricing.json` endpoint or declare costs in `llms.txt`. - **Consistency** — OpenAPI describes the contract, but the live API may diverge. Agent readiness includes verification — checking that actual responses match the documented schema. Tools like AgentBadge scan for these inconsistencies. The gap between "has OpenAPI" and "agent-ready" is typically 6-10 additional checks. None require rewriting the API — they are metadata, headers, and documentation layers added on top. ## Example **API with perfect OpenAPI spec but failing agent readiness:** `# openapi.json — flawless spec openapi: 3.1.0 info: title: Payment API version: 1.0.0 paths: /payments: post: summary: Create payment requestBody: content: application/json: schema: type: object properties: amount: { type: number } currency: { type: string } responses: 200: description: Payment created 400: description: Bad request ` **What the agent readiness scanner finds:** `✗ AB-001: No robots.txt allowing AI agents ✗ AB-003: No llms.txt file ✗ AB-007: No agent guide ✗ AB-011: No rate limit headers in responses ✗ AB-010: No pricing.json endpoint ✗ AB-012: Errors return plain text, not application/problem+json ✓ AB-004: OpenAPI spec exists and is valid Score: 1/7 checks passed — NOT agent-ready ` The OpenAPI spec is correct but useless to agents who cannot find it, do not know how to authenticate, cannot handle errors, and get rate-limited without warning. ## What AgentBadge checks [📋 AB-004 API Specification](https://agentbadge.xyz/rules/AB-004) [🔄 AB-007 Guide and API Consistency](https://agentbadge.xyz/rules/AB-007) [⚠️ AB-012 Structured Error Responses](https://agentbadge.xyz/rules/AB-012) [⏱️ AB-011 Rate Limits Declared](https://agentbadge.xyz/rules/AB-011) [💲 AB-010 Machine-Readable Pricing](https://agentbadge.xyz/rules/AB-010) ## How AgentBadge measures this AgentBadge scans your API against 5 rules related to this topic. Each rule is checked deterministically with evidence. Run a scan to see your score. [Scan your site](https://agentbadge.xyz/#scan) ## Related [How to make an API agent-ready?](https://agentbadge.xyz/how-to-make-an-api-agent-ready) [What is an AI-ready API?](https://agentbadge.xyz/what-is-an-ai-ready-api) [How do AI agents use APIs?](https://agentbadge.xyz/how-ai-agents-use-apis) ![](https://agentbadge.xyz/icons/logo-32.webp) AgentBadge · Agency for the agentic web — agent-ready infrastructure on Arc & Hedera [![AgentBadge MCP on mcprush — grade A](https://mcprush.com/badge/agentbadge-mcp/card.svg)](https://mcprush.com/spreadzp/agentbadge-mcp) Services [Scanner](https://agentbadge.xyz/services/scanner) [Passports](https://agentbadge.xyz/services/passports) [Marketplace](https://agentbadge.xyz/services/marketplace) Guides [Agent Guide](https://agentbadge.xyz/agent-guide) [Market Guide](https://agentbadge.xyz/market-guide) [Medical Guide](https://agentbadge.xyz/medical-guide) [Blog](https://agentbadge.xyz/blog) Product [FAQ](https://agentbadge.xyz/faq) [Rules](https://agentbadge.xyz/rules) [Use Cases](https://agentbadge.xyz/use-cases) [Pricing](https://agentbadge.xyz/pricing) [Changelog](https://agentbadge.xyz/changelog) Company [About](https://agentbadge.xyz/about) [Services](https://agentbadge.xyz/services) [Work With Us](https://agentbadge.xyz/work-with-us) [Medical Demo](https://agentbadge.xyz/ui/medical-demo) [HashScan](https://hashscan.io/testnet/transaction/) support@agentbadge.xyz Engineering [Services](https://agentbadge.xyz/services) [Work With Us](https://agentbadge.xyz/work-with-us) [Team](https://agentbadge.xyz/team) [About](https://agentbadge.xyz/about) Legal [Terms](https://agentbadge.xyz/terms) [Privacy](https://agentbadge.xyz/privacy) © 2026 AgentBadge. MIT License. Built on Arc & Hedera. v0.16.0 · ee9a6ba [![npm version](https://img.shields.io/npm/v/@agentbadge/mcp?style=flat-square&label=npm&color=334155)](https://www.npmjs.com/package/@agentbadge/mcp) [![Verified on SaaS Browser](https://files.saasbrowser.com/h05pfd6qctu4jsnymq6q06maaf2t)](https://saasbrowser.com/en/saas/1618369/agentbadge) [![HOL Registry: owner-verified, trust 77](https://img.shields.io/badge/HOL%20Registry-owner--verified%20%C2%B7%20trust%2077-334155?style=flat-square)](https://hol.org/registry/plugins/agentbadge%2Fagentbadge-mcp) [![mcprush grade A, trust 95/100](https://img.shields.io/badge/mcprush-A%20%C2%B7%2095%2F100-334155?style=flat-square)](https://mcprush.com/spreadzp/agentbadge-mcp)