> ## Documentation Index
> Fetch the complete guide index at: https://www.synscribe.com/agentic-discovery/llms.txt
> Use this file to discover all pages before exploring further.

---
title: "Agent-Readiness Audit: Score Your Site in 30 Minutes"
description: "Run an AI visibility audit in 30 minutes: 8 pass/fail tests — llms.txt, .md URLs, registry presence, freshness — plus a 0–100 score and a fix order."
slug: /agentic-discovery/agent-readiness-audit
series: The Agentic Discovery Playbook — Part 3 of 6
last_verified: 2026-06-12
---

# The Agent-Readiness Audit: Score Yourself in 30 Minutes

> **In short:** Agent-ready documentation is fetchable, addressable, indexed, chunked, versioned, directive, discoverable, and fresh. That's eight properties you can test in 30 minutes with curl and a registry search. Use the 0–100 rubric below; 80+ matches the products winning agent traffic today. Five of the eight are docs-platform defaults, so a platform switch is often the fastest fix.

![Checklist of the eight properties of agent-grade documentation: fetchable, addressable, indexed, chunked, versioned, directive, discoverable, and fresh, each with a thirty-second pass-fail test.](/agentic-discovery/images/f9-agent-grade-checklist.svg)

## Do this now

- [ ] **Test 1 — Fetchable:** `curl -sL https://yourdocs.com/quickstart | head -50` — does the full content come back without JavaScript?
- [ ] **Test 2 — Addressable:** append `.md` to any docs URL — does raw markdown come back?
- [ ] **Test 3 — Indexed:** `curl -s https://yourdomain.com/llms.txt` — does it exist, with a one-line description per link?
- [ ] **Test 4 — Chunked:** open three random code snippets — install command, imports, and expected output all present?
- [ ] **Test 5 — Versioned:** `curl -s https://yourdocs.com/changelog.md` — machine-readable changelog with version stamps?
- [ ] **Test 6 — Directive:** search your llms.txt for "ALWAYS," "NEVER," or "deprecated" — anything there?
- [ ] **Test 7 — Discoverable:** search the [Official MCP registry](https://registry.modelcontextprotocol.io/) and [context7.com](https://context7.com) for your product — owned entry present?
- [ ] **Test 8 — Fresh:** check your Official MCP registry & Context7 entry's "Updated" field — is it under 7 days?
- [ ] **Test 9 — Corroborable (open-web search):** pick your top product claim and find a *primary or third-party* source that states it — if only your own site does, it's at risk of being killed when an agent verifies it ([Play 1](/agentic-discovery/ai-agent-web-search-and-fetch)).

> 📥 **Free resource:** [Agent-Readiness Scorecard](/agentic-discovery/resources/agent-readiness-scorecard)

## Can AI read my website? (Tests 1–3: the access layer)

### Test 1: Fetchable.

Agents are HTTP clients, not browsers.

Run `curl -sL https://yourdocs.com/<any-page>` and check whether the complete article text is in the response body.

If your docs render client-side, the agent gets an empty shell.

Gold standard, observed 2026-06-11: Next.js serves *markdown* to non-browser fetchers even on canonical URLs without `.md` — user-agent content negotiation.

**Pass:** full body for every sampled page.

**Fail:** empty or skeleton HTML.

### Test 2: Addressable.

Append `.md` to five docs URLs (`https://yourdocs.com/payments/quickstart.md`) and check for raw markdown with `Content-Type: text/markdown`. 

Stripe, Supabase, Bun, Polar, Prisma, and Vercel all ship this convention; it gives every page a stable, token-cheap address an agent can fetch and re-fetch. 

**Pass:** works across the docs. 

**Partial:** some sections only. 

**Fail:** 404s.

### Test 3: Indexed.

Fetch `https://yourdomain.com/llms.txt` (and your docs subdomain). 

A passing file has 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`. 

The reference: [Stripe's is 654 lines with 472 described `.md` links across 26 sections](https://stripe.com/llms.txt). 

A bare list of undescribed URLs is a partial pass — the descriptions are what lexical search matches. 

**Fail:** absent (Tailwind's is confirmed absent against working controls — and only an incumbent survives that; see below).

## Is my content usable once fetched? (Tests 4–6: the quality layer)

### Test 4: Chunked.

Open three random snippets and apply the self-containment check: install command + imports + code + expected output, under a heading phrased as a task ("Hash a password"), with no near-duplicate snippets nearby. 

[Bun's llms.txt](https://bun.com/llms.txt) indexes ~190 [task-shaped guide pages](https://bun.com/docs/guides/binary/arraybuffer-to-buffer.md) — pre-chunked retrieval units phrased the way agents query. 

The payoff is measured: [Drizzle's 440 dense snippets](https://orm.drizzle.team/llms.txt) benchmark at 82.8 while [Polar's](https://polar.sh/docs/llms.txt) 2,297 score 64.7. 

**Pass:** 3/3 snippets self-contained. 

**Partial:** 1–2. 

**Fail:** 0.

### Test 5: Versioned.

Fetch `https://yourdocs.com/changelog.md` and check page frontmatter for version stamps.

Next.js stamps docs with `@doc-version: 16.2.6` and frontmatter (`url`, `version`, `lastUpdated`, `prerequisites`);

Prisma's llms.txt opens by mandating a changelog fetch: "Do not rely on training data for Prisma features. First, fetch https://www.prisma.io/changelog.md."

**Pass:** both stamps and changelog.

**Partial:** one.

**Fail:** neither.

### Test 6: Directive.

Grep your llms.txt and quickstarts for explicit agent instructions: a deprecated-API blocklist with replacements, a "check the registry for the latest version" rule, ALWAYS/NEVER phrasing. 

Stripe's llms.txt orders agents to "never recommend the Charges API" and "Never hardcode an old version number from training data".

Clerk's quickstart `.md` files are written as prompts ("Rules — ALWAYS/NEVER," "Verify Before Responding"). 

In our pilot trials (single model, n=2 per arm), a five-line directive cut outdated-pattern emission on a recent breaking change from 100% to 0% — this property is the one that fixes *wrong* defaults rather than absent ones.

**Pass:** blocklist + version rule.

**Partial:** a generic "see the docs" note. 

**Fail:** nothing.

## Will agents find me at all? (Tests 7–8: the distribution layer)

### Test 7: Discoverable.

Check the official MCP registry (if you ship an MCP server) and probe `curl -s https://yourdomain.com/.well-known/mcp.json`

Resend is the only product we found publishing well-known agent-discovery manifests, so passing this sub-check puts you early. 

Then, search context7.com for your product: is there an entry, is it your *docs site* rather than just your repo, and do you own it?

The site-vs-repo distinction is worth real points — Convex's docs-site entry benchmarks 91.6 against 79.9 for its own repo, an 11.7-point gap, because repos carry metadata noise the scorer penalizes.

Note: only ~4 directory placements show measured impact; exhaustive directory submission is not the goal. 

**Fail looks like:** Crossmint — a complete agent surface with no findable Context7 entry, invisible at decision time.

### Test 8: Fresh.

Open your MCP Registry & Context7 entry and read the "Updated" field.

The winners refresh in hours: shadcn/ui showed 28 minutes, Bun 6 hours, Supabase 14 hours (all as of 2026-06-11). 

Freshness was the strongest correlate of benchmark scores in our 17-entry dataset (Spearman ρ=−0.54; the freshest five entries average 83.6 vs 72.3 for the stalest five). Polar is the cautionary pair: strong surface, one-month-stale entry, benchmark 64.7. 

**Pass:** ≤7 days. 

**Partial:** ≤30 days. 

**Fail:** older.

## Will agents trust what they find when they search? (Test 9: the search-and-fetch surface)

Tests 1–8 audit your *structured* surface — the docs and indexes an agent pulls deliberately. But before it gets there, an agent searches the open web itself, and that's a separate surface with its own pass/fail. We score it as a bonus dimension (it sits outside the 0–100 docs rubric because it depends on third-party pages you don't own):

