swsd_ticket_stats

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

Beyond the annotations (readOnly/openWorld/idempotent/non-destructive), the description discloses the two-pass mechanism (alternating created and updated incident queries), ID deduplication, a shared max_pages budget, and the scan-boundary limitation. It also defines derived semantics (Open excludes Resolved/Closed, unassigned means no individual assignee, breach computed via computeSlaRisk), and warns that list rows may omit resolved_at so resolution metrics can be incomplete — behavioral detail the annotations cannot convey.

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?

Purpose and window are front-loaded, then caveats follow in a logical order (mechanics, scope limits, metric definitions, data-quality gaps). It is dense and somewhat run-on, with mild overlap between the resolved_at exclusion sentence, the 'list API may omit resolved_at' sentence, and the trailing absence caveat, but no sentence is purely 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?

Given five optional params, an output schema, and a genuinely complex sampling design, the description covers nearly everything an agent needs: scan scope, dedup, SLA and resolution metric definitions, and known incompleteness. The remaining implicit points — the effective row cap (max_pages × per_page) and what happens when the budget is exhausted mid-scan — are the main omissions.

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 schema already documents inclusive/exclusive window ends, UTC midnight date-only handling, defaults, and the max_pages range. The description restates the window semantics and confirms the shared max_pages budget, but adds little about per_page or assigned_to_group that the schema does not already supply.

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 sentence gives a specific verb and scope: 'Summarize scanned tickets created OR last updated in [from, to)', which distinguishes it from the sibling list tools that return rows rather than aggregates. It never names an alternative tool (e.g. swsd_list_incidents or swsd_sla_risk) explicitly as a routing choice, so the differentiation is inferable rather than stated.

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?

Guidance is implied through scope statements: 'Totals and breakdowns cover only scanned matching rows, not the tenant backlog or a historical state snapshot' tells the agent when this output is and isn't the right answer. However, there is no explicit when-to-use/when-not-to-use routing against siblings, and no prerequisite or cost guidance despite the paged double-scan design.

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