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

With readOnlyHint/idempotentHint already covering the safety profile, the description adds real context: it produces a text artifact usable as a bookmarklet or page.evaluate payload, and it is a diagnostic rather than an audit. It still doesn't say whether the injected monitor auto-expires or how its output is captured.

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

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

Front-loaded and readable, but it repeats itself: 'injectable JavaScript' and 'bookmarklet or page.evaluate' each appear twice across the description. Trimming the duplicated clause would make it tighter without losing meaning.

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

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

There is no output schema, and the description compensates by explaining that the return value is injectable JavaScript text and what the monitor logs once injected. For a single optional parameter tool this is nearly complete, though a note on where announcements surface (console/panel) is missing.

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

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

Schema description coverage is 100% (the lang enum is documented as 'monitor panel language (en default)'), so the schema carries the parameter burden. The description adds no detail about the lang option or its effect on output, so baseline 3 applies.

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

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

States a specific verb+resource: it returns injectable JavaScript that monitors aria-live dynamic-region announcements, logging time, politeness, role and text. That is a distinct capability from siblings like a11y_sr_transcript or a11y_audit_dom, and an agent can tell what artifact it produces without opening the schema.

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

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

Explicitly frames the tool as a diagnostics aid to inject in a browser and warns that it is 'not an audit by itself', which tells the agent when this is and isn't the right pick. It does not name a specific alternative sibling to use instead, so it falls short of a 5.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial behavior beyond them: the Playwright/Chromium dependency and install step, local-only processing of the auth_state session ('local file, never uploaded'), and the exact rendering methodology (background captured with text transparent). This is exactly the kind of context annotations cannot carry.

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

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

Front-loads what the tool does, then the dependency requirement, then the routing guidance, then the return shape — a sensible order. The opening sentence is a dense run-on enumerating checks, which costs some readability, but every sentence carries information.

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

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

No output schema exists, and the description compensates by spelling out the return shape ({mode, url, score 0-100, findings [{criterion, severity, signal, issue, remediation}], summary, score_note}) and noting it matches the static audit. For a six-parameter tool with a heavy runtime dependency, the definition is complete enough to invoke correctly.

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

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

Schema description coverage is 100% with six well-documented parameters, so the schema already does the heavy lifting and baseline 3 applies. The description adds no parameter-level detail (url, lang, browser, timeout, auth_state, color_scheme are all handled in the schema), so it neither compensates nor degrades.

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

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

States a specific verb and resource — a rendered WCAG audit executed via local Playwright/Chromium — and enumerates the concrete checks (contrast with alpha compositing, target size, focus indicator, rendered static checks). It is clearly distinguished from the sibling a11y_audit_url, which it explicitly positions against.

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

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

Names the alternative and the condition that selects it: 'Use instead of a11y_audit_url on JS-heavy pages.' It also states the prerequisite ('Requires playwright: pip install playwright && playwright install chromium'), so the agent knows both when to pick this tool and what it needs to run.

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

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

Annotations already declare readOnly/idempotent/non-destructive and closed-world, so the bar is met; the description goes further by stating it is a zero-dep structural first pass, operates only on local files and never fetches remotely, and enumerates which failure classes it detects versus which it cannot. That is real behavioral context beyond the structured fields.

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

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

Dense but front-loaded: the differentiator and file-locality constraint come first, then the check list, then the output shape. The parenthetical comparisons with axe/pa11y/Lighthouse and veraPDF are justifiable boundary-setting, though the sentence is long enough to approach overload.

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

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

Despite no output schema, the description names the returned JSON keys (mode, pages, tagged, lang, title, images, alt_entries, findings, summary, limits), so an agent knows what it gets back, and it clearly frames scope and limitations. Nothing needed to invoke or interpret the tool is missing.

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

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

Schema coverage is 100% and both parameters are documented in the schema; the description's only path-related guidance ('never fetched remotely — download it yourself first') duplicates the schema's own description nearly verbatim and adds nothing about the lang enum. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('PDF accessibility screening' on a LOCAL file) and enumerates the concrete checks performed (tagged tree, title, language, outline, /Alt, text layer, encryption). It explicitly separates itself from the HTML-only tools and from spec validators like veraPDF, so an agent can place it without opening the schema.

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

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

Gives clear context ('enterprise document pipelines and PDFs linked from the audited site') and a boundary condition — full PDF/UA conformance belongs to a spec validator, not this tool. It stops short of naming any sibling tool (e.g. a11y_audit_url vs a11y_audit_dom) as the alternative for HTML inputs.

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

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

Annotations already declare readOnly, openWorld, idempotent and non-destructive, so the safety profile is covered by structured data. The description still adds genuinely useful behavioral context beyond that: static analysis cannot measure class/var() CSS contrast, the report's not_measured field reflects this, and a score of 100 must not be read as "contrast is fine." That is meaningful disclosure, though it stops short of rate limits or fetch failure behavior.

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

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

The purpose, the sibling routing, and the caveat all appear before the long criterion enumeration, so the actionable content is front-loaded. The criterion list is dense but each entry pairs a signal with its WCAG success criterion, which is the detail an agent needs to match findings to a request.

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

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

With no output schema, the description carries the burden of describing the return value and does so in detail ({mode, url|file, score, findings[{criterion, severity, signal, issue, remediation}], summary, limits, score_note}), plus explains the limits field's meaning. Minor gap: timeout and lang behavior are left entirely to the schema.

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

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

Schema description coverage is 100%, so every parameter is already documented, including that html overrides url and that pages is a light same-domain crawl. The description restates "URL or an HTML string" and clarifies pages is a sampling mode, but adds no syntax or format detail beyond the schema — baseline 3 applies.

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

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

States a specific verb and resource ("Express WCAG 2.2 audit of a URL or an HTML string") plus concrete scope (20+ automated signals, weighted 0-100 score) and enumerates the checks it performs. It is immediately distinguishable from a11y_audit_dom and the multi-page siblings it names.

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

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

