How Agent Ready scores a site

What does Agent Ready measure?

Agent Ready is an independent validator for the Vercel Agent Readability Spec and the llmstxt.org standard. 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 overallagent 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 are derived from the overall score:

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.

How is the MCP server score calculated?

The MCP server scanner is a separate tool with its own 0–100 score. It connects to a live MCP endpoint and grades the tools, resources, and prompts it advertises against MCP best practices. It is independent of the site checks above and never affects a site’s Vercel score— the M-series below is not part of the 68-check site registry.

Like the llms.txt sub-score it is weighted: tool quality (M3–M7) carries the most points, because tool definitions are what an agent reasons over. Checks that don’t apply to a given server — e.g. resource quality on a tools-only server — are excluded from both the numerator and the denominator, so a server is graded on what it actually offers, not penalised for scope. Authentication (M11) is informational only. The same rating bands apply (90+ excellent, 70+ good, 50+ fair).

What does each check cover?

68 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

Page checks (P1–P23) — 23 checks

llms.txt checks (L1–L10) — 10 checks

Protocol checks (C1–C20) — 20 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.

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 published on the Vercel Knowledge Base; 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–C20) 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 68 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.

Does the MCP server score affect my site's Vercel score?

No. The MCP server scanner (/mcp-server-scanner) is a separate tool that connects to a live MCP endpoint and grades its tools, resources, and prompts on its own 0–100 scale (the M1–M12 series). It is not one of the 68 site checks and never contributes to a site's Vercel agent-readability score. Its score is weighted toward tool quality, excludes checks that don't apply to a given server, and treats authentication as informational only.

Why are some checks not in my scan results?

Protocol checks (C1–C20) 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.