### Test 9a — Surfaced.

Write the query an agent would — long, dated, spec-loaded ("transactional email API SPF DKIM DMARC deliverability 2026"), not a keyword — and run it. 

**Pass:** you appear in the first page for your core category queries. 

**Fail:** competitors and listicles own the results and you're absent.

### Test 9b — Openable.

Read your top result's `<title>` and meta description as an agent would. 

**Pass:** it reads as a precise, dated answer to the query (gets fetched — agents open only ~6% of what they surface). 

**Fail:** brand slogan or vague tagline (gets skipped).

### Test 9c — Corroborable.

Take your three headline claims and look for a *primary or third-party* source stating each.

**Pass:** every claim is corroborated off your own domain. 

**Fail:** your specs exist only on your marketing pages — exactly what gets killed in the ~48% verification cut. [Play 1](/agentic-discovery/ai-agent-web-search-and-fetch) is the fix.

> Synscribe built a free Mac app, Birdseye, that lets you instrument coding agents like Claude Code and Codex to see what they see and how they decide on what they found. [Download Birdseye](/agentic-discovery/resources/birdseye).

## How do I score it? (the 0–100 rubric)

Score each test full, half, or zero. 

Weights are ours, set from the evidence.

| # | Property | Weight | Full points | Half | Zero |
|---|---|---|---|---|---|
| 1 | Fetchable | 10 | Every sampled page returns complete body to a no-JS fetch | Some pages JS-walled | Empty shells |
| 2 | Addressable | 10 | `.md` works across the docs (5/5 spot-checks) | Some sections | None |
| 3 | Indexed | 15 | llms.txt with described links + llms-full.txt | Exists, links undescribed or marketing copy | Absent |
| 4 | Chunked | 15 | 3/3 sampled snippets self-contained, task-shaped headings | 1–2 of 3 | 0 of 3 |
| 5 | Versioned | 5 | Version stamps + machine-readable changelog.md | One of the two | Neither |
| 6 | Directive | 15 | Deprecated blocklist + version-check rule (ALWAYS/NEVER) | Generic pointer | Nothing |
| 7 | Discoverable | 15 | Owned docs-site registry entry (+ MCP registry / .well-known if applicable) | Indexed but unclaimed or repo-only | Absent from indexes |
| 8 | Fresh | 15 | Entry updated ≤7 days | ≤30 days | Older |

