{ "_comment": "Machine-readable twin of the Open Agent-Readiness Rubric. The prose version at https://agentexperience.tech/insights/agent-readiness-rubric/ is canonical; this file carries the same criteria, checks and weights and is updated in the same change. A score describes the surfaces a site has declared. It is not a prediction of agent success, traffic, revenue, or ranking.", "name": "The Open Agent-Readiness Rubric", "url": "https://agentexperience.tech/insights/agent-readiness-rubric/", "canonicalGuide": "https://agentexperience.tech/insights/agent-readiness-rubric/", "version": "0.1", "status": "draft", "publisher": "agentexperience.tech", "license": "CC BY 4.0", "datePublished": "2026-09-01", "dateModified": "2026-09-01", "scoring": { "method": "weighted-sum", "criterionScale": [ { "value": 0, "label": "absent", "meaning": "The criterion is not met." }, { "value": 0.5, "label": "partial", "meaning": "The criterion is met for some of the site or product, or met in a way an agent cannot rely on." }, { "value": 1, "label": "met", "meaning": "The criterion is met across the surfaces an agent would reasonably encounter." } ], "criterionScore": "score = value * weight", "totalScore": "sum of all criterion scores; weights total 100", "dimensionScore": "sum of criterion scores in the dimension, divided by the dimension weight, expressed 0-100", "notApplicable": "Mark a criterion N/A only when the surface does not exist at all (for example, action-safety criteria on a read-only reference site). Renormalise remaining weights to 100 and record which criteria were excluded.", "reportingRules": [ "Publish the per-dimension subscores, not only the total.", "Publish the date of assessment and the tool or method used.", "A score describes observable surface properties. It is not a prediction of agent success, traffic, revenue, or ranking." ], "descriptiveBands": [ { "range": "0-24", "label": "Unmapped", "meaning": "An agent has little to work with beyond rendered HTML." }, { "range": "25-49", "label": "Readable", "meaning": "Content is findable and parseable; actions and policy are mostly undeclared." }, { "range": "50-74", "label": "Navigable", "meaning": "Discovery, structure and content surfaces are deliberate; action and recovery surfaces are partial." }, { "range": "75-100", "label": "Actionable", "meaning": "Agents can find, read, act, fail safely, and be told what is permitted." } ] }, "dimensions": [ { "id": "DIS", "dimension": "Discovery", "weight": 20, "question": "Can an agent find the content and capabilities that exist here, without guessing?", "criteria": [ { "id": "DIS-01", "criterion": "A parseable robots.txt exists", "check": "GET /robots.txt. Expect 200, text/plain, and no HTML error page returned with a 200 status.", "why": "robots.txt is the oldest and most widely honoured machine-readable statement a site makes. A 200 that returns an HTML soft-404 is worse than a 404, because parsers treat it as a rule set.", "weight": 3 }, { "id": "DIS-02", "criterion": "An XML sitemap exists and is referenced from robots.txt", "check": "GET /sitemap.xml (or the path named in robots.txt). Confirm a Sitemap: line in robots.txt and that listed URLs return 200.", "why": "A sitemap is the cheapest complete inventory of a site. Retrieval agents and crawlers both use it to avoid link-graph traversal.", "weight": 3 }, { "id": "DIS-03", "criterion": "Directives for AI and agent user-agents are explicit and intentional", "check": "Read robots.txt for named AI user-agents (for example GPTBot, OAI-SearchBot, ClaudeBot, Google-Extended, PerplexityBot). Confirm the allow/deny pattern matches what the organisation actually intends, and that answer-engine crawlers are not blocked by accident.", "why": "Many sites block answer-engine fetchers while intending only to block training crawlers. The two are different user-agents with different consequences.", "weight": 3 }, { "id": "DIS-04", "criterion": "A site-level agent index exists and is current", "check": "GET /llms.txt (or the equivalent index the site has chosen). Confirm it lists real, current URLs, returns 200, and was updated in the same release cycle as the content it points at.", "why": "A stale index is an active liability: it sends agents to URLs that no longer exist. Consumption of llms.txt is uneven, so score the file on being correct and maintained, not on being present.", "weight": 3 }, { "id": "DIS-05", "criterion": "Capabilities are declared in a machine-readable manifest at a well-known path", "check": "Look for a capability manifest under /.well-known/ (for example an ARD ard.json, an A2A agent card, or an MCP server description) and confirm it validates against its published schema and points at live endpoints.", "why": "Content discovery tells an agent what to read. A capability manifest tells it what it can do. Most sites publish neither, and the ones that publish a manifest often let it drift from the live API.", "weight": 4 }, { "id": "DIS-06", "criterion": "URLs are canonical, stable, and predictable", "check": "Confirm rel=canonical on templated pages, no session identifiers in URLs, consistent trailing-slash behaviour, and 301s rather than soft redirects on moves.", "why": "An agent that re-visits a URL from an earlier step must land on the same resource. Unstable URLs break multi-step tasks and cached plans.", "weight": 2 }, { "id": "DIS-07", "criterion": "Discovery surfaces cross-reference each other", "check": "Confirm the sitemap, the agent index, the capability manifest, and the API reference each link to the others rather than existing as isolated files.", "why": "Agents arrive at one entry point, not all of them. Cross-links mean any single entry point leads to the rest.", "weight": 2 } ] }, { "id": "STR", "dimension": "Structure and semantics", "weight": 18, "question": "Does the page's machine-readable structure match what a person sees?", "criteria": [ { "id": "STR-01", "criterion": "Interactive controls use native semantic elements", "check": "Inspect the accessibility tree for the primary task path. Every control that navigates should be a link; every control that acts should be a button; form fields should be real form fields.", "why": "Browser agents read the accessibility tree. A div with a click handler has no role, no name, and no keyboard contract, so it is invisible to that reading.", "weight": 4 }, { "id": "STR-02", "criterion": "Every control has a meaningful accessible name", "check": "Enumerate controls on the primary path and confirm none resolve to an empty name, an icon glyph, or a generic label such as \"Submit\" repeated across different actions.", "why": "An agent selects an action by its name. Duplicate or empty names force it to guess by position, which breaks the moment the layout changes.", "weight": 3 }, { "id": "STR-03", "criterion": "Heading hierarchy describes the content beneath it", "check": "Extract the heading outline. Confirm one h1, no skipped levels used for styling, and headings that name their section's subject rather than a slogan.", "why": "Heading outlines are the cheapest chunking signal available to a retrieval system, and they are how an agent decides which part of a long page to read.", "weight": 2 }, { "id": "STR-04", "criterion": "Decision-critical content is present without client-side interaction", "check": "Fetch the page without JavaScript, or inspect the initial HTML payload. Confirm pricing, requirements, eligibility, and next steps are present rather than behind a tab, accordion, or hydration step.", "why": "Many agents read a fetched document rather than driving a browser. Content that only exists after interaction does not exist for them.", "weight": 3 }, { "id": "STR-05", "criterion": "Key actions have stable identifiers", "check": "Confirm primary controls carry stable ids, data attributes, or ARIA labels that survive a design change and a CSS-class rebuild.", "why": "Agents and their operators cache selectors. Hash-generated class names invalidate every cached path on each deploy.", "weight": 2 }, { "id": "STR-06", "criterion": "Structured data is present and matches visible content", "check": "Validate JSON-LD against schema.org and confirm each asserted value appears in the rendered page. Check that dates, prices, and availability agree.", "why": "Structured data that contradicts the page is worse than none, because it gives a machine a confident wrong answer.", "weight": 2 }, { "id": "STR-07", "criterion": "Application state is legible in the document", "check": "After a state-changing interaction, confirm the new state is expressed in text or ARIA state attributes rather than only in colour, position, or animation.", "why": "An agent verifies its own work by re-reading the page. State expressed only visually leaves it unable to confirm whether the step succeeded.", "weight": 2 } ] }, { "id": "MRC", "dimension": "Machine-readable content", "weight": 17, "question": "Is the substance of the site available in a form a machine can consume cheaply and exactly?", "criteria": [ { "id": "MRC-01", "criterion": "Key pages have a clean text or Markdown representation", "check": "Request the .md twin of a content URL, or request the URL with Accept: text/markdown. Confirm the returned document carries the same substance as the HTML page.", "why": "A Markdown twin removes navigation chrome, cuts token cost, and eliminates the extraction step where meaning is most often lost.", "weight": 4 }, { "id": "MRC-02", "criterion": "The machine-readable representation is advertised, not hidden", "check": "Confirm content negotiation on the canonical URL, or a Link: <...>; rel=\"alternate\"; type=\"text/markdown\" header, or an in-page link. A twin nobody can discover is not a discovery surface.", "why": "Publishing an alternate representation without advertising it means only clients that guess the convention will ever find it.", "weight": 3 }, { "id": "MRC-03", "criterion": "Programmatic surfaces publish a machine-checkable contract", "check": "Confirm a current OpenAPI document or JSON Schema for each public API, served at a discoverable URL, with the version matching the deployed service.", "why": "A schema is the only part of an API description a runtime can validate against. Prose describing an endpoint cannot catch a malformed call.", "weight": 3 }, { "id": "MRC-04", "criterion": "Publication and modification dates are visible and in metadata", "check": "Confirm a visible date on the page and a matching datePublished/dateModified in structured data or HTTP headers.", "why": "Agents and answer engines weigh freshness. A page with no date forces a consumer to either discard it or trust it blindly.", "weight": 2 }, { "id": "MRC-05", "criterion": "Pages open with a self-contained answer", "check": "Read the first 60 words under the h1 and under each h2. Confirm each is extractable as a standalone answer without the surrounding paragraph.", "why": "Retrieval systems lift passages, not pages. A passage that depends on the paragraph above it becomes wrong when quoted alone.", "weight": 2 }, { "id": "MRC-06", "criterion": "No decision-critical content is locked in images or unstructured PDFs", "check": "Inventory diagrams, pricing tables, and specification sheets. Confirm each has a text equivalent in the page or a linked structured document.", "why": "Image-only content requires a vision pass, costs more, and is read less reliably than the same content in text.", "weight": 3 } ] }, { "id": "ACT", "dimension": "Action safety", "weight": 18, "question": "When an agent acts, are the consequences declared and the guardrails enforced by the system rather than by the prompt?", "criteria": [ { "id": "ACT-01", "criterion": "Irreversible and high-consequence actions are labelled as such", "check": "For each write operation, confirm the tool description, API documentation, or UI copy states whether the action is reversible, who it is visible to, and what it costs.", "why": "An agent cannot infer that an action is irreversible. If the consequence is not stated, it will be discovered by causing it.", "weight": 4 }, { "id": "ACT-02", "criterion": "Approval for consequential actions is enforced server-side", "check": "Attempt the consequential action with a valid credential and no approval token. Confirm the server refuses, rather than relying on a client prompt or an instruction in a description.", "why": "Safety hints in tool metadata are advisory. The MCP specification is explicit that annotations are untrusted unless the server is trusted, so enforcement has to live in the service.", "weight": 4 }, { "id": "ACT-03", "criterion": "Write operations are safely retryable", "check": "Send the same write twice with the same idempotency key and confirm one effect. Confirm the key mechanism is documented.", "why": "Agents retry on timeout by default. Without idempotency, a network blip becomes a duplicate order.", "weight": 3 }, { "id": "ACT-04", "criterion": "Agent identity is distinguishable from human identity", "check": "Confirm the system can tell that a request came from an agent acting for a person, through delegated OAuth scopes, a distinct client identity, or a declared agent header, and that this is recorded.", "why": "Attribution is the precondition for every other control: rate limiting, audit, revocation, and honest analytics all depend on knowing who acted.", "weight": 3 }, { "id": "ACT-05", "criterion": "Credentials are scoped to the task", "check": "Confirm agent-facing access can be issued with a narrower scope than a full user session, and can be revoked independently.", "why": "A long-lived full-privilege key handed to an agent makes every downstream mistake maximally expensive.", "weight": 2 }, { "id": "ACT-06", "criterion": "Rate limits and quotas are documented and expressed in responses", "check": "Confirm published limits and machine-readable limit headers, including Retry-After on 429 responses.", "why": "An agent that cannot read its remaining budget will either back off too much or hammer the service until it is blocked.", "weight": 2 } ] }, { "id": "REC", "dimension": "Recovery", "weight": 15, "question": "When something goes wrong, can the agent work out what to do next, and can a person see what happened?", "criteria": [ { "id": "REC-01", "criterion": "Errors are typed and named, not only prose", "check": "Trigger the common failure modes and confirm each returns a stable machine-readable code alongside the human message.", "why": "A stable code is what lets an agent branch. A sentence that changes wording between releases cannot be matched on reliably.", "weight": 4 }, { "id": "REC-02", "criterion": "Errors name the next viable step", "check": "Read the error payloads and confirm each says what would make the request succeed, or which alternative route exists.", "why": "Most agent loops fail not because a call errored but because the error gave no basis for a different second attempt.", "weight": 3 }, { "id": "REC-03", "criterion": "Validation failures identify the specific field and constraint", "check": "Submit a partially invalid payload and confirm the response points at the field, the rule it violated, and the accepted range or format.", "why": "A generic \"invalid request\" turns a one-shot correction into a guessing loop across every field.", "weight": 2 }, { "id": "REC-04", "criterion": "Partial progress is resumable", "check": "Interrupt a multi-step flow and confirm the state can be queried and continued, rather than requiring a restart from the beginning.", "why": "Long agent tasks are interrupted routinely. Non-resumable flows convert an interruption into repeated side effects.", "weight": 3 }, { "id": "REC-05", "criterion": "Agent actions are inspectable by the person responsible", "check": "Confirm a person can see what an agent did on their behalf, with timestamps, inputs, and outcomes, and can reverse or escalate from that view.", "why": "Delegation without an audit view moves work out of a person's sight. Recovery is a product surface, not only a log file.", "weight": 3 } ] }, { "id": "POL", "dimension": "Policy signals", "weight": 12, "question": "Has the organisation said, in machine-readable terms, what AI systems may do with this content and these capabilities?", "criteria": [ { "id": "POL-01", "criterion": "A usage preference for AI systems is stated in machine-readable form", "check": "Confirm a declaration exists in robots.txt, HTTP headers, or a well-known document, rather than only in prose terms of service.", "why": "A policy only a lawyer can read is not a policy a crawler can honour.", "weight": 3 }, { "id": "POL-02", "criterion": "Distinct uses are distinguished, not collapsed", "check": "Confirm the declaration separates indexing for search, use as input to a generated answer, and use as training data, rather than issuing one blanket allow or deny.", "why": "Most organisations want different answers for these three uses. A single directive forces one answer for all of them.", "weight": 3 }, { "id": "POL-03", "criterion": "Terms address agents acting on a user's behalf", "check": "Read the terms of service for language covering automated access performed for a logged-in user, as distinct from scraping.", "why": "Terms written against scrapers often prohibit, by accident, the assistant the customer is deliberately using.", "weight": 2 }, { "id": "POL-04", "criterion": "A contact route exists for agent and crawler operators", "check": "Confirm a published contact address or endpoint for access problems, and that it is referenced from robots.txt or the capability manifest.", "why": "Without a route, an operator whose agent is blocked has no option other than to work around the block.", "weight": 2 }, { "id": "POL-05", "criterion": "Policy signals agree across surfaces", "check": "Compare robots.txt, the machine-readable preference declaration, the capability manifest, and the terms of service for contradictions.", "why": "Contradictory signals are resolved by whoever is reading them, which means the organisation is no longer choosing its own policy.", "weight": 2 } ] } ], "relatedFrameworks": [ { "name": "AXIS (Agent Experience Index Score)", "publisher": "Netlify", "scope": "Runs a real agent against a scenario and scores the transcript across four dimensions: goal achievement, environment, service, and agent behaviour.", "url": "https://axis.run/", "note": "Behavioural: scores an observed run. This rubric is structural: it scores declared surfaces." }, { "name": "Agent Readiness Model", "publisher": "Factory", "scope": "Repository readiness for coding agents across nine technical pillars and five maturity levels.", "url": "https://docs.factory.ai/agent-readiness/overview", "note": "Scope is a code repository, not a public web surface." }, { "name": "Agentic Readiness", "publisher": "AWS", "scope": "Application evaluation across API and interface readiness, security and identity, data handling, operational resilience, and observability.", "url": "https://aws.amazon.com/blogs/migration-and-modernization/agentic-readiness/", "note": "Scope is an enterprise application estate, assessed as tool and as resource." }, { "name": "Agent readiness score", "publisher": "Cloudflare", "scope": "Public-site signals checked at the edge.", "url": "https://blog.cloudflare.com/agent-readiness/", "note": "Closest in scope to this rubric; see the guide for how the two differ." }, { "name": "Lighthouse agentic-browsing audits", "publisher": "Google Chrome", "scope": "A single page, inside an existing audit runner: WebMCP integration, an llms.txt discoverability check, accessibility for agents, and layout stability.", "url": "https://developer.chrome.com/docs/lighthouse/agentic-browsing/", "note": "Per-audit results in an experimental category; explicitly not a weighted 0-100 score." } ], "_frameworksNote": "relatedFrameworks describes the scope and shape of other published frameworks so readers can tell what each one measures. It is not a ranking, and the scores these frameworks produce are not comparable with each other or with this rubric." }