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

Annotations already declare the safe read-only, idempotent profile, but the description adds critical non-obvious behavior: it does NOT run the scan, axe-core needs a real browser DOM, and the score comes from a local run rather than the tool. It also discloses the install prerequisite (npm i -D @axe-core/playwright) and that returned checks are PENDING_EXECUTION — none of which the annotations 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?

Front-loads the deliverable and constraints effectively, and every sentence carries information. There is mild redundancy in stating twice that the tool returns the checks plus a Playwright script (once in prose, once in the JSON shape), but the structure is otherwise tight and scannable.

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 fully compensates by spelling out the return shape ({checks[{id,name,status}], playwright_script, install_command, run_command}) and the PENDING_EXECUTION status. For a tool whose real execution happens locally, this is complete enough to call 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 goes further by explaining the purpose of `config` (customizes axe.configure(), e.g. branding overrides or rule disables) and that omitting it yields standard WCAG 2.2 AA, adding practical meaning beyond the schema's field descriptions.

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 (Get) and resource (WCAG 2.2 AA accessibility verification framework), enumerates the concrete deliverable (11 checks a01-a11 plus a Playwright + axe-core script template targeting the URL), and explicitly contrasts itself with the sibling designesy_score. An agent can distinguish this from the other designesy_* scoring tools 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 an explicit when-to-use ('audit a site for accessibility violations') and a when-NOT-to-use with the named alternative ('for a full design-contract score (not just a11y), use designesy_score'). Routing between siblings is unambiguous.

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