**Reading your total:**

**80–100** — agent-grade; this is where the products winning agent traffic operate. 

**60–79** — readable but losing share to better-surfaced competitors. 

**40–59** — partially visible; agents fall back on training priors. 

**<40** — invisible to agents.

One asterisk: Tailwind would score near the floor and still sits in the retrieval top 10 — incumbent privilege carried by training data and third-party indexing. That path is closed to everyone who isn't already famous.

## What do good and failing look like in the wild?

From our 18-product audit (all observations 2026-06-11): <!-- EXT: vertical benchmark reports — slot for future data -->

| Product | What we observed | Audit verdict |
|---|---|---|
| **Stripe** | 654-line llms.txt, 472 described `.md` links, directive section ordering agents off the Charges API, remote MCP | The model for Tests 3 and 6 |
| **Bun** | ~190 task-shaped guides, docs-MCP with grep tools, entry updated 6 h | The model for Tests 4 and 8 |
| **Resend** | Sitewide markdown (even `pricing.md`), `.well-known/mcp.json` + agent-skills manifests, benchmark 92.3 — highest we observed | The model for Tests 2 and 7 |
| **Next.js** | Markdown via content negotiation, `@doc-version` stamps, full frontmatter | The model for Tests 1 and 5 |
| Tailwind | No llms.txt, no `.md` mirrors, no MCP | Fails 2–7; survives on incumbent privilege — don't copy this |
| Hono | Three-tier llms.txt, but Context7 repo entry = 48 snippets / 3,267 tokens, benchmark 63.3 | Passes Test 3, fails Test 7: surface without a working index entry |
| Crossmint | Full Mintlify surface + docs MCP, no findable Context7 entry | Fails Test 7: surface without distribution |
| Polar | llms.txt + `.md` + production *and* sandbox MCP — but entry 1 month stale, benchmark 64.7 | Fails Test 8: staleness drags everything |
| Drizzle | llms-full.txt is 94KB of raw MDX with framework imports left in | Partial on Test 3 — the MDX-leak failure mode (its snippet density saves it anyway) |

## What do I fix first?

Work the audit failures in this order — each row points into the play that fixes it:

| If you failed | Fix with | Typical effort |
|---|---|---|
| Tests 1–3 (access layer) | [Play 5: llms.txt](/agentic-discovery/llms-txt) + [Play 6: markdown docs](/agentic-discovery/markdown-docs-for-ai-agents) — or switch docs platforms: five of the eight properties arrive as platform defaults | Days |
| Test 7 (discovery) | [Play 2: registries](/agentic-discovery/ai-agent-registries-and-directories) + [Play 3: MCP distribution](/agentic-discovery/mcp-server-distribution) — claiming and curating your index entry is the highest-leverage 30 minutes in this playbook | Week 1 |
| Test 6 + 5 (directives, versioning) | [Play 8: stop AI using deprecated APIs](/agentic-discovery/stop-ai-using-deprecated-apis) | Week 2 |
| Test 4 (chunking) | [Play 7: code snippets for AI agents](/agentic-discovery/code-snippets-for-ai-agents) | Weeks 2–4 |
| Test 8 (freshness) | Re-parse trigger on every docs deploy; weekly tracking per [Part 5](/agentic-discovery/measure-ai-visibility) | Hours to set up, forever to keep |
| Test 9 (search/fetch) | [Play 1: get surfaced in agent web search](/agentic-discovery/ai-agent-web-search-and-fetch) — fetch-worthy snippets + corroborate every claim off-domain | Ongoing content discipline |