Explicitly routes between alternatives: "Prefer a11y_audit_dom when JS renders the content or contrast/2.5.8/focus matter; use pages for light multi-page sampling," and points to a11y_criterion for criterion definitions. It also sets expectations on when this tool is insufficient ("automation covers ~1/3 of WCAG").

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds genuinely useful behavior – the allowlist boundary, that rejections carry remediation text, and the {fixed_html, applied, not_applied} shape. However it claims it 'writes a file only when output_path is given' while no output_path parameter exists in the schema, and a file write would also sit awkwardly against readOnlyHint=true, so an agent could be misled about side effects.

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

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

The core purpose is front-loaded, but the text repeats itself: 'Returns fixed_html + applied + not_applied' is immediately followed by a second 'Returns JSON: {fixed_html, applied, not_applied}' block, and the allowlist-only constraint is stated twice with an em-dash. Roughly a third of the text is duplication rather than new information.

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

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

With no output schema, the description correctly carries the return-shape burden and explains what appears in applied vs not_applied. For a 5-parameter mutator it is nearly complete, but the phantom output_path reference and the untouched default behavior of form_errors leave a small gap an agent would have to resolve from the schema alone.

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

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

Schema description coverage is 100%, so the baseline is 3; each parameter is already documented in the schema ('only if provided and <title> is empty', 'default: (html)'). The description restates the lang/title conditions and the default-true form-error layer without adding syntax, format, or interaction detail beyond the schema.

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

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

States a specific verb+resource combination (deterministic safe auto-fixes applied to HTML) and immediately bounds it: a closed allowlist of unique-answer fixes (1.4.4 zoom, 1.3.5 autocomplete, html lang, empty title). It implicitly distinguishes itself from the audit/check siblings by declaring judgment fixes out of scope, but never names a sibling tool explicitly, so the differentiation is inferential rather than stated.

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

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

Gives a clear when-to-use condition (only issues with a provably unique fix) and an explicit when-not (alt text, contrast, accessible names are NOT touched, returning not_applied with remediation). It does not route the agent to a specific sibling for the judgment cases, which keeps it below a 5.

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

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

Adds genuine value with the disclosure that the badge deliberately avoids claiming 'conformant' and that scope is ~1/3 of WCAG. However, it says the tool 'writes a file only when output_path is given', which conflicts with readOnlyHint=true and references an output_path parameter that does not exist in the schema — a misleading behavioral claim on a read-only tool.

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

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

Front-loaded with the essential fact (returns an SVG badge), but 'honest' appears five times and the return value is restated in the trailing sentence, so several clauses do not earn their place.

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

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

With no output schema, the description does explain the badge contents (score, date, scope, color coding), which is adequate. But the unsupported output_path claim leaves an agent unsure whether a file artifact is produced, and the 0-100 score constraint is left entirely to the schema.

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

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

Schema coverage is 100%, so baseline is 3, but the description introduces a phantom 'output_path' parameter that is absent from the schema, while saying nothing useful about score, date, or lang beyond what the schema documents. This actively misleads an agent about the callable surface instead of supplementing it.

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

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

States a concrete verb+resource: returns a color-coded accessibility SVG badge containing score, date and scope, and explicitly differentiates itself from the machine-readable sibling a11y_evidence. The core purpose is unmistakable, though the repeated 'honest' framing adds rhetoric rather than additional clarity.

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

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

Gives a use context ('embed it in audited sites or statements') and names the alternative explicitly ('the machine-readable bundle is a11y_evidence'), so an agent knows which sibling to pick. It lacks an explicit when-not condition (e.g., unaudited or partial audits).

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds genuinely non-derivable context: it launches Chromium, hides the text (transparent) so only real background pixels are sampled, avoids antialiasing edges, and requires local Playwright. It stops short of mentioning runtime cost or browser-launch overhead, so it is strong but not exhaustive.

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

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

Front-loaded with the core purpose, then methodology, then sibling routing, then return shape. The em-dash parentheticals make it dense, but each segment earns its place and nothing is redundant.

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

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

There is no output schema, so the inline JSON return summary (worst/median/p95_ratio, pass flag, worst_zone, sampled_pixels, interpretation) is necessary and supplied. Combined with prerequisites, routing, and parameter coverage already in the schema, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% across all 8 parameters, so the schema already carries the semantics. The description only echoes a couple of schema facts (selector-matched element, text_color computed when not given) and adds no syntax or format detail beyond it — baseline 3.

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

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

The description names a specific verb and resource (measure the real contrast of an element against whatever renders behind it) and immediately scopes it against siblings by naming a11y_contrast_image and a11y_contrast_pair. An agent can tell exactly which contrast tool to pick without opening any schema.

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

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

Explicit routing: 'Use instead of a11y_contrast_image when the text lives in a live page' and 'for flat pairs use a11y_contrast_pair.' Alternatives and the conditions that select them are stated outright, plus the practical prerequisite of a local Playwright install.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so safety is covered; the description instead adds behavioral substance — that sampling is pixel-level over the real rendered background, that a 3×3 hostile-zone grid is computed, and the shape of the result. It stops short of noting failure/edge behavior (e.g. what happens without region, or with translucent text_color), keeping it below a 5.

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

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

Front-loaded with the distinguishing capability and the sibling routing in the first two sentences; the return-field list is justified because no output schema exists. The telegraphic arrow/em-dash style is dense but readable, with only slight redundancy around region.

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

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

For a 5-parameter, no-output-schema tool the description is essentially complete: capability, inlining of the return fields, and the sibling decision rule are all present. The remaining minor gap is that it doesn't say what happens when region is omitted despite the sampling depending on it.

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

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

Schema description coverage is 100%, so all five parameters are already documented, and the description adds only the reminder that region is "x,y,w,h" and recommended — which restates the schema's own 'strongly recommended' note. Baseline 3 is correct when the schema does the semantic work.

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

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

