explain_issue

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

No annotations are provided, so the description carries the full burden. It states the tool provides educational information but does not disclose any behavioral traits such as read-only nature, side effects, or authentication needs. While no negative traits are implied, the description fails to explicitly assure safe or non-destructive 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 concise sentences that front-load the primary purpose and then enumerate the educational content. Every sentence adds value and there is no extraneous 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?

Given the tool's simplicity and the absence of an output schema, the description adequately captures what the agent can expect (plain-language explanation, fix guidance, etc.). It does not specify the exact output format (e.g., text, structured data), which is a minor gap, but overall it is sufficient for an agent to understand the tool's role among complex sibling tools.

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 does not add semantic detail beyond the schema: it does not mention or elaborate on the two parameters (ruleId and context). The schema itself already provides clear 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?

The description clearly states the verb 'Explain' and the resource 'accessibility issue', and lists specific educational content (why it matters, how to fix, WCAG references, code examples). This distinctly sets it apart from sibling tools focused on auditing, scoring, and reporting.

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 the tool is used after an issue is identified (e.g., from audit tools), but it does not explicitly state when to use this versus alternatives or provide 'when not to use' guidance. It lacks explicit contextual direction.

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