get_statistics

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

No annotations are provided, so the description carries the full burden. 'Generate detailed statistics' implies a non-mutating analysis operation, but the description does not explicitly state side effects, return format, or any permissions required. It provides minimal but sufficient transparency for a likely 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?

The description is two concise sentences, front-loaded with the main purpose and followed by relevant detail. No redundant or extraneous information, making it efficient and easy to parse.

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 has no output schema, the description does not explain what the returned statistics look like (e.g., counts, percentages, structure). It also omits edge cases like empty results or how breakdowns are presented. While adequate for a simple statistics tool, the lack of output details leaves some uncertainty.

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 both parameters described in the schema. The description adds little beyond the schema, only restating the breakdown dimensions and supporting single/multiple results, which are already covered by the schema's oneOf definition. The baseline of 3 is appropriate when schema handles the semantic 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 clearly states the tool generates detailed statistics from audit results and lists specific breakdown dimensions (category, impact, WCAG level, rule ID). It also notes support for single or multiple audit results. While it doesn't explicitly distinguish itself from siblings like aggregate_audit_results or generate_summary_report, the focus on statistical breakdowns makes the purpose clear.

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 usage for generating statistics from audit results, and the phrase 'Supports single or multiple audit results' gives context on input flexibility. However, there is no explicit guidance on when to prefer this tool over alternatives, nor any mention of 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.