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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds behavioral detail: it logs announcements with time, politeness, role, and text, and is visible on screen, which goes beyond the structured metadata.

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?

Two sentences, front-loaded with the purpose, no redundant words.

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 simple tool with one optional parameter and no output schema, the description explains the return value (injectable JavaScript), its purpose, and its non-audit nature. It could mention the exact return type but is sufficient.

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 covers the only parameter (lang) with a description and default, so the description adds nothing about parameters. 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 (Returns) and resource (injectable JavaScript for an aria-live announcement monitor), and explicitly distinguishes itself from an audit. Clear and unambiguous.

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?

Provides usage context by calling itself a diagnostics aid and clarifying it is not an audit, but does not name alternative tools or specify when to prefer it over siblings.

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 behavior. The description adds meaningful behavioral context beyond that: it performs real rendered checks, computes against effective backgrounds with alpha compositing, includes remediation in findings, and depends on a local Playwright install. This is valuable context that the annotations do not provide.

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 description is dense and front-loaded with the core purpose. The long list of checks and the installation command are useful, but the second sentence packs many details into a single unwieldy clause. Still, there is no filler or repetition.

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?

The description covers purpose, scope, alternatives, prerequisites, and result hints ('Findings include remediation'). However, there is no output schema and the description does not state the overall return format, so an agent is left inferring how findings are structured. For a complex audit tool, a bit more return-value context would make it complete.

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 url, lang, timeout, and auth_state. The description does not add material parameter-level meaning beyond reinforcing that the audit is rendered/browser-based. 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?

The description states a specific verb and resource: a deep rendered WCAG audit of a page via local Playwright/Chromium. It enumerates concrete checks (contrast, target size, focus indicator) and clearly separates this tool from a11y_audit_url by naming that sibling directly. An agent can determine what this tool does without inspecting its 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?

The description explicitly routes usage: 'Use instead of a11y_audit_url on JS-heavy pages.' It also states the prerequisite that local Playwright/Chromium must be installed, with an installation command. This gives clear when-to-use and alternative guidance.

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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond that: it explicitly states the audit is automated, covers ~1/3 of WCAG, is a filter rather than a verdict, and that findings include concrete remediation. This goes beyond the annotations without contradicting them.

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 description is long but well-structured: it front-loads the core purpose, then lists specific checks, then adds caveats and routing guidance. Each sentence contributes meaning, though the list of checks could be trimmed without loss. It is more detailed than average but not bloated.

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 lacking an output schema, the description tells the agent that the tool returns a weighted 0-100 score and that each finding includes remediation. It also explains limitations (covers ~1/3 of WCAG) and when to use sibling tools. For a complex audit tool with 5 parameters, this is sufficient context 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% — every parameter (url, html, lang, pages, timeout) already has a description. The tool description mentions 'URL or an HTML string' and 'pages' for light multi-page sampling, but these add little beyond the schema. Per the rubric, baseline 3 is appropriate 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?