The description states a specific verb and resource ('TEXT OVER IMAGE contrast: pixel-level sampling of the real background behind the text box') and enumerates exactly what the tool produces (worst/median/p95 ratio, % area passing AA, worst_zone). It explicitly positions itself against a named sibling, so an agent can distinguish it from a11y_contrast_pair without opening the schema.

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

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

It names the alternative outright — 'Use instead of a11y_contrast_pair whenever the background is a photo/gradient' — which is an explicit when/when-not rule with the selector condition stated. It also advises when to pass region ('recommended'), covering the main invocation choice.

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

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

Annotations already establish this as a safe, idempotent, closed-world read, so the remaining burden is behavioral detail — and the description supplies it: accepted color syntaxes, alpha compositing rules (over bg for fg, over white for bg), automatic nearest-passing-color suggestion when AA fails, and the shape of the returned JSON object despite there being no output schema.

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

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

Front-loaded with the core purpose, then formats, then the sibling disclaimer and return shape — all sentences earn their place. Slightly dense with em-dash-separated clauses, but nothing is wasted.

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

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

With no output schema, the description compensates by documenting the returned JSON keys (text, background, ratio, verdicts, aa_suggestion). Combined with format acceptance, compositing behavior, and the sibling boundary, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100% and the description's parameter content (accepted formats, alpha compositing) largely restates what the fg/bg schema entries already say. The lang enum parameter is not mentioned in the description at all. Baseline 3 is appropriate when the schema carries the parameter semantics.

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

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

States a specific verb+resource (exact WCAG contrast ratio for a color pair) and enumerates the verdict set it produces (1.4.3 AA, 1.4.6 AAA, 1.4.11 non-text). It explicitly distinguishes itself from the sibling a11y_contrast_image, so an agent can route correctly without opening a schema.

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

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

Gives both the inclusion condition ('For flat pairs') and the exclusion with a named alternative ('text over images needs a11y_contrast_image'). This is explicit when/when-not/alternative guidance rather than implied usage.

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

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

Adds substantial context beyond the annotations: it declares a pure knowledge lookup with no fetching/auditing, discloses the exact return shape including a signal mode that adds ACT rules with w3.org links, and documents the error shape for unknown codes. That goes well past readOnlyHint/idempotentHint.

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

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

Front-loaded with the core purpose and usage trigger, but the tail is dense — the return-shape sentence and the interleaved 'includes the official Understanding WCAG 2.2 link' aside sit awkwardly after the 'does not fetch' note. Slight restructuring would earn the fifth point; no sentence is truly wasted.

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

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

No output schema exists, and the description compensates by enumerating all returned fields plus the signal-mode additions and error case. With optional params (required: 0) fully explained, an agent has everything needed to call it correctly and interpret the response.

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

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

Schema coverage is already 100%, but the description adds real meaning: it names the accepted code format ('1.4.3', '2.5.8', '4.1.2'), explains that signal ids are 'the id in every audit finding', and states the default language is English. The interaction between code and signal modes (signal resolves criterion AND ACT rules) is clarified beyond the schema.

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

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

Specific verb + resource: 'Explains a WCAG 2.2 success criterion in plain language' with the exact contents of the explanation (requirements, typical failures, verification). It also clearly distinguishes itself from the audit siblings by stating 'Knowledge lookup; does not fetch or audit anything.'

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

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

Explicit trigger: 'Use it whenever you need to explain WHY a finding matters or what the criterion actually says.' It also gives two concrete input routes (criterion codes like '1.4.3' or a finding signal like img_no_alt) and an explicit negative scope ('does not fetch or audit anything'), routing agents to the audit tools for those needs.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description goes further by disclosing input handling (inline JSON starting with '{' or file paths) and the meaning of the ok flag. It stops short of noting failure modes (malformed/incompatible snapshot versions) or large-payload limits, so it is strong but not exhaustive.

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

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

The purpose is front-loaded well, but content is duplicated: 'ok=false means a regression to review' appears in the opening sentence and again in the trailing return-shape sentence (via 'ok:false means a regression to review'). Trimming one occurrence would tighten it without losing information.

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

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

With no output schema, the description carries the return contract and does so reasonably (ok, added, removed, renamed, focus_order_changed, first_differences). It does not explain the element format inside added/removed or how renames are detected, which a caller consuming the diff might want, but the essentials for correct invocation are present.

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

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

Schema coverage is 100% and already labels a/b as BEFORE/AFTER inline JSON or path, so baseline is 3. The description adds genuinely useful detail beyond the schema: the '{'-prefix heuristic for distinguishing inline JSON from a file path, which the schema does not state.

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

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

States a specific verb and resource ('Regression diff between two accessibility snapshots') and immediately scopes it ('before/after a deploy') with the concrete artifacts diffed (added/removed/renamed interactives, focus-order changes). It explicitly differentiates from the sibling a11y_diff_urls, so an agent can choose between them without opening schemas.

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

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

Gives the operative condition for this tool versus the alternative: 'Compares two existing snapshots; a11y_diff_urls snapshots both for you.' That is an explicit when-to-use/when-to-use-the-other split, plus interpretation guidance ('ok=false means a regression to review') that tells the agent what to do with the result.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds useful non-annotation context: a hard dependency on local Playwright, that the auth_state session 'stays local', and that the return shape matches a11y_diff.

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

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

Short and front-loaded with the core action and example. The em-dash fragment ('Convenience for...; manual control is...') is slightly choppy but each piece carries information.

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

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

With no output schema, the description compensates by stating the return shape matches a11y_diff, and it discloses the Playwright prerequisite. Adequate for a 3-param tool, though it says nothing about failure behavior when a URL is unreachable.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description reinforces the 'two live URLs' and staging-vs-production framing but adds no format or constraint detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific compound verb+resource ('snapshot two URLs and diff them in a single call') and explicitly differentiates from the sibling path (a11y_snapshot + a11y_diff). An agent can tell exactly what this is without opening the schema.

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

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

Names the alternative workflow and frames this as the convenience path for staging-vs-production. It gives clear context for selection but stops short of stating explicit when-not-to-use conditions.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive). The description adds real value beyond that: it explains the purpose (catching false positives, race conditions, page-change drift) and that rejected findings carry a reason. It stops short of describing how re-verification is performed or any rate/timeout behavior beyond the schema.

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

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

