Retrieve Reporting Statistic

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

The annotations declare readOnlyHint=true and openWorldHint=true, and the description does not contradict them. The description adds useful behavioral context beyond the annotations, such as the query structure depending on the scope field, support for filtering/grouping/measures/time analysis, and cursor-based pagination. It does not mention rate limits or auth, but the read-only annotation provides a baseline.

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 the alternative, then capabilities, and finally a comprehensive scope list. The sentence 'Retrieve analytics reporting statistics data' is somewhat redundant with the opening line, but the extensive scope list and procedural details justify the length for a tool of this complexity.

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 low-level API with no output schema, the description covers the core aspects: the low-level nature, the alternative, scope semantics, query capabilities, and pagination. It does not explicitly describe the response format, which could be a gap, but the detailed scope and measure/dimension lists give agents enough context to infer expected results.

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 significant meaning by enumerating all 27 scopes with parenthetical explanations (e.g., 'tickets-closed (closed ticket stats)'), which goes beyond the schema's bare enum list. This helps the agent select the correct scope and understand the resulting query shape.

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 the tool as 'Retrieve analytics reporting statistics data' and its low-level nature ('POST /api/reporting/stats — Low-level reporting API'). It distinguishes itself from the sibling tool gorgias_smart_stats by positioning itself as the low-level alternative, which makes its 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 states when to prefer the alternative: 'For easier stats with automatic scope defaults, dimension validation, agent name resolution, and date handling, use gorgias_smart_stats instead.' This provides clear when-not-to-use guidance and names the alternative, making the use case boundaries explicit.

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