The description states a specific verb ('Express WCAG 2.2 audit') and resource ('a URL or an HTML string'), enumerates the exact checks covered, and distinguishes itself from siblings by naming a11y_audit_dom and the pages parameter. An agent can immediately tell what this tool does and how it differs from related tools.

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 states when to prefer alternatives: 'Prefer a11y_audit_dom when JS renders the content or contrast/2.5.8/focus matter; use pages for light multi-page sampling.' It also notes it is a filter, not a verdict, and recommends querying a11y_criterion for criterion meaning. Clear when-to-use and when-not-to-use guidance.

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 convey read-only, idempotent, open-world-false, and non-destructive behavior. The description adds genuinely useful context beyond those annotations: deterministic behavior, the exact return shape (fixed_html + aplicados + no_aplicados), and the no-op fallback behavior with remediation for judgment-based issues. It is consistent with the annotations.

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 content is front-loaded and information-dense, but it is somewhat repetitive: 'judgment fixes come back as no_aplicados with remediation' appears twice, and the 'closed allowlist of provably safe fixes' concept is restated. The description earns its place but would benefit from tighter editing.

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 having no output schema, the description explains the return fields and the fallback behavior for unsupported fixes. It gives concrete examples of what the closed allowlist includes, though it does not enumerate every possible fix. That is a minor gap, not a blocking one, since the tool communicates unsupported cases through no_aplicados.

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 parameters are already documented. The description adds a bit of context by mentioning lang and title as optional fill-ins, but it does not substantially extend the schema descriptions. This is the expected baseline-3 case.

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 the exact verb and resource: it applies deterministic, provably safe auto-fixes to raw HTML. It also distinguishes itself from judgment-based accessibility work by explicitly excluding alt text, contrast, and accessible names, which separates it from the audit and analysis sibling tools.

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 clearly defines when to use the tool: only for the closed allowlist of fixes where the correct answer is unique. It also explains that judgment-requiring issues are returned as no_aplicados with remediation, signaling that the tool should not be relied on for those cases. It does not name specific alternative tools, but the boundary is explicit enough.

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, and destructiveHint, covering the safety profile. The description adds important behavioral context: the badge is deliberately non-conformant, is based on automated screening covering roughly one-third of WCAG, and is color-coded by score.

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 description is front-loaded with the core purpose and kept short. The word 'honest' is repeated a few times and the scope note could be tightened, but every sentence contributes useful 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?

Despite having no output schema, the description explains the return value's format, content, and purpose, while annotations cover side-effect safety. An agent can confidently call this tool for badge generation without missing critical information.

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 score, fecha, and lang with descriptions and an enum. The description only confirms that score and date appear in the badge, adding little 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?

The description clearly defines the tool as returning an accessibility badge as accessible SVG with score, date, scope, and color-coding, and explicitly states that it does NOT claim WCAG conformance. It also distinguishes itself from a11y_evidence by scope, so an agent can tell it apart from siblings.

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 embed contexts ('audited sites or statements') and a scope note that directs machine-readable-bundle needs to a11y_evidence. This provides a clear when-to-use and when-not-to-use distinction among siblings.

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, and non-destructiveHint. The description goes beyond this by detailing the computational behavior—sampling real background pixels, producing specific ratio metrics, and performing 3x3 grid hostile-zone detection. It does not contradict annotations and adds meaningful context about what the tool actually computes.

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 description is two sentences, front-loaded with the core purpose, and wastes no words. It uses compact arrow notation to list outputs and ends with a clear usage directive. Every sentence contributes to understanding or selecting 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?

For a tool with no output schema, the description sufficiently outlines the expected outputs (worst/median/p95 ratio, % area passing AA, hostile-zone detection). It also covers usage context and the key parameter recommendation. Minor gaps like exact output key names or error handling are not critical given the provided detail.

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 parameters (lang, path, region, sample, text_color) have individual descriptions. The tool description redundantly recommends region='x,y,w,h', which mirrors the schema's 'strongly recommended' note. No additional parameter meaning is provided beyond the schema, so a baseline score of 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?

The description clearly states the tool performs pixel-level contrast sampling of the real background behind text, computing worst/median/p95 ratios, % area passing AA, and hostile-zone detection. It explicitly contrasts with 'pair-only checkers' and names the sibling a11y_contrast_pair, making its unique purpose unmistakable.

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 an explicit directive: 'Use instead of a11y_contrast_pair whenever the background is a photo/gradient.' It also recommends setting region as 'x,y,w,h' for accurate sampling, providing actionable guidance on when and how to invoke the tool.

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 readOnly/idempotent annotations, the description reveals key behavior: alpha is composited over the background (or white for bg), per-criterion verdicts are returned, and a nearest passing color is suggested when AA fails. This materially helps an agent predict side effects and output shape.

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?

Two tight sentences front-load the core function and verdicts, then add format support, compositing behavior, fallback suggestion, and the key sibling exclusion. Every clause earns its place with no fluff.

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 simple read-only calculation tool, the description covers what it computes, what inputs it accepts, how alpha is handled, what outputs to expect, and when not to use it. No critical gap remains for an agent 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 schema already documents formats and compositing for both fg and bg. The description reinforces those semantics but does not add significant meaning beyond the structured 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?

