Agent-Readiness Scorecard

What this is: the fillable worksheet version of the Agent-Readiness Audit. It gives you eight 30-second tests, a 0–100 score, and a pointer to the play that fixes each failure.

How to use it:

• Print it or copy it into a doc, fill in the header block, and budget 30 minutes with a terminal open. You only need curl plus two registry searches.
• Run each test exactly as written, mark □ pass □ partial □ fail, record the points, and paste one line of evidence (the command output or URL you saw) so the next audit can diff against it.
• Sum the points, read your band, then work the fix-order table top to bottom. Re-check Test 8 (freshness) weekly; re-run the full audit quarterly.

Audit header

Domain audited:   _______________________________________________
Docs base URL:    _______________________________________________
Date of audit:    _______________________________________________
Auditor:          _______________________________________________
Total score:      _________ / 100

The eight tests

Test 1 · Fetchable · 10 points

• 30-second test: run curl -sL https://yourdocs.com/<any-page> | head -50 and sample a few pages. Agents are HTTP clients, not browsers.
• Expected pass: the complete article text is in the response body for every sampled page, no JavaScript required.
• Partial (5): some pages JS-walled. Fail (0): empty or skeleton HTML shells.
• Field reference: Next.js serves markdown to non-browser fetchers using user-agent content negotiation, even on canonical URLs.

Result: □ pass (10) □ partial (5) □ fail (0) · Points: ______ Evidence / notes: __________________________________________________________

Test 2 · Addressable · 10 points

• 30-second test: append .md to five docs URLs (e.g. https://yourdocs.com/payments/quickstart.md) and fetch each.
• Expected pass: raw markdown with Content-Type: text/markdown on 5/5 spot-checks, across the docs.
• Partial (5): works in some sections only. Fail (0): 404s.
• Field reference: Stripe, Supabase, Bun, Polar, Prisma, and Vercel all ship this convention.

Result: □ pass (10) □ partial (5) □ fail (0) · Points: ______ Evidence / notes: __________________________________________________________

Test 3 · Indexed · 15 points

• 30-second test: run curl -s https://yourdomain.com/llms.txt, then repeat at your docs subdomain.
• Expected pass: the file exists with a title, a one-line product definition in task words, sectioned links each with a one-line description, and a link to llms-full.txt.
• Partial (7.5): file exists but links are undescribed or marketing copy. Fail (0): absent.
• Field reference: Stripe has 654 lines and 472 described .md links across 26 sections. The descriptions are what lexical search matches.

Result: □ pass (15) □ partial (7.5) □ fail (0) · Points: ______ Evidence / notes: __________________________________________________________

Test 4 · Chunked · 15 points

• 30-second test: open three random code snippets and apply the self-containment check.
• Expected pass: 3/3 snippets have install command + imports + code + expected output, under a heading phrased as a task ("Hash a password"), with no near-duplicate snippets nearby.
• Partial (7.5): 1–2 of 3. Fail (0): 0 of 3.
• Field reference: Bun has about 190 task-shaped guide pages, pre-chunked into retrieval units phrased the way agents query. Drizzle's 440 dense snippets benchmark at 82.8 vs Polar's 2,297 at 64.7.

Result: □ pass (15) □ partial (7.5) □ fail (0) · Points: ______ Evidence / notes: __________________________________________________________

Test 5 · Versioned · 5 points

• 30-second test: run curl -s https://yourdocs.com/changelog.md and check page frontmatter for version stamps.
• Expected pass: you want both: version stamps in the docs and a machine-readable changelog.md.
• Partial (2.5): one of the two. Fail (0): neither.
• Field reference: Next.js stamps docs with @doc-version: 16.2.6 and full frontmatter. Prisma's llms.txt opens by mandating a changelog fetch.

Result: □ pass (5) □ partial (2.5) □ fail (0) · Points: ______ Evidence / notes: __________________________________________________________

Test 6 · Directive · 15 points

• 30-second test: search your llms.txt and quickstarts for "ALWAYS," "NEVER," or "deprecated."
• Expected pass: a deprecated-API blocklist with replacements plus a "check the registry for the latest version" rule, in ALWAYS/NEVER phrasing.
• Partial (7.5): a generic "see the docs" note. Fail (0): nothing.
• Field reference: Stripe ("never recommend the Charges API," "Never hardcode an old version number from training data"); Clerk's quickstart .md files written as prompts. This is the property that fixes wrong defaults rather than absent ones.

Result: □ pass (15) □ partial (7.5) □ fail (0) · Points: ______ Evidence / notes: __________________________________________________________

Test 7 · Discoverable · 15 points

• 30-second test: search context7.com and the official MCP registry for your product, then probe curl -s https://yourdomain.com/.well-known/mcp.json.
• Expected pass: an owned registry entry for your docs site (not just your repo), plus MCP registry presence and a .well-known manifest if you ship an MCP server.
• Partial (7.5): indexed but unclaimed, or repo-only. Fail (0): absent from indexes.
• Field reference: Convex's docs-site entry benchmarks 91.6 vs 79.9 for its own repo, an 11.7-point gap. Resend is the only product we found publishing well-known agent-discovery manifests. Fail looks like Crossmint: a complete agent surface with no findable Context7 entry.

Result: □ pass (15) □ partial (7.5) □ fail (0) · Points: ______ Evidence / notes: __________________________________________________________

Test 8 · Fresh · 15 points

• 30-second test: open your Context7 entry and read the "Updated" field.
• Expected pass: updated ≤7 days ago.
• Partial (7.5): ≤30 days. Fail (0): older.
• Field reference: the winners refresh in hours: shadcn/ui 28 minutes, Bun 6 hours, Supabase 14 hours (all as of 2026-06-11). Freshness was the strongest correlate of benchmark scores (Spearman ρ=−0.54, n=17). Polar's one-month-stale entry benchmarks 64.7 despite a strong surface.

Result: □ pass (15) □ partial (7.5) □ fail (0) · Points: ______ Evidence / notes: __________________________________________________________

Scoring table

Score each test full, half, or zero, then sum to 0–100.

Reading your total

One asterisk: an established player can score near the floor and still rank. Tailwind would score near the floor and sits in the retrieval top 10 on training-data mass and third-party indexing. That path is closed to everyone who isn't already famous.

Fix order

Work the failures in this order; each row points into the play that fixes it.

Last verified 2026-06-11. All tests, weights, and thresholds trace to the parent guide.

Parent guide: Agent-Readiness Audit: Score Your Site in 30 Minutes · Hub: The Complete Playbook to Agentic Discovery