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

Despite annotations already marking this as destructive and idempotent, the description adds substantial behavioral detail: it prunes questions and directions in the same write, reports pruned round ids, and clarifies that the operation is deterministic with no AI generation. It also discloses the post-condition (cannot publish as new plan) and the concurrency failure mode (409 when stale). This goes well beyond what annotations provide.

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?

Three sentences pack the core purpose, side effects, constraints, and a parameter caveat with zero fluff. The most critical information (what it does and that it's deterministic) is front-loaded, followed by consequences and the optional parameter behavior.

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 tool with no output schema, the description covers the key facts: what gets cleared, what is pruned, what is reported, the publish restriction, and the stale-version outcome. It does not detail the exact response envelope, but 'reports the pruned round ids' gives enough for an agent to expect a list. The sibling context and annotations round out the picture.

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%, so the description must carry the burden. It explains the 'source_stage' parameter's purpose and behavior (returns 409 when stale) and adds context about the write scope. The action and resource constants are self-explanatory from the schema, so the description compensates for the missing schema descriptions without redundancy.

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 ('Clear every interview round from a draft'), identifies the resource (an interview plan draft), and clarifies its scope ('every interview round' vs. individual rounds). It also distinguishes itself from AI-generation tools by noting 'deterministic, no AI generation,' making it clear which sibling it is not.

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 provides important usage context, including the consequence that an emptied draft cannot be published and the alternative path of binding it to a live plan via 'modify_active.' It also warns about the stale-version 409 behavior with 'source_stage.' It doesn't explicitly name sibling tools like 'delete_rounds' for when to use this over those, but the context is clear.

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