The description states an exact, specific function: computing WCAG contrast ratio for a color pair with per-criterion verdicts (1.4.3, 1.4.6, 1.4.11). It clearly differentiates from a11y_contrast_image by explicitly noting flat pairs vs. text over images.

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 direct usage context: use for flat color pairs, and explicitly says text-over-images needs a11y_contrast_image. This names the alternative and the condition that selects it, leaving no ambiguity about when this tool is appropriate.

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 mark the tool read-only and idempotent; the description adds that it is a knowledge lookup and does not fetch or audit anything, which is useful beyond the safety hints. It also discloses what the returned explanation covers (requirements, failures, verification), compensating for the absent 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?

The description is compact and front-loaded: the first sentence states purpose and content, the second gives concrete use and a behavioral boundary. Every sentence earns its place without wasted words.

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 simple knowledge-lookup tool, the description covers purpose, output content, language options, when to use it, and the fact that it performs no fetch or audit. With no output schema, this is sufficient for an agent to select and call the tool 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% and the schema already documents code and lang with an example and enum. The description reinforces the expected format with several criterion codes and mentions es/en, but adds only marginal value 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?

The description states a specific verb and resource: it explains a WCAG 2.2 success criterion in plain language, covering requirements, typical failures, and toolkit verification. It also distinguishes itself from the sibling audit tools by explicitly saying it is a knowledge lookup and '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?

The description gives clear when-to-use guidance: 'Use it whenever you need to explain WHY a finding matters or what the criterion actually says.' It does not explicitly name alternatives or give when-not-to-use conditions, but the knowledge-lookup note and sibling list make the boundary clear.

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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds valuable behavioral context beyond that: the meaning of 'ok=false' (a regression to review) and the accepted input formats (inline JSON starting with '{' or file paths). This enriches the agent's understanding of the tool's output and input handling without contradicting the annotations.

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 description is compact—two or three sentences—and front-loaded with the core purpose and outputs. It uses an em-dash to cleanly separate the alternative-tool note. Every sentence contributes value: purpose, output semantics, input format, and usage differentiation. No fluff or 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?

For a simple two-parameter read-only tool with no output schema, the description covers the essential aspects: what it compares, how to interpret the result (ok=false means regression), and how to provide input. It mentions the specific change types (added/removed/renamed interactives and focus-order changes) which gives context on the diff output. The only minor gap is that it doesn't detail the full output structure beyond the ok field, but given the simplicity and the presence of the sibling tool note, this is sufficient.

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?

The input schema covers both parameters with descriptions ('BEFORE snapshot (inline JSON or path)' and 'AFTER snapshot (inline JSON or path)'), so the schema already documents the basics. The description adds a small but useful detail about inline JSON format (starting with '{'), which goes slightly beyond the schema. With 100% schema coverage, the baseline is 3, and this additional guidance justifies a 4.

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 clearly states the verb (diff), resource (accessibility snapshots), and purpose (regression detection). It enumerates what is compared (added/removed/renamed interactives and focus-order changes) and explicitly differentiates from the sibling a11y_diff_urls by noting it compares existing snapshots while the other snapshots both. This gives an agent a precise understanding of the tool's role.

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?

The description explicitly names the alternative tool (a11y_diff_urls) and the condition for choosing it: 'a11y_diff_urls snapshots both for you.' It also states the typical use case (before/after a deploy) and that it requires existing snapshots, which tells an agent when this tool is appropriate and when another is needed.

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, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds meaningful context beyond that by noting the local Playwright dependency and clarifying that this is a convenience wrapper around two separate operations rather than a novel 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 description is two sentences with no filler. The core operation is front-loaded, and the manual alternative is included without unnecessary detail.

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 simple two-parameter, read-only tool with rich annotations, the description covers what the tool does, its prerequisite, and its relationship to the manual flow. No critical information needed to call it correctly is missing.

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

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

