Shell cancel session

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description goes beyond them by naming exactly what is destroyed ('kills every process tree' / 'running commands are killed') and adding the iteration mechanism ('in-process shell run table') plus output shape and a 'Batch-safe: no' caveat. It stops short of stating permission requirements or failure behavior for already-dead processes.

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?

Front-loaded with the core action and scope, then labeled lines for when/avoid/destructive/speed/output. Dense but every line carries a distinct fact; slightly terse telegraphic style ('Batch-safe: no') reads more like a spec sheet than prose.

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 zero-parameter destructive tool with no output schema, the description supplies the output shape (cancelled_run_ids[], count), destructiveness detail, speed, and batch-safety. Nothing an agent needs to invoke it safely 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?

Zero parameters, so the schema carries nothing and the 4 baseline applies. The description implicitly clarifies the scope is session-wide rather than parameterized, which is the only semantic an agent could get wrong here.

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?

States a specific verb and resource ('Cancel ALL shell runs tracked in this session') plus the effect ('kills every process tree'), and contrasts its 'ALL' scope against the sibling project_shell_cancel that works by run_id. An agent can distinguish it from the per-run canceller without reading either schema.

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?

Explicit 'Use when' (session ending, stuck session with many running commands) and 'Avoid when' (only one run needs cancelling → project_shell_cancel by run_id) give a decision rule naming the alternative tool. Nothing is left to inference.

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