agentready

Documentation

How AgentReady works

AgentReady fetches one public page the way a non-rendering agent does — the raw HTML plus the machine signals around it — runs six independent checks, and returns a 0–100 score with evidence-backed findings and copy-paste fixes. No account, no storage: URL in, report out.

The six checks

Agent discovery (18%)
robots.txt, sitemap.xml, llms.txt, feeds, OpenAPI links, and MCP well-known files — can an agent locate the site's machine entry points?
Machine-readable structure (18%)
JSON-LD with a schema.org context, semantic landmarks, a clean heading outline, canonical metadata — can an agent tell what the page is without guessing?
Access & renderability (18%)
Response headers, bot-management and CAPTCHA signals, and JavaScript-dependence heuristics — does the fetched HTML actually contain the content?
Form semantics (16%)
Labels, names, input types, autocomplete — if an agent finds a form, can it tell what each field wants? Pages with no forms are exempt, not penalised.
Actionability (15%)
Real links, buttons and forms versus click-handler soup — of the things a person can do here, how many can an agent invoke?
WebMCP capability (15%)
Declarative tool attributes on forms, imperative registerTool references, the polyfill, and the policy headers that gate the API. Where nothing is declared, the report generates a starter tool from the page's own first form.

The honesty rules

  • Unknown never becomes zero: what a check cannot observe is excluded from the score and lowers the visible coverage percentage, and every category carries a confidence label.
  • A blocked fetch (robots.txt disallow, bot challenge) produces a no-score report — it proves our request was refused, not that agents in a browser are.
  • robots.txt is honoured before any page — including every redirect target — is fetched.
  • The “+N with WebMCP” number is computed by re-scoring the same page with WebMCP at full marks, never a constant.
  • Grades change when the rubric changes; treat any published score as a dated observation.

API

Machine-readable description: /openapi.json (OpenAPI 3.1). Agent orientation: /llms.txt.

POST /api/audit          {"url": "https://example.com"}   → full JSON report
GET  /report?url=<url>   server-rendered HTML report (works without JavaScript)
GET  /api/card?url=<url> 1200×630 PNG share card

Rate limit: best-effort, ~12 requests/min per client per instance. Only public http/https URLs on ports 80/443 are audited; private and internal addresses are refused.

WebMCP tools on this site

AgentReady practises what it measures. In a WebMCP-capable browser (ChatGPT’s in-app browser, or Chrome with the WebMCP flag), the landing page exposes audit_site — an agent can run a full audit and read back the score, grade, coverage and top finding. The demo bistro additionally declares its reservation form as a tool and registers an availability checker.

Methodology & source

The full rubric, the safe-fetch security invariants, and every check’s implementation are open source (MIT): github.com/fyzycyst/AgentReady. Weights live in one file; scoring maths in another; each check is a pure function with fixture tests.