Schema coverage is 100%, and the parameter descriptions already explain that url_a is usually staging and url_b is usually production. The tool description adds no additional parameter-level meaning, so the baseline score of 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?

The description states a specific action: 'Snapshot two URLs and diff them in a single call,' with the staging-vs-production example making the resource and intent clear. It also distinguishes itself from the manual 'snapshot + a11y_diff' flow, so an agent can differentiate it from related sibling tools.

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?

The description explicitly positions this tool as a convenience for staging-vs-production comparisons and names the manual alternative: 'snapshot + a11y_diff.' It also flags the prerequisite 'Requires local Playwright,' giving the agent concrete conditions for when this tool is appropriate.

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 mark this as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: it re-runs the live audit, rejects non-reproducing findings with a reason, and catches false positives/race conditions/page changes. No contradiction with annotations.

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?

Four compact, front-loaded sentences cover action, purpose, output, and usage instruction. Every sentence earns its place with no redundancy or filler.

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?

The description provides the core purpose, output summary, and usage context. Since there is no output schema, it doesn't fully specify the exact structure of confirmed/rejected findings, but it gives enough high-level information for an agent to invoke the tool 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%, and each parameter already has a clear description. The main description doesn't add per-parameter details, so it stays at the baseline 3 without needing to compensate.

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, marks) and resource (audit findings against the live page), and explains the output (fresh score over confirmed findings). It clearly distinguishes the tool from sibling audit and autofix tools by framing it as the verification/disproval step.

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 tells the agent when to use it: 'Run this before acting on any audit report.' It gives clear context for invocation, though it doesn't name alternative tools or state 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?

Beyond the readOnly/idempotent annotations, the description discloses rich behavioral traits: the exact 55-criterion matrix values ('automated-fail / automated-review / not-flagged — NOT pass / not-run / manual-only'), per-row human-effort classes, SHA-256 hashing with timestamps, the empty signature block, the tamper-evidence rule, and the core stance 'Evidence, never conformance.' This significantly exceeds what the annotations already provide.

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 description is dense but every sentence earns its place: it front-loads the core purpose, then covers input acceptance, output contents, pricing semantics, hashing, signature requirements, tamper evidence, and vendor neutrality. Despite its length, it is structured as one coherent specification rather than padded prose, which is appropriate for a complex tool with no 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?

For a complex aggregation tool with nested objects and no output schema, the description is remarkably complete. It specifies what inputs are accepted, exactly what the returned pack contains, how criteria are classified, how human effort is priced, how artifacts are hashed, what the signature block requires, and the tamper-evidence rule. An agent has enough context to invoke it correctly and understand the return value.

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 parameters are already documented in the input schema. The description adds useful context about the reports parameter ('any mode') and the overall purpose of reviewer/snapshot inputs, but it does not substantially enrich the meaning of individual parameters beyond what the schema provides. The brief mention of an 'empty signature block' while the schema has a reviewer parameter for prefilling could cause minor ambiguity but is not contradictory.

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 action and resource: 'Builds the COUNTERSIGNATURE-READY evidence pack' with a defined role as 'the machine→human handoff object for WCAG conformance work.' It also distinguishes itself from siblings by calling itself 'The tier-3 handoff object' and specifying that it aggregates 'every audit report you have,' which clearly separates it from audit-generation or snapshot tools.

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?

The description gives clear guidance on when to use the tool: 'Takes one or more audit reports (any mode — static, rendered, reflow, keyboard, scroll)' and instructs to 'feed it every audit report you have.' It does not explicitly name excluded scenarios or route to alternatives, but the input conditions and handoff purpose are clear enough for an agent to select it appropriately.

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 read-only and idempotent annotations, the description discloses that the tool actually submits the form with invalid data, which is a significant behavioral trait. It also notes edge cases like native validation and forms that navigate on submit, providing transparency about limitations. This adds value beyond the annotations.

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 description is informative but slightly long; it front-loads the purpose and then details the flow and edge cases. It uses punctuation effectively to organize information. It could be trimmed, but it remains readable and well-structured.

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?

