Permanently delete a JSM alert

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

Annotations already indicate destructive and non-read-only behavior, but the description adds substantial context: deletion has no undo, destroys notes/activity/attachments/timing, is asynchronous and requires verification via jsm_get_request_status, and needs a separate delete:ops-alert grant. This fully discloses the behavioral weight of the operation beyond what the annotations alone 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?

The description is longer than average, but every sentence is load-bearing: the most important warning is front-loaded, the destructive implications are explained, the narrow justifications are named, async behavior is highlighted, and permission constraints are included. The use of bold, section headers, and bullet-like structure makes the length navigable rather than bloated.

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 asynchronous mutation tool with one parameter and an output schema, the description covers every essential decision factor: what is destroyed, when deletion is justified, when it is not, how to confirm user consent, how to verify completion, and what permission is required. The return shape is described and the output schema exists, so no critical context is missing.

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%, and the schema already explains that alert_id must be the full alert id rather than the tinyId, provides an example, and directs the agent to jsm_list_alerts. The description's Args line repeats 'full alert id (not the tinyId)' but adds no new parameter-level semantics beyond the schema. The pre-call instruction to read the alert is usage guidance, not parameter semantics.

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 states a specific action: permanently delete a JSM alert and everything recorded on it. It explicitly distinguishes itself from jsm_close_alert by explaining what is lost in deletion versus what is preserved when closing. This makes the tool's purpose unmistakable and clearly differentiated from its siblings.

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 unusually explicit when-to-use and when-not-to-use guidance: it names the narrow cases that justify deletion, warns it is 'almost never the right tool,' and enumerates forbidden uses such as tidying up, clearing queues, or looping over search results. It also requires reading the alert back and obtaining explicit user consent before calling.

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