Front-loaded and useful, but the closing sentence duplicates itself: 'Returns a fresh score over confirmed findings only' appears twice, and the stray em-dash separator adds clutter. The core content is tight, but the redundancy is avoidable.

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

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

With no output schema, the description compensates by stating the JSON return shape {confirmed, rejected, score}. Combined with the annotations covering the safety profile, an agent has enough to invoke this correctly, though the nested report payload is not elaborated.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, including the optional report object and its fallback-to-audit behavior. The description adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (re-runs the audit) and resource (findings), and describes exactly what it produces: each finding confirmed or rejected. This is clearly distinguishable from siblings like a11y_audit_url or a11y_diff, which do not re-verify prior findings.

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

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

Explicitly says 'Run this before acting on any audit report,' giving a clear when-to-use trigger. It does not, however, name the specific sibling that generates the report it consumes or state when not to use it.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so safety is covered. The description adds real value beyond them: it is a zero-dependency *structural* pass only, it cannot replace a human review, and it advertises a `limits` field in the response so the agent knows the output self-documents its blind spots.

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

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

Front-loaded with the purpose and the concrete checks, and the return-shape sentence at the end is useful. Minor flourish ("the other half of enterprise paperwork", "finds what makes it pointless") costs a little density but the substance is all present.

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

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

With no output schema, the description compensates by listing the returned JSON keys (mode, language, images, tables, findings, summary, limits). Combined with the enumerated checks and the explicit human-review caveat, an agent has enough to call it correctly; only per-parameter behavior of `lang` is left unstated.

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

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

Schema coverage is 100%, so `path` and the `lang` enum are already fully documented in the schema. The description reinforces the local-file constraint for `path` but says nothing about what `lang` changes in the output (finding text localization). Baseline 3 is appropriate.

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

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

States a specific resource (.docx) and enumerates exactly what the pass checks: missing alt text (docPr without descr), fake headings, document language, and tables without a header row. This makes it trivially distinguishable from the PDF/DOM/URL audit siblings, which operate on different inputs.

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

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

"LOCAL .docx" implies a file-path precondition and "Full review needs a human" signals this is a screening step, not a verdict. However, no sibling is named as the alternative (e.g., a11y_audit_pdf for PDFs, a11y_autofix for remediation), so routing is left to inference.

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

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

Beyond the annotations, it discloses the exact output contract (a11y-evidence-pack/2), that a file is written only when output_path is given, digest/timestamp stamping, an empty human-signature block, and the matrix's tri-state semantics (automated-fail / automated-review / not-flagged, explicitly NOT pass/not-run/manual-only). It also states the substantive rule that agent-verified codes never erase an automated-fail, which no annotation conveys. The one tension is that readOnlyHint=true while the tool can write a file, but the description surfaces that write condition explicitly rather than hiding it.

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

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

Purpose is front-loaded in the first sentence, but the middle is a single ~90-word run-on of em-dash-separated fragments (effort classes, hashes, signature block, tamper rule) that is hard to parse quickly. Information density is high and little is pure filler, yet the compressed telegraphic style ('Evidence, never conformance.', caps-locked MIN/MED/MAX) costs readability.

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

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

With no output schema, the description carries the burden of describing the return value and does so thoroughly: JSON shape, schema version, matrix states, effort pricing, signature block, tamper rule. The only real gap is the optional 'snapshot' input, whose role relative to 'reports' is never explained in the description.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces 'reports' by urging the agent to pass every report and clarifies that 'verified' codes are promoted to agent-verified while automated-fail stands, but it says nothing about 'snapshot' and only alludes to 'reviewer' via the signature-block mention.

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

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

The first sentence gives a concrete verb and resource: 'Builds the verifiable evidence pack: the machine→human handoff object for WCAG conformance work', and the payload contents are enumerated (55-criterion matrix, effort classes, SHA-256 hashes, signature block). It is unmistakably distinct from audit siblings like a11y_audit_url or a11y_reflow, though it never names a sibling or an alternative tool explicitly.

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

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

'Run after the audits you trust' and 'feed it every audit report you have' establish clear sequencing and input breadth, and 'pass verified codes from the manual checklist' tells the agent what else to supply. The when-to-use context is solid, but no explicit exclusions or named alternatives (e.g. vs. a11y_generate_vpat or a11y_generate_declaration) are given for an agent choosing between report-producing tools.

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

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

Annotations already cover the safety profile (readOnly/idempotent/non-destructive/openWorld), and the description adds substantial context beyond them: the exact two-phase procedure, the finding that hardcoded SVG fills fall back to inherited and icons can vanish, the heuristic-vs-definitive caveat, and the revision-1 scope limit. It also notes auth_state stays local, useful for a login-gated test.

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

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

Front-loaded with the core question the tool answers, then the mechanism, then the caveat, then the return shape. Every sentence earns its place; the revision-1 scoping note prevents a false expectation of image coverage and the inline JSON return list compensates for the absent output schema.

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

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

With no output schema, the description supplies the return shape ({mode, normal, forced, score, findings, limits}). Combined with the disclosed scope limits, the heuristic-vs-definitive framing, and annotations covering safety, an agent has everything needed to decide to call it and interpret the result.

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

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

Schema description coverage is 100%, so the schema already documents url, lang, browser, timeout, and auth_state. The description only loosely gestures at url ('loads the page') and auth ('behind login') without adding syntax, defaults, or format detail beyond what the schema provides — the baseline 3 for schema-driven parameters applies.

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

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

States a specific verb+resource: tests whether content survives forced-colors: active (Windows High Contrast), and details the mechanism (load normally, flag hardcoded SVG fills, emulate forced-colors, compare). This is a uniquely identifiable function among the siblings — no other tool covers forced-colors, so differentiation is inherent and the scope is precise.

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

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