The description explains the tool's purpose, process, and limitations, including how it handles novalidate and navigation-on-submit. However, it does not describe the output format or return value, which might be expected from a testing tool. Given the absence of an output schema, this is a minor gap.

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?

The input schema already documents all four parameters with descriptions (100% coverage). The description does not add further parameter-specific details beyond mentioning the Playwright requirement, which is a prerequisite rather than a parameter. Thus, the description adds minimal value to 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?

The description clearly states the tool tests form error identification and suggestion (WCAG 3.3.1 and 3.3.3). It specifies the exact flow: fills invalid data, submits, and checks the post-submit DOM. This distinguishes it from sibling tools like a11y_audit_url, which do general accessibility audits.

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?

The description implies this tool is for form error testing, but it doesn't explicitly state when to use it versus other a11y tools. It mentions a prerequisite (local Playwright) but doesn't describe alternatives or exclusions. The context is clear enough for an agent to infer, but explicit guidance is missing.

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 indicate idempotentHint=true and destructiveHint=true, but the description does not elaborate on these. It does say the generated document is 'accessible' and that it 'saves to output_path when given', which adds behavioral context beyond annotations. However, it doesn't explain what destructive actions might occur (e.g., overwriting files) or specifics about idempotency. The description adds some value but not deeply.

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 description is two sentences, but the first is quite long and packed with information. It front-loads the action and legal frameworks, then adds a brief usage note. Every part is informative, though the sentence is dense; it could be split for readability, but it's still efficient.

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?

Given 13 parameters and no output schema, the description does a good job of explaining the tool's output (HTML statement, accessible) and hints at the workflow (drive from audit findings). It doesn't explain return values, but that's less critical since it saves to output_path. It also mentions legal frameworks and language options, covering the main context an agent needs.

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 parameters are well-described in the schema. The description adds some context by mentioning 'marco' (which corresponds to framework) and specifically calling out 'contenido_no_accesible' as a key for driving from audit findings, which provides usage meaning beyond the schema. But most parameters are self-explanatory, so the description adds marginal 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 clearly states that the tool generates an Accessibility Statement in HTML, with specific legal frameworks (RD 1112/2018 and EAA), and mentions key fields like marco and output_path. It distinguishes itself from siblings by focusing on statement generation, which is unique among the listed tools (siblings are for auditing, contrast, etc.), so it is distinct. However, it doesn't explicitly name a sibling as an alternative, but the uniqueness is clear from the context.

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?

The description implies that the tool is used for generating legal accessibility statements and mentions 'drive contenido_no_accesible from audit findings and a11y_evidence', linking it to audit tools. It gives context for when to use it (after audits) but does not explicitly state when not to use it or name alternatives. The implicit usage context is strong enough for an agent to infer its 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, indicating a safe, read-only operation. The description adds that it requires local Playwright, which is critical for the agent to know before calling. It also implies the tool will perform browser interactions (hover) but does not detail potential side effects or warnings beyond the Playwright dependency; however, given the strong annotation coverage, this is acceptable.

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 description is concise and front-loaded with the criterion and ability. It efficiently uses a dash to introduce scope and alternatives without wasting words. The only minor issue is that it crams several pieces of information into one long sentence, but it remains readable.

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?

Given the tool's moderate complexity, the description covers what it does, when to use it, prerequisites, and scope. The output schema is absent, but the description does not specify what the tool returns (e.g., a report of flagged tooltips). Since it flags issues, a brief note on output format would improve completeness, but the current info is largely sufficient.

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 is documented. The description adds context that the tool runs a browser test requiring local Playwright, which helps agents understand prerequisites. It does not deeply explain each parameter, but the schema covers it, so the baseline of 3 is elevated by the extra environment context.

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 clearly states the tool's purpose: it finds tooltip/overlay candidates, hovers each, and tests whether Escape dismisses the result, flagging non-dismissible tooltips. It identifies a specific accessibility criterion (1.4.13) and distinguishes itself from siblings by stating its scope (tooltips only) and naming the full audit (a11y_audit_dom) and keyboard traps (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?

