Statistics for a period

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

Annotations already declare readOnly, openWorld, and idempotent. To that the description adds effective non-annotation behavioral context: reports cost no API units, the tool checks the requested period and refuses requests past the rolling three-year boundary instead of returning a silently cut subset, and dates are explicit so the same request remains stable. No contradiction with annotations; this goes well beyond the structured hints.

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 reasonably concise and front-loads the core purpose in the first sentence. The second paragraph is longer but earns its place by warning about the exact boundary behavior, which is critical for correct invocation. It could be slightly tighter, but every part contributes meaningfully.

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?

The description covers the most important behavioral caveat and the cost advantage, and the schema covers several parameters. However, there is no output schema and the description does not describe what the returned rows look like, nor does it clarify several parameters such as filters, name, or include_vat. For a tool with 9 parameters, this is functional but not fully complete.

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 67%, so the schema already handles many parameters such as date formats, fields examples, report_type examples, and client_login behavior. The description adds general date semantics ('Dates are explicit rather than relative') and the period-boundary rule, but it does not explain underdocumented parameters like name, filters, or include_vat. This is adequate but not a strong compensation for the remaining gaps.

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 states the verb and resource: 'Ask for a report and get its rows.' It identifies the tool as a report-generation operation and distinguishes it at a high level from object calls by emphasizing that reports return prebuilt rows and cost no API units. It does not explicitly name a sibling tool, but the purpose is still specific and actionable.

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 gives clear context for when to use the tool: when you need report rows rather than rebuilding numbers from object calls, since reports are cheaper. It also explains the date boundary behavior, telling the agent that requests reaching past available statistics will be refused rather than silently truncated. It does not explicitly enumerate alternatives or exclusion conditions, so it stops short of a full 5.

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