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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds non-obvious behavior: calendar grouping can pull in earlier dates, evidence dates live in scope.date_basis.range, and unavailable history must be treated as missing rather than zero. It stops short of covering pagination or result-size behavior across the two page-size params.

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 most important information (what it answers, which view to pick) is front-loaded, and the dense sentences each carry guidance. The final comparison sentence is somewhat compressed into a multi-clause run, but no sentence is filler.

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?

An output schema exists, so return shapes need not be explained, and the primary analytical workflow is well covered. But for a 17-parameter tool, roughly eight parameters remain undocumented anywhere, leaving an agent to guess at stage filters, segmentation values, and paging behavior.

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?

At 59% schema coverage the description usefully clarifies group_by (day vs calendar-boundary grouping), date_range bounds, and comparison alignment. However several parameters — start_stages, end_stages, segment_value, pipeline_stages, page, page_size, group_page_size — carry no explanation in either the schema or the description, so the coverage gap is not compensated.

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 opening states a specific verb and resource — return pipeline history for a date range — and immediately enumerates the three supported analytical views (waterfall, stage-transition, deal-change). It also implicitly separates itself from state-only siblings by noting that snapshot 'shows state, not change drivers.'

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?

Explicit routing is given: start with waterfall for what changed, stage_transitions for stage-flow causes, deal_changes for supporting deals, and day grouping for exact date ranges. It also prescribes the comparison workflow (call once per range with identical non-date arguments, align by explicit ranges and returned order).

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