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

The description adds valuable behavioral detail beyond the annotations: it states the operation returns immediately, cleanup is best-effort, and the sweeper will retry failures. It also explicitly clarifies what is destroyed (scratch dir) and what is not (live site), complementing the readOnlyHint, destructiveHint, and idempotentHint annotations without contradicting them.

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 two sentences with no filler. The primary action and target come first, followed by the key safety guarantee and the timing/cleanup nuance. Every sentence contributes critical information.

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 simple one-parameter tool with an output schema, the description covers purpose, safety, and asynchronous cleanup behavior, which is nearly complete. It does not formally define what a 'staging session' is or state explicit prerequisites, but the lifecycle context from sibling tools (begin_deploy, commit_deploy) mitigates this minor gap.

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 100%: deployId is described as 'Session id to abort.' The description does not add further parameter detail, but with full schema documentation and a single obvious parameter, no additional explanation is required. Baseline 3 is appropriate.

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 uses a specific verb and resource: 'Discard a staging session and its scratch dir.' It clearly identifies the tool's action and distinct target, and the phrase 'Live site is untouched' differentiates it from deployment or site-deletion operations among the sibling tools.

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 clear context: this is for discarding a staging session, not touching the live site. It implies the appropriate moment to use the tool, but it does not explicitly contrast it with sibling operations like commit_deploy or begin_deploy, so exclusions and alternatives are left to inference.

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