Clearly frames the tool's place: 'Review-grade heuristic — the definitive check is visual on Windows HCM; this prepares it,' which tells the agent when the result is sufficient and when it is not. It also states current coverage limits (SVG fills only, images deferred). It stops short of naming sibling tools for adjacent checks (e.g. contrast tools), so it is strong but not exhaustive on alternatives.

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

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

Goes well beyond the annotations by disclosing that invalid data is REALLY submitted (matching destructiveHint/openWorldHint), that local Playwright is required, what gets checked in the DOM (aria-invalid, aria-describedby, role=alert), and what is not measurable. The safety-critical warning about production forms is exactly the kind of context annotations alone cannot convey.

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

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

Purpose is front-loaded in the first clause, followed by mechanism, requirements, return shape and the safety caveat. It is information-dense but somewhat long and parenthetical, trading some readability for thoroughness.

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

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

For a complex, destructive, output-bearing tool with no output schema, the description covers the mechanism, the return JSON shape, the prerequisites (local Playwright), the edge cases and the safety constraint. Nothing an agent needs to invoke it safely and correctly is missing.

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

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

Schema description coverage is 100%, so each parameter (url, lang, timeout, auth_state) is already documented in the schema. The description adds behavioral context rather than parameter-level detail — it implies forms behind login (auth_state) are supported but doesn't enrich the parameter syntax beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource: it fills validatable fields with invalid data, really submits, and judges the post-submit DOM for WCAG 3.3.1/3.3.3 error identification and suggestion. This is clearly distinguishable from sibling audit tools like a11y_audit_url or a11y_audit_dom because it is the only one that actively submits a form and reads the resulting DOM.

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

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

Gives explicit when-to-use (test/staging forms or forms you own) and when-not-to-use (do not run against production forms that trigger real emails, orders or leads). It also defines edge-case handling: native browser validation counts unless the form has novalidate, and forms that navigate on submit are honestly marked as not measurable in-page.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, which could alarm an agent given this is a document generator; the description resolves that by stating a file is written only when output_path is given, and that it returns {html, summary}. It also notes the generated document is itself accessible, a non-obvious quality guarantee. It doesn't say whether an existing file at output_path is overwritten.

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

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

Front-loaded with the verb and the framework fork in the first clause, and the emitter-style tagline at the end is useful rather than filler. It is dense with parenthetical legal citations, which costs a little readability but each clause carries information.

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

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

For a 13-parameter generator with no output schema, the description supplies the return shape ({html, summary}), the conditional side effect, and the legal/input sourcing guidance. What's missing is minor: overwrite semantics for output_path and how status/partial maps into the generated text.

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

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

Schema coverage is 100%, so all 13 parameters are already documented, and the description mostly restates them (framework values, output_path behavior, lang). It adds light legal context — EN wording falls under Directive (EU) 2016/2102 / EAA — but gives no guidance on the required triple (entity/url/status) or how status interacts with inaccessible_content. Baseline 3 applies.

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

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

States a specific verb and artifact — generates an Accessibility Statement in HTML — and pins down the two legal frameworks (rd1112 vs eaa) with the exact directives behind each. The trailing tagline 'Legal statement generator' separates it from the sibling audit tools and from a11y_generate_vpat without the agent needing to open a schema.

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

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

Gives concrete workflow guidance: populate inaccessible_content from audit findings and a11y_evidence, and pick framework=rd1112 for Spanish public sector vs eaa for private sector. It stops short of naming an explicit alternative for when a different statement format (e.g. VPAT) is wanted, so no exclusion rule is stated.

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

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

Annotations only declare readOnly=false, destructive=true, idempotent=true, openWorld=false; the description adds substantial context beyond them: levels start at 'Not Evaluated', automated fails force 'Does Not Support', the document is a DRAFT until the signature block (referencing pack sha256) is completed, and a file is written only when output_path is given. This is exactly the behavioral disclosure a mutation tool needs.

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

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

Front-loaded and information-dense, but redundant: the a11y_generate_declaration counterpart relationship is stated twice, and 'the machine fills Remarks, the human signs the claim' plus the 'levels stay Not Evaluated until a qualified human sets them' point are repeated across the main text and the trailing recap.

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

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

For a 12-parameter, nested-object tool with no output schema, the description supplies the return shape ({html, summary, levels, pack_sha256, draft}), the draft/signature workflow, the override semantics, and the file-write condition. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real semantics: it explains the pack-versus-reports relationship, that the pack is built from reports when absent, the accepted override level vocabulary, and the conditional file-writing behavior of output_path. It adds value over the schema without fully re-documenting every field.

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

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

States a specific verb and resource ('Generates a VPAT 2.5 (WCAG edition) accessibility conformance report in accessible HTML from an a11y_evidence pack'), including the exact artifact (55-criterion WCAG 2.2 A/AA table). It explicitly distinguishes itself from the sibling a11y_generate_declaration by positioning VPAT as the US/ADA counterpart versus the EU/EAA declaration.

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

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

Gives clear when-to-use context ('Run after the audits you trust'), names the required input source (the a11y_evidence pack, or raw reports), and routes the agent between this tool and a11y_generate_declaration by region/standard. The preconditions (qualified human must set levels and sign) are spelled out.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), so credit goes to added context: the description discloses the actual interaction performed (hovers elements, presses Escape), the local-Playwright dependency, and that non-dismissing tooltips are flagged. It doesn't discuss limits on candidate count or timing/pagination of the hover probing, but the operational disclosure is solid.

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

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

Dense but front-loaded: purpose first, then the scope/alternative routing, then the return shape. Every clause carries information; the 'Returns JSON' sentence is justified because there is no output schema, though it is the least essential element.

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

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

With no output schema, the description compensates by naming the return keys (candidates, dismissed_on_escape, findings), and it covers the environment requirement and the auth path via the schema. For a focused single-criterion checker with annotated safety, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so every parameter (url, lang, timeout, auth_state) is already documented in the schema, including the enum and defaults. The description adds no parameter-level syntax or format detail beyond that, so the baseline 3 is appropriate.

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

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