The description explicitly states when to use this tool (for tooltip hover dismissibility testing) and what it is not for (full audit, keyboard traps), naming the alternatives directly. It also includes a hard prerequisite: 'Requires local Playwright.' This gives the agent clear guidance on invocation 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 read-only, idempotent, non-destructive safety. The description adds valuable behavioral context: privacy implications of POSTing versus sharing URLs, support for self-hosting to avoid sending sensitive content, and the fact that results map to WCAG criteria. These go beyond the annotations and inform the agent of network-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 description is a single dense sentence followed by a PRIVACY note. It front-loads the core purpose and then delivers actionable privacy guidance. No filler, but the structure could be broken into clearer sentences. Every sentence earns its 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?

The tool has no output schema, so the description should clarify the return value. It mentions that it checks for issues and maps to WCAG criteria, but does not specify the format of the report (e.g., list of errors, severity, WCAG references). Given the complexity and lack of output schema, this is a notable gap. Annotations cover safety, but the absence of return-format disclosure leaves the agent guessing.

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 is documented. The description adds extra meaning beyond the schema: for 'url' it notes only the URL is shared, for 'html' it warns about POSTing content and suggests self-hosting for sensitive pages, and for 'base_url' it specifies the docker image. This enriches the schema descriptions without repetition.

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 ('checks') and resource ('URL or raw HTML against the Nu Html Checker'), enumerates the validation aspects (doctype, encoding, structural validity, alt/lang/role), and maps to WCAG criteria. It clearly differentiates from siblings by emphasizing the W3C's authoritative parser, and the privacy note references a sibling (a11y_audit_url) to draw a distinction.

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?

The description provides explicit guidance on mode selection: html mode POSTs content, url mode shares only the URL, and self-hosted base_url is recommended for sensitive content. It mentions a sibling (a11y_audit_url) for similarity but stops short of an explicit when-not-to-use statement against other audit tools. Overall, context for choosing modes is clear, but exclusions are implied rather than 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?

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by detailing the actual algorithm: real Tab walking up to 60 stops, cycle detection, the Escape-release test, and the specific decision rule for reporting a trap as high severity. This is valuable behavioral insight not available from 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?

The description is dense and front-loaded with the core purpose. Every sentence serves a role: algorithm, cycle/escape logic, return value, environment requirement, and scope separation. No filler or 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?

With no output schema, the description still explains the return value (full tab stop list) and the severity logic. It also covers the Playwright prerequisite and scope. It doesn't detail the exact output structure or error behavior, but the essential information for calling is 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?

The schema covers all 4 parameters with descriptions (100% coverage), so the description doesn't need to compensate. It adds some context (e.g., 'up to 60 real tab stops' aligns with max_pasos) but does not materially change parameter meaning 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?

The description states a specific action ('detection') on a specific resource ('keyboard traps') with the WCAG reference '2.1.2'. It explicitly distinguishes from sibling a11y_audit_dom by noting focus visibility is part of that tool, making the purpose unambiguous.

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?

The description gives explicit scope ('keyboard traps (2.1.2)') and identifies the sibling that covers the adjacent concern ('focus visibility is part of a11y_audit_dom'). It also notes a concrete prerequisite ('Requires local Playwright'), helping agents decide when this tool can be used.

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?

The description explicitly describes persistent state accumulation and a record action that adds audit results, which is a write-oriented behavior. However, the annotations declare readOnlyHint: true and idempotentHint: true, which directly contradicts the described mutation and accumulation. This is an annotation contradiction that severely undermines the agent's ability to predict the tool's 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 description is concise and front-loaded: it states the core purpose, lists actions, and explains persistence in three sentences. The provenance mention 'from Cloudflare's security-audit-skill' is slightly extraneous, but overall every substantive part earns its 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?

