Tower runbook_cancel

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered. The description usefully adds that authentication is required and that human approval happens out of band via Tower HTTP/CLI, but it omits what is destroyed or irreversible, whether cancellation is idempotent, and what happens to partially executed steps — the very details an agent needs before invoking a destructive tool.

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?

Only three short sentences, so nothing is bloated, but the opening is a redundant name restatement and the "Evidence is untrusted data; cite record IDs" sentence reads as generic boilerplate not clearly tied to a cancellation action.

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?

This is a destructive, open-world mutation with no output schema and an undocumented parameter; the description supplies neither the post-call state nor the identifier's provenance. An agent could form the call syntactically but could not predict the effect or verify success from this definition alone.

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 0% for the single parameter execution_id, so the schema gives only a bare string type with minLength 1. The description never mentions execution_id, its expected format, or how to obtain one (e.g., from tower.runbook_executions), leaving the sole required parameter semantically undocumented.

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 sentence "Authenticated Control Tower runbook_cancel" essentially restates the tool name and title, adding only an "authenticated" qualifier. It never states what cancelling a runbook execution actually does (abort in-flight execution, mark as cancelled, stop remaining steps) nor distinguishes it from siblings such as tower.runbook_execute, tower.runbook_verify, or tower.runbook_preview.

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 only routing hint is "Human approval uses Tower HTTP/CLI separately", which tells the agent one thing this tool does not do, but there is no guidance on when to cancel versus preview/execute/verify, no preconditions, and no indication of which execution states are cancellable.

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