States a specific criterion (1.4.13 Content on Hover or Focus) and a concrete verb sequence: finds tooltip/overlay candidates, hovers each, tests whether Escape dismisses. It explicitly distinguishes itself from siblings by naming a11y_audit_dom and a11y_keyboard, so an agent can tell them apart without opening schemas.

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

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

Gives explicit scope ('tooltips only'), names the alternative for full audits (a11y_audit_dom) and for keyboard traps (a11y_keyboard), and states the prerequisite (local Playwright). Nothing about when to pick this vs. a sibling is left to inference.

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

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

Annotations cover the safety profile (readOnly, idempotent, openWorld), and the description adds genuinely non-derivable behavior: html mode POSTs the document to the third-party W3C service, url mode shares only the URL, and base_url enables a self-hosted vnu. It also states the return shape, disclosing network/privacy implications the annotations cannot express.

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

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

Front-loaded with the core purpose, then privacy, then return shape — a logical order with little waste. Minor redundancy: 'mapped to WCAG criteria where they overlap' appears twice (opening and closing sentence).

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

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

With no output schema, the description correctly carries the return-value burden ('Returns JSON: Nu validator messages mapped to WCAG criteria'), covers all four parameters' semantics, and discloses the third-party network behavior. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema by tying url/html to their privacy consequences (URL-only vs full document POST) and explaining base_url's self-hosted purpose. It does not add format or syntax detail for lang beyond the enum.

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

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

States a specific verb+resource (checks a URL or raw HTML) against a named authoritative engine (Nu Html Checker) and enumerates the scope: doctype, encoding, structural validity, plus alt/lang/role issues. An agent can tell this apart from generic audits like a11y_audit_url because it names the specific checker and its WCAG mapping.

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

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

Gives clear selection context among its own modes (url for URL-only sharing, html POSTs content, base_url for sensitive content via self-hosted vnu) and contrasts privacy behavior with a11y_audit_url. However, it never explicitly states when to prefer this tool over sibling audits like a11y_audit_dom or a11y_audit_url for a given validation goal.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered; the description adds genuinely new behavior: deterministic scoring, the pass criterion definition, friction-to-WCAG mapping, the evidence-pack handoff, and the conditional file write. The one nuance it states ("writes a file only when output_path is given") sits in mild tension with readOnlyHint=true, though a new opt-in artifact is not destructive and is not a real contradiction. It does not discuss rate limits or failure modes when the journey input is malformed, which keeps it short of a 5.

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

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

Front-loaded with the core action and the return shape, and most sentences carry distinct information. It loses a point for promotional framing ("the capability no other accessibility tool has") and for restating the blindfold-task prerequisite twice with slightly different phrasing.

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

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

There is no output schema, so the description supplies the return contract inline (verdict enum, 0-100 score, findings field list, summary, rules) plus the file-write side effect. Combined with the stated preconditions and the WCAG-mapping behavior, an agent has everything needed to invoke it correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining the relationship between parameters — steps carry per-step friction either as a journey_* pattern key or as {criterion, severity, issue, remediation}, and those map into the returned findings. It also clarifies output_path's effect (full verdict written to file instead of returned inline). It doesn't add format detail for url/lang/task beyond what the schema already states.

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

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

States a specific verb and artifact: it converts a blindfold journey's friction log into a deterministic scored verdict with pass/partial/fail/blocked. It also explicitly differentiates itself from the rest of the toolkit ("the capability no other accessibility tool has") and from conformance-oriented siblings ("Task usability evidence, never conformance"). An agent can distinguish it from a11y_audit_url or a11y_keyboard without opening a schema.

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

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

Explicit preconditions and sequencing: "Run only after a real blindfold attempt (the blindfold-task prompt)" and "act by accessible name, log friction per step, then call this." It names the companion prompt as the alternative workflow and draws the boundary against conformance tooling, so both when-to-use and when-not are covered.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantive runtime context: requires local Playwright, a 60 tab-stop ceiling, and the exact trap-vs-modal decision rule. It also previews the return payload keys, which is more than the annotations give.

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

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

Front-loaded with the criterion number and capability, then the decision rule, then scope. Dense and mostly earning its space, though phrases like 'the decisive test' add dramatic flourish that could be trimmed without losing meaning.

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

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

For a 5-param open-world tool with no output schema, the description supplies the prerequisite (local Playwright), the scope boundary against a sibling, the severity model, and the return shape. An agent has everything needed to decide whether to call it and how to interpret the result.

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

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

Schema coverage is 100%, so every parameter including url, lang, browser, max_steps and auth_state is already documented. The description mentions Chromium and the 60-stop bound, but that largely restates the schema's own 'max real Tab presses (60 default)' and browser engine entries. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource (keyboard-trap detection / 2.1.2) plus the mechanism (real Tab walking in Chromium) and the decisive discriminator (Escape releases the cycle). It also names the bound: focus visibility belongs to a11y_audit_dom, so an agent can separate it from that sibling 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.

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

Gives explicit when-to-use (pages with modals, dialogs or embedded apps) and an explicit when-not (a plain content page has nothing to trap), plus the sibling routing for the adjacent concern. It also states the not-a-bug case — a cycle that Escape releases is correct and NOT reported — which prevents false-positive chasing.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and non-idempotency, so the mutation profile is covered. The description adds genuinely non-obvious behavior: the ledger accumulates across runs, prior findings show as resolved on re-audit, and each project should get its own ledger_path. It does not clarify whether record overwrites existing entries for the same URL, which is the one gap given destructiveHint=true.

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

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

Dense and front-loaded: the identity sentence comes first, actions next, return shapes and timing last. Nearly every clause carries information, though the parenthetical attribution to Cloudflare's skill is marginally expendable.

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

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

There is no output schema, yet the description supplies the return shape for each action (stored entry, never-checked criteria, and the {entries, active_signals, resolved, mean_score} object). Combined with the persistence model and required-parameter guidance, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value beyond the schema by scoping url to record/gaps and by advising 'give each project its own ledger_path,' which explains the default file's cross-project collision risk rather than just restating the default value.

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

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

