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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description's 'Discard' aligns with those. It adds useful context by stating that bindings are removed along with the revision and that only drafts are eligible, which goes beyond the structured annotations. It does not mention permissions or irreversibility, but the core destructive behavior is clearly disclosed.

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?

Two highly efficient sentences with the primary action front-loaded and the key constraint in the second sentence. There is no filler, no repetition of the title or schema, and every clause earns its place.

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 two-parameter destructive operation with full schema coverage and appropriate annotations, the description is complete: it identifies the target, the side effect on bindings, and the eligibility restriction. No output schema exists, so omitting return-value details is acceptable.

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%, with both revision_id and automation_id already documented as UUID IDs. The description's mention of 'draft revision and its bindings' adds a little semantic context about what is deleted, but it does not need to elaborate on the individual parameters given full schema coverage.

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 ('Discard') and a specific resource ('a draft revision and its bindings'). The follow-up sentence, 'Only drafts can be discarded; live and historic revisions are immutable history,' clearly distinguishes the tool from revision-lifecycle siblings such as activateAutomationRevision or promoteRevision.

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 explicitly states when the tool should be used—discarding a draft revision—and gives a clear when-not: live and historic revisions cannot be discarded because they are immutable. It does not name an alternative tool, but the boundary is unambiguous.

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