API Documentation and Agent Readiness: Why Mintlify Scores 66 and ReadMe Doesn't
Documentation is the bridge between an API and an AI agent. When documentation is structured, current, and machine-readable, agents can self-teach your API in seconds. When it is a stale PDF or a JavaScript-rendered page that returns blank HTML, agents see nothing. Documentation tools themselves have wildly different agent readiness — and the platform you choose directly impacts your score.
The Documentation Divide: Platform Scores
Documentation platforms are an interesting test case for agent readiness because they are built to make technical information accessible. You would expect them to score well. Some do. Most do not. The gap between the best and worst documentation tools is 58 points — nearly the same range as the entire 500-business scan.
Mintlify leads at 66 Silver because it was designed with machine-readability as a first-class concern. It generates static HTML, renders OpenAPI specs inline with structured navigation, exposes endpoint metadata in crawlable format, and ships with SEO and schema markup out of the box. When an agent crawls a Mintlify-powered docs site, it finds everything it needs without executing JavaScript.
The drop-off from there is steep. GitBook and Docusaurus are solid Bronze performers because they also generate static content but lack Mintlify's OpenAPI-first approach. ReadMe falls behind because it renders content client-side — agents that do not execute JavaScript see empty pages. And Notion, increasingly used as a documentation platform, is essentially invisible to agents.
Five Things Agents Need From Your Documentation
Agents read documentation differently than developers. They do not browse — they extract. They need five specific types of information, each mapping to a scoring dimension.
Current OpenAPI spec
D2 API Quality (0.15)Agents auto-generate client libraries from OpenAPI. Outdated specs mean broken calls.
Example requests and responses
D6 Data Quality (0.10)Agents learn by example. A request/response pair teaches more than paragraphs of description.
Error code reference
D6 Data Quality (0.10)Agents need to know what 422 with code "invalid_amount" means and how to fix it. Error tables are critical.
Authentication guide
D7 Security (0.12)How to get a token, what scopes exist, where to pass the Bearer header. Agents cannot guess auth flows.
Changelog with dates
D8 Reliability (0.13)Agents need to know if the API changed since they last cached the schema. Breaking changes without changelogs cause silent failures.
Together, these five documentation elements directly impact D2 API Quality (0.15), D6 Data Quality (0.10), D7 Security (0.12), and D8 Reliability (0.13) — a combined 50% of the Agent Readiness Score. Documentation is not a nice-to-have. It is half your score.
The Business Documentation Problem
Documentation platforms scoring 50-66 is encouraging. But those platforms are the exception. When we look at how actual businesses document their APIs, the picture collapses. Of 500 businesses scanned by AgentHermes:
The issue is not that businesses lack APIs — many have internal APIs powering their mobile apps and web frontends. The issue is that those APIs are undocumented, undiscoverable, and assume a human will figure out the integration through trial and error. Agents do not figure things out through trial and error. They read structured documentation or they move on.
AgentHermes checks documentation quality through two dimensions: D2 API Quality (0.15 weight) evaluates whether an OpenAPI spec exists and whether it is current, and D6 Data Quality (0.10 weight) checks for structured error responses, example payloads, and consistent data formats. A business can have a working API but still score poorly if agents cannot understand how to use it.
Five Documentation Anti-Patterns That Kill Agent Readiness
The Documentation Fix: From Zero to Agent-Readable in a Day
Fixing documentation for agent readiness follows a specific order. Each step unlocks a scoring improvement, and the first three can be done in a single afternoon.
Publish an OpenAPI spec at a predictable URL
Serve your spec at /openapi.json or /api-docs. This single file unlocks D2 API Quality. Tools like swagger-jsdoc or @asteasolutions/zod-to-openapi auto-generate specs from existing code. Cost: 2-4 hours. Score impact: +8 to +12 points.
Add example requests and responses to every endpoint
OpenAPI supports the "example" field on every parameter, request body, and response. Fill them in with realistic data. Agents use these to construct their first API call. Cost: 1-2 hours. Score impact: +3 to +5 points.
Document error codes in a structured table
List every error code your API returns with its HTTP status, machine-readable code, human description, and suggested fix. Publish this as both a docs page and a JSON endpoint at /api/errors. Cost: 1 hour. Score impact: +2 to +4 points.
Ship an llms.txt file
A simple markdown file at /llms.txt that describes your API, links to the OpenAPI spec, and provides a quick-start guide. Takes 15 minutes and directly boosts D1 Discovery. Cost: 15 minutes. Score impact: +2 to +3 points.
Generate an SDK from your spec
Use openapi-generator or Speakeasy to produce typed client SDKs. Publish to npm/PyPI. Agents that find a ready-made SDK skip the API-learning step entirely. Cost: 1 hour. Score impact: +2 to +3 points.
Total impact: Steps 1-5 can lift a business from zero documentation score to +17 to +27 points across D2, D6, D7, and D8. For a business currently at 30 (Not Scored), this alone pushes into Bronze. For one at 45 (Bronze), it can push into Silver. Documentation is the single highest-ROI fix for agent readiness because it impacts the most dimensions per hour of work. See also: auto-generated SDKs for the full D2 playbook.
Frequently Asked Questions
Does documentation quality really affect my Agent Readiness Score?
Yes. Documentation directly impacts D2 API Quality (0.15 weight) and D6 Data Quality (0.10 weight), which together account for 25% of your score. A published OpenAPI spec with examples and error codes can add 10-15 points. Missing documentation caps multiple dimensions.
Why does Mintlify score higher than ReadMe?
Mintlify generates static HTML with structured content that agents can crawl directly. It renders OpenAPI specs inline with clear endpoint grouping and example blocks. ReadMe relies more heavily on client-side JavaScript rendering, which means some content is invisible to agents that do not execute JS. Mintlify also ships with better default SEO and schema markup.
Is Swagger UI enough for agent readiness?
Swagger UI is a good start but not sufficient. The key is whether you also expose the raw OpenAPI spec file at a predictable URL like /openapi.json or /api-docs. Many Swagger UI deployments render the spec visually but do not link to the downloadable file. Agents need the raw spec, not the rendered UI.
What if my documentation is in Notion?
Notion-hosted documentation scores very low for agent readiness. Notion pages are rendered client-side, require authentication for private pages, have no OpenAPI spec, and lack structured API metadata. If your docs are in Notion, the fastest fix is to export them to a static documentation platform like Mintlify or Docusaurus and add an OpenAPI spec.
How does your documentation score?
Run a free Agent Readiness Scan and see exactly how your API documentation impacts your score across D2 API Quality and D6 Data Quality.