The description names a specific resource (persistent coverage ledger) and enumerates its three actions (record, gaps, summary) with what each does. No sibling tool in the list provides persistent audit history, so the function is unambiguous without opening the schema.

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

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

It gives explicit sequencing guidance: 'record after every audit run; gaps before planning the next pass,' which tells the agent when to invoke each action. It stops short of naming alternative sibling tools to use instead when persistence is not needed, so it is clear context rather than full when/when-not routing.

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

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

With readOnlyHint/idempotentHint already declaring the safe-read profile, the description adds real behavioral detail: the two-pass reload methodology, the specific animation threshold (>0.15s infinite), the video[autoplay] coverage, and the honest limits. That is exactly the context annotations cannot carry.

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

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

Front-loads the core question, then method, then scope limits, then return shape — a good information hierarchy. Mild deduction: 'Nobody else automates this' is marketing filler that does not help an agent invoke the tool.

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

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

No output schema exists, yet the description enumerates the return keys ({mode, normal, reduced, respects, score, findings, limits}), covers the manual-review boundaries, and already reflects the safety annotations. An agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100%, so url, lang, browser, timeout, and auth_state are already documented in the schema, including that auth_state stays local. The description adds no syntax or format detail beyond that, so baseline 3 applies.

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

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

States a specific, testable verb+resource: it checks whether a site HONORS prefers-reduced-motion, and spells out the exact method (load, count looping animations, reload with reduce, recount). This is unmistakably distinct from siblings like a11y_forced_colors or a11y_reflow.

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

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

Gives clear context — WCAG 2.2.2 / 2.3.3 AAA — and explicitly notes the alternative gap ('axe leaves it as manual review'), plus what remains manual (JS/WebGL/scroll-parallax). It stops short of explicit when-not-to-use framing, but a caller can infer scope well.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: the two-pass measurement method (1280px then 320px), the rationale that zoom re-layout is equivalent to a 320px viewport, the local Playwright dependency, and the exact JSON return shape. Nothing about the tool's runtime behavior is left to inference.

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

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

Front-loaded with the check name and criterion, then method, scope, and return shape in a tight sequence. It is on the long side and dense with em-dash asides, but each sentence carries distinct operational value (dependency, method rationale, exclusion, cardinality rule).

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

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

With no output schema, the description compensates by enumerating the return object ({url, viewport, horizontal_scroll, offenders[{selector, width}]}). Combined with the method note, scope boundary, and environment requirement, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so every parameter (url, lang, browser, timeout, auth_state) is already documented structurally; the description only reinforces the 320px viewport semantics of url. It adds no syntax, format, or interaction detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Reflow check at 320px') tied to a named WCAG criterion (1.4.10, AA), and explicitly claims the niche axe/Lighthouse leave uncovered. It routes away from a sibling by name ('for the full rendered pass use a11y_audit_dom'), so an agent can distinguish it without opening any schema.

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

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

Gives explicit when-to-use (320px reflow / 1.4.10), an explicit alternative with its selecting condition (a11y_audit_dom for the full rendered pass), and a cardinality rule ('run once per template, not per page'). The prerequisite ('requires local Playwright') is also stated up front.

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

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

Annotations already declare read-only/idempotent/non-destructive, but the description adds substantive behavior the agent cannot infer: real scrolling batches in a live browser, a live-region observer, a per-batch focus-survival test, and an explicit degradation guard that skips unfounded signals. It also discloses the return payload shape inline.

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

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

Front-loaded and dense with useful specifics, and the alternative-tool routing comes before the return-shape note. Some flourish ("the documented disaster nobody automates") and embedded criteria lists cost a little density, but nothing is redundant with structured fields.

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

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

With no output schema, the description responsibly describes the returned JSON (mode, url, score, findings, summary) and the finding fields. Minor gap: the score scale and severity taxonomy are not defined, leaving an agent unsure how to read a low score.

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

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

Schema coverage is 100%, so all four parameters are already documented; the baseline would be 3. The description still adds meaning by framing max_batches as real scroll batches in a browser (implying runtime cost) and by advising to audit feeds you own or can authenticate into, which motivates the auth_state parameter.

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

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

States a specific verb+resource — an infinite-scroll accessibility audit with real Chromium scrolling — and enumerates the three concrete checks (focus survival, live-region announcement, feed termination). It explicitly demarcates itself from a11y_audit_url/a11y_audit_dom, so an agent can route correctly without opening the schema.

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

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

Gives an explicit usage boundary ("For paginated feeds only; general page audit is a11y_audit_url/dom") and a prerequisite ("Requires local Playwright"). It also states a when-not condition via the honest guard for login walls / non-standard markup, so the agent knows when results will be degraded.

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

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld. The description adds real behavioral context beyond them: it requires local Playwright, the accessibility tree only appears with Playwright ≥1.49, and it documents the return shape. Not full marks because the Playwright dependency is stated without failure semantics.

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

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

The core purpose is front-loaded, but the single sentence sprawls with nested parentheticals, an em-dash clause, and a trailing fragment about the watch loop and JSON shape. It is information-dense rather than wasteful, yet the run-on structure hurts scannability.

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

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

No output schema exists, but the description compensates by sketching the return JSON ({url, ts, elements, focus_order}) and the Playwright version condition. Combined with annotations covering the safety profile, an agent has enough to invoke it correctly, though auth/login flow details remain thin.

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

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

Schema description coverage is 100% and both parameters (url, auth_state) are documented in the schema itself, so the baseline is 3. The description mentions login context only obliquely via the 'watch loop' framing and never explains auth_state's format, adding little beyond the structured field.

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

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

States a precise verb+resource (accessibility snapshot of a URL) and enumerates exactly what it captures: interactive elements in DOM order, real tab focus order, and the computed accessibility tree. It names sibling tools (a11y_diff, a11y_diff_urls) so an agent can distinguish this capture tool from the comparison tools without opening schemas.

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

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