## The receipts

*Research layer — where the eight properties come from. Full data in the [Data Room](/agentic-discovery/data).*

The properties synthesize a live audit of 18 developer products' agent-facing surfaces (llms.txt contents, `.md` probes with observed Content-Types, MCP endpoints, scaffolder behavior), cross-read against Context7's published scoring stack. Each property maps to an observed exemplar and a concrete eval:

| # | Property | Exemplar observed | Eval |
|---|---|---|---|
| 1 | Fetchable | Next.js (markdown via content negotiation) | curl-equivalent fetch returns complete body |
| 2 | Addressable | Stripe, Supabase, Bun, Polar, Prisma, Vercel | automated `.md` probe across the sitemap |
| 3 | Indexed | Stripe (472 described links), Bun | llms.txt linter + token budget check |
| 4 | Chunked | Bun's 190 task guides; Drizzle's density | self-containment + uniqueness scoring |
| 5 | Versioned | Next.js, Prisma | frontmatter audit; changelog fetch test |
| 6 | Directive | Stripe, Clerk, Prisma | deprecation eval: does an agent with your docs still emit old patterns? |
| 7 | Discoverable | Resend (well-known URIs), Convex | registry presence checklist; search-API spot checks |
| 8 | Fresh | shadcn (28 min), Bun (6 h), Supabase (14 h) | monitor the entry's "Updated" field; alert at >7 days |

Numbers quoted on this page: freshness–benchmark correlation ρ=−0.54 (n=17, correlational, non-random sample of audited winners plus counterexamples); fresh-vs-stale benchmark gap 11.3 points (83.6 vs 72.3); Convex site-vs-repo gap 11.7 points (91.6 vs 79.9); Drizzle 440 snippets at benchmark 82.8 vs Polar 2,297 at 64.7; E3 directive result 100%→0% (pilot-grade: single model, n=2 per arm). Treat single-snapshot registry metrics as ±10% — we observed the same product reading 130 snippets on one surface and 207 on another the same day. The audit set is winners plus counterexamples, so it carries survivorship bias; scoring high on this rubric is what the winners *do*, which is not yet proof of what *causes* winning.

## FAQ

**Can AI read my website?**
Run one command to find out: `curl -sL https://yourdocs.com/<page>` — if the full text isn't in the response, AI agents can't read that page, because agents are HTTP clients, not browsers. Client-side-rendered docs are the most common failure. Test 1 above scores it; Play 6 fixes it.

**What is an AI visibility audit?**
An AI visibility audit tests whether AI agents can fetch, parse, trust, and act on your documentation — distinct from an SEO audit, which tests human search rankings. This page's version is eight pass/fail tests (fetchable, addressable, indexed, chunked, versioned, directive, discoverable, fresh) scored 0–100, runnable in about 30 minutes with curl and two registry searches.

**Do I need an llms.txt file?**
Treat llms.txt as necessary plumbing, not proven magic. It's verifiably consumed by retrieval workflows and shipped by nearly every product winning agent traffic, but no major LLM provider officially confirms using it for ranking — and Tailwind ranks top-10 without one (incumbent privilege). It's 15 of the 100 points here; see [Part 6](/agentic-discovery/geo-myths-what-doesnt-work) for the full evidence both ways.

**What is a good agent-readiness score?**
80 or above puts you in the pattern of the products that win agent retrieval today — Stripe, Bun, Resend, and Next.js each pass essentially every test. 60–79 means agents can read you but better-surfaced competitors out-rank you; below 40, agents fall back on whatever their training data remembers, which usually means a competitor.

**How often should I re-run this audit?**
Check freshness (Test 8) weekly and re-run the full audit quarterly. This layer decays fast — the strongest correlate of quality scores is recency, and we watched one library lose 50% of its retrieval share in 30 days. Set a re-parse trigger on every docs deploy so freshness maintains itself.

---

*Last verified 2026-06-12. We re-test the claims on this page quarterly — changes are logged in the [Data Room](/agentic-discovery/data).*

**Part of [The Complete Playbook to Agentic Discovery](/agentic-discovery).**

← Previous: [How AI Agents Actually Choose Products](/agentic-discovery/how-ai-agents-choose-products) · Next: [The Playbook: 11 Plays](/agentic-discovery/agentic-discovery-playbook) →

> **Stay ahead of the agents.** We re-test this playbook quarterly and publish what changed — new data, busted myths, ranking shifts. [Get the update digest →](/agentic-discovery#updates)
>
> **Want this done for you?** Synscribe runs agentic-discovery programs for B2B SaaS and developer platforms. [Talk to us →](/contact)