cancel_alert

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

Annotations already indicate destructive is true and readOnly is false, but the description adds meaningful nuance: the operation is permanent, won't re-trigger unless condition recurs, and confirmed=False returns a preview without making changes. This goes well beyond the annotation metadata.

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 compact, well-structured, and front-loaded with the core action. The 'Args' section is minimal and each line adds value without repetition. It avoids padding and stays under a reasonable length for the tool's complexity.

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 destructive cancellation tool with no output schema, the description covers what the agent needs: what it does, when to use it, what happens on confirm/cancel, and all parameters. The sibling context (acknowledge_alert) is also considered, making the description complete for operational 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 coverage is 0%, so the description carries the full burden. It clearly explains alert_id as the alert UUID, confirmed as a safety switch requiring True to actually cancel with default False preview mode, and target as an Aria target name from config with a sensible default. This fully compensates for the schema's lack of descriptions.

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 starts with 'Cancel (dismiss) an active alert' and explicitly states it is a WRITE operation that permanently closes the alert. It clearly identifies the resource (alert) and the specific action (cancel/dismiss), and does not get confused with acknowledge_alert.

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 explicit usage guidance by pointing to acknowledge_alert when the user only wants to mark an alert as seen. It also explains the behavioral distinction: cancelled alerts will not re-trigger unless the underlying condition recurs, helping the agent choose correctly between similar tools.

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