Skip to main content
Glama

a11y-toolkit: Blindfold journey verdict

a11y_journey_verdict
Read-onlyIdempotent

Scores a blindfold task journey (sign-up, checkout, password reset) acted via the accessibility tree, mapping friction points to WCAG criteria and returning a pass/partial/fail verdict.

Instructions

Blindfold journey verdict — the capability no other accessibility tool has: the agent attempted a REAL task (sign up, checkout, password reset) perceiving only the accessibility tree and acting by accessible name and keyboard; perceive via your browser accessibility snapshot (state-preserving). This turns its friction log into a deterministic scored verdict. Pass = task completable non-visually by the agent; friction items map to WCAG criteria and flow into the evidence pack (report:journey). Use with the blindfold-task prompt: act by accessible name, log friction per step, then call this. Task usability evidence, never conformance. Returns JSON: {verdict pass|partial|fail|blocked, score 0-100, findings [{criterion, severity, signal, issue, remediation, step}], summary, rules} — writes a file only when output_path is given. Run only after a real blindfold attempt (the blindfold-task prompt): the verdict prices the walk, it does not replace it.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "a11y_journey_verdict"
  }
}

Input Schema

NameRequiredDescriptionDefault
urlNopage(s) where the journey ran
langNooutput language
sealNoreturn the sealed a11y-journey/1 record instead: the walk + judgment + steps, sha-sealed (record_verify re-derives the verdict from the steps)
taskNo{"goal": what the agent attempted, "kind": sign-up|checkout|password-reset|search|onboarding|settings|data-export|custom}
stepsNojourney steps: {action, target (accessible name), perceived, friction?} — friction is {pattern: journey_* key} or {criterion, severity, issue, remediation?}
outcomeNo{"completed": bool, "gave_up": bool, "workaround_used": bool, "notes"}
output_pathNowrite the full verdict JSON here instead of returning it inline
verify_recordNoan a11y-journey/1 record to verify instead of judging: returns verified or tampered (sha + deterministic re-scoring)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv5.27.0
    • addedInput schema / properties / seal
      Added value: +{
      +  "description": "return the sealed a11y-journey/1 record instead: the walk + judgment + steps, sha-sealed (record_verify re-derives the verdict from the steps)",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / task / description
      Previous value: -"{\"goal\": what the agent attempted, \"kind\": sign-up|checkout|password-reset|search|custom}"New value: +"{\"goal\": what the agent attempted, \"kind\": sign-up|checkout|password-reset|search|onboarding|settings|data-export|custom}"
    • addedInput schema / properties / verify_record
      Added value: +{
      +  "description": "an a11y-journey/1 record to verify instead of judging: returns verified or tampered (sha + deterministic re-scoring)",
      +  "type": "object"
      +}
    • changedInput schema / required
      Previous value: -[
      -  "task",
      -  "steps",
      -  "outcome"
      -]New value: +[]
  2. Addedv5.5.0

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations: discloses that friction items map to WCAG criteria and flow into the evidence pack (report:journey), that scoring is deterministic, that a file is written only when output_path is supplied, and that verify_record re-derives the verdict from steps via sha. One mild tension remains unaddressed: readOnlyHint=true while an optional output_path write mutates the filesystem — the write is disclosed, but the description never reconciles it with the read-only annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core claim and the operating sequence, but it is dense and repetitive: the 'blindfold-task prompt' prerequisite is stated twice and the 'not conformance / not a replacement' caveat is restated in the closing sentence. The promotional opener ('the capability no other accessibility tool has') consumes space without helping invocation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an eight-parameter, nested-object tool with no output schema, the description supplies the return shape inline ({verdict, score, findings[criterion, severity, signal, issue, remediation, step], summary, rules}), the side-effect condition, the downstream evidence link, and the prerequisite. Nothing an agent needs in order to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all eight parameters including the task kinds, step friction shapes, outcome fields, and the seal/verify_record alternatives; baseline is therefore 3. The description reinforces the seal/verify relationship and the output_path write condition, but adds little parameter-level meaning the schema does not already carry.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: turns a blindfold journey (agent attempting a real task via the accessibility tree) into a deterministic scored verdict, with concrete task examples (sign up, checkout, password reset). It explicitly distinguishes itself from other accessibility tooling and from the sibling audit-style tools by naming the unique capability and framing the output as 'task usability evidence, never conformance.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit precondition ('Run only after a real blindfold attempt') and an explicit exclusion ('the verdict prices the walk, it does not replace it'), plus a step-by-step operating sequence: act by accessible name, log friction per step, then call this. It also names the companion prompt (blindfold-task) and routes the sealed/verify paths via seal and verify_record.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.