There is no output schema, so the description must explain return values and call implications, but it does not. It also omits what the 'informe' object should contain and how ledger_path is resolved. While the high-level purpose is clear, the annotation contradiction and missing operational details leave an agent under-equipped to invoke record 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. The description adds useful meaning to the action enum values and clarifies the persistent context, but it does not explain the structure of the 'informe' object or the ledger_path behavior beyond the schema. It meets the baseline but does not compensate for the nested object ambiguity.

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 identifies a specific resource (a persistent coverage ledger) and names three distinct actions with concrete effects: record, gaps, and summary. This clearly differentiates it from sibling audit and analysis tools, as it is the stateful tracking layer rather than an auditing tool.

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?

The action descriptions imply when to use each behavior—record after an audit, gaps to find unchecked URLs, summary for portfolio overview—but there is no explicit when-to-use vs. alternatives guidance. It does not name sibling audit tools or state exclusions, so the usage context is only implied, not fully specified.

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, and destructiveHint false, so the safety profile is covered. The description adds valuable behavioral context beyond that: it loads the URL at two viewports (1280px and 320px), reports horizontal scroll and overflowing elements, and states the local Playwright requirement. No contradiction exists.

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 description is front-loaded with the core purpose and scope, then adds the method note and prerequisite. Each sentence earns its place—there is no filler or repetition. The structure flows logically from what it does to how to do it correctly.

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 test tool with no output schema, the description is complete: it explains what is measured, what is reported (real horizontal scroll + overflowing elements), the scope (1.4.10 only), and the alternative tool for broader coverage. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so all four parameters (url, lang, timeout, auth_state) are documented in the schema. The description only implicitly references url ('Loads the URL') and does not add any param-specific guidance or format details, so it stays at the baseline for full schema coverage.

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: 'Reflow check at 320px' targeting criterion 1.4.10, and explicitly differentiates from siblings by noting it is the check axe and Lighthouse do not automate. It also names the sibling a11y_audit_dom as the alternative for a full rendered pass, making the tool's purpose unambiguous.

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 explicitly directs the agent to use a11y_audit_dom for the full rendered pass, and explains the correct measurement method (1280 @ 400% zoom = 320px) to avoid misinterpretation. The 'Requires local Playwright' prerequisite further clarifies when the tool is applicable.

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) already convey the tool's safe, read-only, side-effect-free nature. The description adds significant context beyond that: it details what the audit checks (focused element survival, announcement, feed end), how it works (real scrolling, live-region observer), and its honest guard (skipping unfounded signals). However, it does not mention potential heavy resource usage or timeouts, which would be useful for an automation 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?

The description is information-dense but well-structured, with the key purpose front-loaded in the first sentence and additional details organized logically. It uses a clear em-dash structure and includes practical usage notes without fluff, making every sentence earn its 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?

For a complex auditing tool with 4 parameters and no output schema, the description covers most critical context: what it does, how it works, its limitations, and when to use it. However, it doesn't specify what the output format looks like (e.g., report structure), which an agent might need to know if it plans to parse results. Yet since there's no output schema, this is a minor gap, and the description is otherwise quite thorough.

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?

The schema description coverage is 100%, so parameters are fully documented there. The description adds minimal extra meaning, but it does mention 'login walls' suggesting auth_state use, and 'scroll batches' aligns with max_tandas. Since schema already covers the parameters well, a baseline of 3 is appropriate; the description doesn't need to repeat what's already clear.

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 clearly states the tool audits infinite-scroll feeds for accessibility, listing specific criteria (2.4.3, 4.1.3, 2.2.2) and the ARIA APG Feed pattern. It explicitly distinguishes itself from 'a11y_audit_url/dom' for general page audits, which differentiates it from sibling tools.

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?