Gives clear usage context ('Save it before a deploy and compare after with a11y_diff') and explicitly routes to a11y_diff_urls for two live URLs. It stops short of stating when NOT to use it (e.g., when you only have a DOM string, where a11y_audit_dom/a11y_keyboard might apply), so it is strong but not exhaustive.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real context beyond that: the linearized walk behavior, the Playwright dependency, and the exact return shape. It does not cover auth/permission needs beyond the schema's own auth_state note.

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

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

Front-loaded with the core concept and well organized with em-dash-separated clauses. Slightly repetitive ('the linearized reading experience' and 'as prose an agent can READ... from a blind user's perspective' say overlapping things), but no wasted structure.

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

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

For a read-only tool with no output schema, the description supplies the return contract ({url, total, announcements [{time, politeness, role, text}]}), the dependency, and the sibling routing — everything an agent needs to invoke and interpret it.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters (url, lang, browser, timeout, auth_state). The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('Screen reader TRANSCRIPT: what a blind user HEARS on this page') and explains the mechanism — walking the accessibility tree linearly. It explicitly distinguishes itself from siblings by naming a11y_snapshot and a11y_keyboard.

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

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

Explicit routing: 'for structure use a11y_snapshot, for keyboard traps use a11y_keyboard.' It also flags the required dependency ('Requires Playwright'), giving the agent the conditions under which the tool applies.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral detail: the matching is by RGB distance, results are constrained to opaque colors, and the returned action indicates whether the color lightens or darkens. It does not mention edge cases (e.g. when no passing color exists) or tie-breaking.

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

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

The front-loaded first sentence is excellent, but the return-value information is stated twice — once as prose ('Returns the color, its ratio and whether it lightens or darkens') and again as 'Returns JSON: {color, ratio, action}' — and the trailing clause 'the nearest opaque color reaching the target' repeats the opening. Roughly a third of the text is redundant.

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

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

With no output schema, the description correctly steps in to document the return payload {color, ratio, action}, and all three parameters are documented in the schema. The only real gap is the undefined failure case when no opaque color reaches the target ratio, which matters for an agent deciding how to handle the result.

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

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

Schema coverage is 100% and each parameter already carries a description, including the target's ratio semantics and default. The description reinforces 'opaque' and the 4.5 default but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific operation (find the nearest opaque color to fg that reaches a target contrast ratio against bg) and even names the algorithm (RGB distance). It explicitly positions itself as 'the fixer companion to a11y_contrast_pair failures,' which separates it from the diagnostic sibling a11y_contrast_pair 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.

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

Usage context is clear: this is the remediation step after a contrast-pair check fails, with a sensible default target of 4.5. However, it never states when NOT to use it — notably it does not distinguish itself from the sibling a11y_autofix, which an agent could reasonably confuse for the same fixer role.

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

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

Annotations already declare the read-only, idempotent, open-world, non-destructive profile, so the bar is lower. The description adds real behavioral context: it fetches and parses an external file, applies a concrete reading-speed standard (>21 chars/second, BBC/Netflix), and discloses a 'limits' field and the human-review boundary. It stops short of stating failure modes (e.g., unreachable URL, non-VTT content).

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

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

The core purpose is front-loaded in the first clause, with detail following. It is dense and longer than typical, but nearly every sentence carries signal; the return-shape sentence is justified because there is no output schema. Slightly heavy parentheticals cost it the top mark.

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

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

With no output schema, the description compensates by sketching the JSON return ({mode, cues, characters, captioned_seconds, findings, summary, limits}), states the analysis thresholds, the coverage condition, and the human-review limitation. An agent has everything needed to call it correctly and interpret results.

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

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

Schema coverage is 100%, so url, lang, and duration are already documented in the schema, including that duration enables the coverage check. The description's mention of the 21 chars/second threshold adds marginal color around the duration parameter but otherwise restates schema-provided meaning, so baseline 3 applies.

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

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

States a precise verb+resource: it downloads and parses the actual .vtt and judges caption quality (WCAG 1.2.2), enumerating what it inspects (timing lines, empty cues, overlaps, reading speed, coverage). It explicitly carves out its scope against the naive '<track> exists' check, so an agent can tell it apart from a presence-checking sibling without opening a schema.

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

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

Clear context: pass the .vtt URL, and passing duration enables the coverage/completeness check, plus an explicit when-not ('not a substitute for human review of accuracy or speaker identification'). It never names a specific sibling tool as the alternative, so the routing is implied rather than explicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses the pinned draft date, that the mapping is curated not W3C-official, that no score/tier/conformance is produced because thresholds are TBD, and that output is JSON with a fixed key set. That is exactly the behavioral context an agent needs before quoting results to a team.

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

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

Front-loaded with purpose, then the disclaimer, then the return shape and cadence — good ordering. The no-score point is made three times ('Informative only', 'NO score, tier or conformance claim', 'never a score'), which is defensible emphasis for a headline risk but is mild redundancy.

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

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

There is no output schema, and the description compensates by enumerating the full return object including outcomes, counts, unmapped and the disclaimer fields. Combined with the draft pinning and non-conformance caveats, nothing an agent needs to call or interpret this tool is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description correctly scopes the input as an audit report whose findings are WCAG 2.2. It adds the source tools the report can come from, but says nothing about the lang parameter or edge cases like what happens to unmapped criteria beyond the 'unmapped' key.

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

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

States a specific verb and resource: it takes an audit report and re-groups WCAG 2.2 findings under WCAG 3 Working Draft outcomes. The framing ('the view layer nobody ships') and the explicit negation of scoring clearly separate it from the audit siblings like a11y_audit_url and a11y_ledger.

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

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

Gives an explicit trigger ('Run after any audit when the team asks "what about WCAG 3?"'), an explicit counter-instruction ('keep auditing against WCAG 2.2'), and a maintenance cadence ('re-baseline on each W3C draft publication, roughly March/September'). An agent knows both when to reach for it and when not to.

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