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

With no annotations, the description carries the full behavioral burden. It discloses that counts are computed server-side over the full period, making results authoritative where client-side tallying would be incomplete, and it reveals that breakdowns map directly to chart components. It does not discuss errors, permissions, or response shape, but the most important behavioral caveat is clearly surfaced.

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 efficient: it enumerates outputs, states the primary use case, explains the correctness advantage over the sibling tool, maps results to chart components, and gives a default-behavior tip in three sentences. Every sentence contributes new information and the most important directive is front-loaded in caps.

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?

Even without an output schema, the description names the concrete aggregates and breakdowns the agent should expect, covers all four optional parameters through the schema, and adds usage and defaulting context. For a read-oriented reporting tool, this is sufficient for a correctly targeted call.

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, but the description adds value by explaining that omitting startDate and endDate selects the default period. It also frames platform and testSuite as optional restrictions in a way consistent with the schema. This goes slightly beyond the schema's field-level 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 identifies this as a pre-aggregated automation statistics tool, enumerates the exact data it returns (pass/fail counts, pass rate, per-platform/per-device breakdowns, slowest/most-failed commands), and explicitly frames it as the tool for charts and totals. It distinguishes itself from automation_sessions_list by calling out that manual tallying would only cover the recent window.

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 direction: 'USE THIS FOR ANY CHART OR TOTAL' and explains why it is the correct choice over automation_sessions_list for aggregate accuracy. It also names the alternative explicitly and provides the practical default-period hint, so an agent can decide when to select this tool without opening either schema.

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