Collect Incidents

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

Annotations already declare readOnlyHint and destructiveHint=false, so the safety profile is covered; the description adds genuine non-obvious behavior that annotations do not: multi-page collection, compacted payloads, and that out-of-bounds arguments are clamped and reported rather than rejected. It stops short of covering rate limits, permissions, or how paging failures surface, so it is strong but not exhaustive.

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?

Three short sentences ordered by usefulness: what it does, when to choose it over the sibling, then the argument caps. No filler, no restatement of the title, and the routing guidance is front-loaded before the mechanical details.

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?

With 12 optional params, an output schema already defined, and read-only annotations, the description covers the essentials an agent needs: purpose, alternative selection, and bounds behavior. The gaps are not mentioning search_incidents as an alternative and not clarifying what 'compact' means relative to a full incident record, which matters for audit use.

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% across all 12 parameters, and the description's stated caps (max_results <= 100, batch_size 10-100) largely restate what the schema already declares as min/max. The one marginal addition is that out-of-range values are clamped rather than erroring, which is useful but thin against an otherwise schema-driven parameter story — baseline 3 applies.

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?

States a concrete verb and resource ('Collect a bounded working set of incidents across multiple pages') and frames the output shape ('compact batch', 'payload size under control'), which is clearly distinct from a plain list. It explicitly contrasts with list_incidents, though the closely related filtering sibling search_incidents is never addressed, leaving some ambiguity about which filtering tool to pick.

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?

'Use this instead of list_incidents when you want a compact batch of incidents in one tool call' gives an explicit alternative and the condition that selects it. However, it offers no when-not guidance and never mentions search_incidents, which overlaps heavily on the query/team/severity filters this tool exposes.

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