a11y-toolkit

Overview Schema Source Related Servers Discussions Admin

a11y-toolkit: OpenACR YAML report (GSA)

a11y_generate_openacr

Idempotent

Generate a machine-readable OpenACR accessibility conformance report in YAML from an evidence pack or audit reports, with WCAG 2.2 A/AA criteria and notes ready for qualified human review.

Instructions

Generates an OpenACR (the GSA open standard, VPAT-derived) accessibility conformance report in machine-readable YAML from an a11y_evidence pack (or raw audit reports): the full 55-criterion WCAG 2.2 A/AA matrix as chapters with one web component per criterion, adherence levels starting at not-evaluated (automated fails force does-not-support; review-level signals stay not-evaluated with the evidence in notes) and notes auto-filled from the pack (status, measured values, remaining human effort, sha256). Same honesty rule as a11y_generate_vpat: the machine fills notes, a qualified human sets levels via overrides (supports, partially_supports, …; hyphenated OpenACR forms accepted). OpenACR is what US federal procurement and GSA buyers parse — emit it from the same pack as the human-readable VPAT. — The machine-readable (GSA OpenACR YAML) sibling of a11y_generate_vpat — emit both from the same pack: humans read the VPAT, procurement systems parse the OpenACR. Returns {yaml, summary {level: count}, levels {code: level}, pack_sha256, format, draft} — the OpenACR YAML draft; writes a file only when output_path is given. Run after the audits you trust; validate and render in the GSA OpenACR editor (gsa.github.io/openacr-editor) — a qualified human must set the final adherence levels before publishing.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "product": "<product>"
    },
    "name": "a11y_generate_openacr"
  }
}

Input Schema

Name	Required	Description
`lang`	No	Document language (default en)
`pack`	No	a11y_evidence output (evidence pack); alternative to reports
`notes`	No	Additional notes to include
`scope`	No	a11y_scope output: human-confirmed exclusions become not-applicable with their reason (machine proposals never); overrides still win
`author`	No	{"name":…, "company":…, "email":…, "website":…} — the ACR author block
`contact`	No	Contact email (author.email fallback)
`methods`	No	Evaluation methods used (default: honest automated-screening note)
`product`	Yes	Product name as it must appear in the OpenACR
`reports`	No	Audit report objects to bundle (when pack is not given, the pack is built here first)
`overrides`	No	Criterion → adherence level set by a qualified human: {"1.1.1": "supports", "1.2.2": "not_applicable", …} (hyphenated forms accepted)
`output_path`	No	save the OpenACR YAML here (optional)
`report_date`	No	ACR report date ISO (default: today)
`product_version`	No	Product version
`product_description`	No	Product description paragraph

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv5.27.0Nov 10, 2026

addedInput schema / properties / scope

Added value: +{
+  "description": "a11y_scope output: human-confirmed exclusions become not-applicable with their reason (machine proposals never); overrides still win",
+  "type": "object"
+}

Addedv5.19.0Oct 29, 2026

TDQS

A4.2/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and the description is consistent with them: it clarifies that a file is written only when output_path is given. It adds genuinely useful behavior beyond the annotations – automated fails force does-not-support, review-level signals stay not-evaluated with evidence in notes, machine fills notes while humans set levels via overrides. The remaining gap is minor (no explicit statement about overwriting an existing output_path file or permissions), so a solid but not maximal score.

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?

Key facts (what it emits, honesty rule, return shape, file-write condition) are front-loaded and useful, but the sibling rationale is stated twice – once in the opening sentence and again in the em-dash aside about emitting both from the same pack – and the trailing editor/publishing guidance is lengthy. Trimming the duplication would sharpen it without losing information.

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

Completeness4/5

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

For a 14-parameter, nested-object tool with no output schema, the description compensates well by enumerating the return shape ({yaml, summary, levels, pack_sha256, format, draft}) and the human-in-the-loop caveat. Coverage of input-side details is largely delegated to the 100%-covered schema, which is acceptable here.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, and the description does add meaning on top: it explains the precedence chain for scope (human-confirmed exclusions become not-applicable, machine proposals never, overrides still win) and the pack-vs-reports relationship. It does not elaborate on notes, author, methods, or lang, leaving those entirely to the schema.

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?

The description opens with a specific verb and artifact: generates an OpenACR (GSA standard, VPAT-derived) YAML accessibility conformance report from an a11y_evidence pack or raw reports. It explicitly names the sibling a11y_generate_vpat and states the difference (human-readable vs machine-parsed), so an agent can disambiguate without opening either schema.

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?

It states when to use it (after the audits you trust, from the same pack used for the VPAT, when procurement systems need to parse the output), names the alternative (a11y_generate_vpat) and advises emitting both. It also names the follow-up step (validate/render in the GSA OpenACR editor) and the precondition that a qualified human sets final levels.

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