The description explicitly states 'For paginated feeds only; general page audit is a11y_audit_url/dom,' giving clear when-to-use guidance and naming the alternative. It also warns about login walls and non-standard markup, and notes the requirement for local Playwright, which helps the agent decide if the tool is appropriate.

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 behavior. The description adds valuable behavioral context that annotations cannot convey: it requires local Playwright, behavior varies by Playwright version (≥1.49), and it reports the accessibility tree as what a screen reader announces. No contradiction with annotations.

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 description is informative and mostly well-structured, with the key output details front-loaded. It is slightly redundant by mentioning comparison with a11y_diff twice ('Save it before a deploy and compare after with a11y_diff' and 'compare with a11y_diff'), but it remains efficient and readable.

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 tool without an output schema, the description explains the output contents, the prerequisite environment, the version-dependent behavior, and the sibling tools to use for comparison. An agent has enough context to invoke it correctly and to route the result into the intended diff workflow.

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 parameters url and auth_state are already documented in the schema. The description adds context about the overall tool behavior and prerequisites, but does not materially deepen the meaning of either parameter beyond what the schema provides. 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?

The description uses a specific verb and resource: it captures an accessibility snapshot of a URL and enumerates exactly what it contains (interactive elements in DOM order, real tab focus order, and the computed ARIA snapshot when available). It is clearly distinct from sibling tools by emphasizing the snapshot-and-compare workflow rather than auditing or fixing.

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 workflow guidance: 'Save it before a deploy and compare after with a11y_diff' and 'Capture half of the watch loop'. This tells the agent when in a process to call it. It does not enumerate exclusions versus every sibling tool, but the comparison and prerequisite guidance are strong.

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 (readOnlyHint, idempotentHint, destructiveHint=false), the description adds valuable behavior: it 'walks the accessibility tree linearly' and explains the output as 'announcement text with roles, names and states'. It also discloses the Playwright dependency, which is not present in structured data. No contradiction with annotations.

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 description is front-loaded with the core purpose ('what a blind user HEARS') and then provides distinctions and requirements. It is fairly concise, though the phrase 'the linearized reading experience, as prose an agent can READ' is slightly redundant with the earlier 'Walks the accessibility tree linearly and returns the announcement text with roles, names and states'.

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 describing the return value as announcement text with roles/names/states as prose. It includes prerequisite Playwright and differentiates from siblings. Missing edge cases or error behavior, but these are minor for a read-only transcription tool.

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?

The input schema has 100% coverage with each parameter (url, lang, timeout) already described. The description does not add additional parameter-level meaning, so the baseline of 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?

The description clearly states the tool's function: it walks the accessibility tree linearly and returns announcement text with roles, names, and states. It also differentiates from siblings by naming a11y_snapshot for structure and a11y_keyboard for keyboard traps, so an agent can distinguish it from other a11y tools.

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 guidance is given: 'for structure use a11y_snapshot, for keyboard traps use a11y_keyboard' directly steers the agent to alternatives, and the 'Read-only' label indicates when to use this tool. The requirement 'Requires Playwright' also serves as a practical precondition.

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, and destructiveHint. The description goes beyond those by explaining the algorithm (opaque, RGB distance), the default target ratio of 4.5, and what the function returns (color, ratio, lightens/darkens). There is no contradiction with annotations.

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 description is two compact sentences that front-load the core algorithm, then state the return value shape and the relationship to a11y_contrast_pair. No filler or redundant words; every clause earns its 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?

For a read-only, 3-parameter tool with 100% schema coverage and strong annotations, the description adequately explains the behavior and return values despite the lack of an output schema. It does not specify the accepted color-string format or edge cases (e.g., impossible targets), which is a minor gap but not a major one.

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?

Input schema coverage is 100%, with useful descriptions for fg, bg, and target including valid ratio values. The description adds algorithmic context ('nearest opaque', 'RGB distance') but mostly repeats the default 4.5 already present in the schema. It does not add input format or extra parameter meaning, so 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?

The description clearly states a specific operation: find the nearest opaque color to fg that reaches the target ratio against bg. It also names the return type (color, ratio, lighten/darken) and explicitly frames itself as the fixer companion to a11y_contrast_pair, distinguishing it from the sibling tools.

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 explicitly tells the agent when to use this tool: as the fixer companion to a11y_contrast_pair failures. It does not explicitly list when not to use it or compare against a11y_autofix, so it is clear but lacks exclusion guidance.

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