--- title: "Methodology: how Agent Ready scores a site" description: How Agent Ready computes its agent-readability score. 59 checks across four categories — page, site, llms.txt, and agent protocols — mapped to the Vercel Agent Readability Spec and llmstxt.org standard. last_updated: 2026-05-11 canonical_url: https://agent-ready.dev/methodology --- # How Agent Ready scores a site > 59 checks across four categories, mapped to the Vercel Agent Readability Spec and the llmstxt.org standard. Every check is open and reproducible. ## What does Agent Ready measure? Agent Ready is an independent validator for the [Vercel Agent Readability Spec](https://vercel.com/docs/agent-readability) and the [llmstxt.org standard](https://llmstxt.org). The score reports how well your site exposes itself to AI agents and LLM-based clients — the same way a Lighthouse score reports how well your site performs for human users. We fetch your URL once, fan out to the discovery files and well-known endpoints AI agents probe, and grade the result. ## How is the score calculated? Two scores are reported: an **overall** agent readability score (0–100) and an **llms.txt** sub-score (0–100). The overall score is a simple percentage: count of passing checks divided by total checks, rounded. Warns and fails both count against you; `pass` is the only state that earns credit. Checks marked `unreliable` by the JS-rendering check (P23) are excluded entirely so a single architectural choice doesn't penalise four dependent checks at once. Rating bands: | Score | Rating | Meaning | |---|---|---| | 90–100 | excellent | Ready for AI citation; all critical surfaces present. | | 70–89 | good | Discoverable, but a few extractability gaps. | | 50–69 | fair | Partial coverage; multiple required surfaces missing. | | 0–49 | needs improvement | Not yet AI-readable; start with llms.txt and AGENTS.md. | ## Why is the llms.txt sub-score weighted differently? The llmstxt.org spec treats some properties as foundational and others as optional. We mirror that with weights: structural checks (file accessible, H1 present, valid markdown) count **3×**, content checks count **1×**, and the optional `llms-full.txt` presence check counts **0.5×**. The overall score is unweighted because every check on the Vercel spec is equally normative; the llmstxt.org spec is explicitly layered. ## What does each check cover? 59 checks across four categories. Site checks run once per scan; page checks run against every fetched URL; llms.txt and protocol checks run conditionally on file presence. ### Site checks (S1–S15) — 15 checks | ID | Check | |---|---| | S1 | llms.txt exists | | S2 | llms.txt Content-Type | | S3 | llms.txt not empty | | S4 | llms.txt URL format | | S5 | robots.txt — AI bots allowed | | S6 | robots.txt — /llms.txt not blocked | | S7 | robots.txt exists | | S8 | sitemap.xml valid | | S9 | sitemap.xml has lastmod | | S10 | sitemap.md exists | | S11 | sitemap.md has headings + links | | S12 | AGENTS.md exists | | S13 | AGENTS.md has required sections | | S14 | HTTPS | | S15 | Root OpenAPI spec | ### Page checks (P1–P23) — 23 checks | ID | Check | |---|---| | P1 | HTTP 200 | | P2 | Redirect chain | | P3 | Content-Type header | | P4 | x-robots-tag | | P5 | Canonical link | | P6 | Meta description | | P7 | og:title | | P8 | og:description | | P9 | HTML lang attribute | | P10 | JSON-LD present | | P11 | JSON-LD has required fields | | P12 | Section headings | | P13 | Text-to-HTML ratio | | P14 | Glossary link | | P15 | Markdown mirror exists | | P16 | Markdown frontmatter | | P17 | Alternate link (markdown) | | P18 | Link header in markdown | | P19 | Content negotiation | | P20 | Sitemap section in markdown | | P21 | Code block language tags | | P22 | API schema link | | P23 | JS rendering dependency | ### llms.txt checks (L1–L10) — 10 checks | ID | Check | Weight | |---|---|---| | L1 | File accessible | 3× | | L2 | H1 present | 3× | | L3 | Valid markdown | 3× | | L4 | Blockquote summary | 1× | | L5 | H2 file-list sections | 1× | | L6 | Link format correct | 1× | | L7 | Links are accessible | 1× | | L8 | Optional section used correctly | 1× | | L9 | Content-Type: text/plain | 1× | | L10 | llms-full.txt available | 0.5× | ### Protocol checks (C1–C11) — 11 checks Protocol checks discover-then-validate: when the relevant endpoint is absent we drop the check rather than failing it, so a marketing site doesn't score itself against agent manifests it has no reason to ship. | ID | Check | |---|---| | C1 | MCP Server Card exists | | C2 | MCP Server Card fields | | C3 | MCP OAuth Protected Resource metadata | | C4 | A2A Agent Card exists | | C5 | A2A Agent Card fields | | C6 | Wildcard agents.json | | C7 | agent-permissions.json | | C8 | UCP profile (/.well-known/ucp) | | C9 | UCP OAuth Authorization Server metadata | | C10 | x402 Payment Required response | | C11 | x402 accepts entries | ## How do we handle JavaScript-rendered pages? P23 detects pages where the static HTML response lacks data that only appears after client-side rendering — missing H1, empty body text, JSON-LD that injects after hydration. When P23 fires, the runner marks dependent checks (P10, P11, P12, P14) as `unreliable` and the scorer excludes them from both numerator and denominator. Without this, a single SPA architecture choice would compound into a 4-point score drop across unrelated checks. ## How often do we refresh the spec mapping? The Vercel Agent Readability Spec is versioned at its [canonical repository](https://github.com/vercel-labs/agent-readability); we track it and fold in new check IDs as they ship. The llmstxt.org spec changes less frequently — the structure has been stable since the late-2024 proposal. Each scan reports the spec version it was scored against, surfaced in the JSON response from the public API. ## Where is the source for each check? Every check is implemented as a single function in `src/lib/checks/{site,page,llmstxt,protocol}/`. The naming convention is `{id}-{slug}.ts` (e.g. `p11-json-ld-fields.ts`). Each file exports a check definition; the registry collects them into a single array that the runner iterates. If you want to see exactly what we're asserting, read the source — one check per file. ## Frequently asked questions ### How is the agent readability score calculated? Each check returns pass, warn, or fail. The score is the percentage of passing checks across all categories: site-wide checks (run once per scan) plus per-page checks for every URL we fetch. Warnings count toward the failing side. Checks marked unreliable by P23 — JS-rendered pages where the static HTML lacks the data — are excluded from both numerator and denominator so a single architectural choice doesn't penalise four downstream checks. ### Which spec does Agent Ready implement? The Vercel Agent Readability Spec drives the S- (site), P- (page), and C- (protocol) check series. The L- series implements the llmstxt.org specification for llms.txt files. Both specs are tracked at their canonical locations and updates are folded in when published. ### Why does my score change between scans even though I didn't change anything? Three causes. First, content negotiation (P19) depends on your origin honouring Accept headers — CDN caches can serve stale variants. Second, AI-bot crawl checks (S5) depend on what's currently in robots.txt for the rotating list of bot user-agents. Third, the protocol checks (C1–C11) discover-then-validate — if your /.well-known endpoint times out, the check drops rather than failing. Re-run; transient network errors are common. ### Why does the llms.txt score differ from the overall score? The overall score is pass/total across all 59 checks weighted equally. The llms.txt sub-score uses category weights from llmstxt.org: structural checks (file accessible, H1 present, valid markdown) count 3×; content checks count 1×; the llms-full.txt presence check counts 0.5×. Re-weighting matters here because the structural checks are foundational — a file that doesn't parse is worth less than one with the optional companion missing. ### What's the difference between the page checks and the site checks? Site checks (S1–S15) run once per scan against your root URL — they cover discovery files (llms.txt, robots.txt, sitemap.xml, AGENTS.md), HTTPS, and the OpenAPI spec probe. Page checks (P1–P23) run against every URL we fetch — they cover HTTP semantics, metadata, JSON-LD, markdown mirrors, and the static-render guarantee. A typical scan emits 15 + (23 × pages-fetched) check results. ### Why are some checks not in my scan results? Protocol checks (C1–C11) follow a discover-then-validate pattern: if your /.well-known endpoint returns 404, we drop the result rather than failing it. The same applies to the x402 probe — if the path doesn't return 402 Payment Required, neither C10 nor C11 appears. This keeps validator-only scans (e.g. an MCP server card check on a static marketing site) from showing irrelevant failures. --- Read the full guide on the web: Scan your site: API reference: ## Sitemap See the full [sitemap](https://agent-ready.dev/sitemap.md) for all pages on agent-ready.dev.