swsd_change_calendar

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds far more: only page/per_page reach the server, filters are client-side over scanned rows, rows missing a valid planned start are excluded and counted as unscheduled, conflict details are capped at 200 while conflict_count counts all pairs, and truncated=true means unscanned records may hold more matches. That is exactly the kind of hidden-cost disclosure an agent needs.

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 is front-loaded in sentence one, and subsequent sentences are dense with operational facts rather than filler. The telegraphic style ('Overlap, with an exclusive end', 'scan reports pages_fetched per kind') is compact but occasionally terse enough to require a second read.

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 10-parameter, zero-required scanning tool with an output schema, this covers the risky edges: timezone and default window, overlap semantics, invalid-data fallbacks, truncation flags, and the scan diagnostic block. An agent could call it correctly and interpret the limits of the answer without opening anything else.

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 coverage is already 90%, so the baseline is 3, but the description earns above that by explaining which parameters are actually transmitted to SWSD versus evaluated locally — a distinction absent from the schema and material to interpreting quality of results. It also restates the max_pages default/maximum and the exclusive-end overlap rule, though it does not clarify per_page's effect on scan completeness.

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?

First sentence names a specific verb and resource ('Show a UTC change/release calendar widget') plus a secondary capability ('shared-CI/group scheduling conflicts'). No sibling tool in the list produces a calendar or conflict view, so the agent can tell instantly that this is the only option for scheduled-change visibility.

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 establishes the operating envelope: page-limited scanning, client-side filtering, defaults of today-to-plus-30-days, and the caveat that conflicts cover only returned items. What it lacks is an explicit 'use this instead of X when…' routing statement, though no sibling overlaps enough to make that a serious gap.

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