How we score what an agent can read.
The Agent Readability Score measures one thing: how well an AI agent — not a human — can read your public documentation and complete a real task against your API. Published, versioned, and reproducible from stored inputs.
How to read a grade
Every score is 0–100, banded: green 80+ (an agent can reliably self-serve most first tasks), amber 50–79 (workable, with gaps that cost the agent tries), red <50 (an agent is likely to stall or abandon common tasks).
The three categories
| Category | Weight | The question it answers |
|---|---|---|
| Deterministic checks | 40% | Are the machine-checkable fundamentals present and well-formed? Valid root llms.txt; a discoverable OpenAPI spec that validates; sane heading structure; code samples on reference pages; auth documented with an example; pages within an agent-friendly token budget; working links; crawler/meta hygiene. |
| LLM-rubric checks | 35% | Is the prose clear, complete, and consistent enough for an agent to act on? A pinned model (claude-sonnet-5) grades key pages on clarity, instruction completeness, and terminology consistency. The model ID, exact prompt, and raw structured output are stored with every score. |
| Micro-task probes | 25% | Can a real agent actually finish? Three standardized tasks — find the auth method, find the rate limits, construct a first valid request — graded deterministically on substance and citation, never on the agent's self-claim. Full transcripts are saved. |
Task completion (probes + rubric, 60%) deliberately outweighs static structure (40%): you cannot top the Index by adding an llms.txt and nothing else.
How we crawl — good agent citizenship
- Public pages only. No logins, no paywalled or private content.
- We obey robots.txt. A site that disallows automated access is excluded, not scored. (Index #1 excluded: Cohere, WorkOS, Salesforce.)
- Polite by default. One request per second, an identifying user-agent, a hard page cap.
- No dark-pattern discovery. Ordinary same-origin links only; we don't probe hidden endpoints.
Scored as a non-JavaScript agent
Rubric v0 reads the HTML an agent receives without executing JavaScript — the behavior of a large class of real agents. Docs that render client-side arrive as near-empty shells and score accordingly. That is a real finding about that agent class, not a browser-quality verdict.
We verified this axis with a controlled JavaScript-render comparison on the ten lowest-rubric sites. Where rendering decisively changed the verdict — docs that are genuinely strong but invisible without a browser — we applied the rendered score and flagged the row † JS-REQUIRED. Sites that moved somewhat but not decisively are flagged ‡; their fetch-only score stands. For half the sites, rendering changed nothing: the low score is real.
Anti-gaming
- Task completion outweighs static checks (60/40) — structural box-ticking can't carry a low-substance site to the top.
- Hidden holdout checks rotate quarterly and are not published.
- Every scoring change ships as a dated, public changelog entry — no silent re-weighting.
Reproducibility & corrections
Each score is reproducible from its stored inputs: the crawl snapshot, pinned model IDs, rubric version, exact prompts, and raw outputs. If you believe a score reflects a crawl error — a page we couldn't reach that a normal agent can — email corrections@prolectio.com and we'll re-run against a corrected snapshot and publish the update. Accuracy is the product; we'd rather fix a real miss than defend a number.
What this Index is not
- Not a rating of the product or the API. Excellent engineering can ship agent-hostile docs, and vice-versa.
- Not a claim about every agent. Scores come from a pinned Claude model reading like an agent would; we publish the model so results are interpretable, not universal.
- Not permanent. Docs change; scores are dated snapshots (this edition: 2026-07-19) and we re-scan on a published cadence.
- Not a penalty for excluding bots. Respecting robots.txt is legitimate; we respect it back.
Changelog
- v0 (2026-07-19) — initial public rubric: deterministic checks (golden-set tested), LLM rubric pinned to
claude-sonnet-5, micro-task probe harness with deterministic substance grading. JS-render comparison pass added; †/‡ flags introduced.