Reset your dedup pool

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

Annotations flag destructive/idempotent, but the description goes further by spelling out exactly what is destroyed ('handles you imported are removed') and the restoration semantics ('accounts earlier runs delivered ... go back to how they were before you blocklisted them'). It also discloses the confirm=true gate, which the schema does not explain.

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?

Four tight sentences, front-loaded with 'DESTRUCTIVE.' then the default behavior, the all=true variant, and the confirm requirement. No filler.

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 reset with no output schema, everything needed to call it safely is present: blast radius of both modes, restoration effect, and the confirm gate.

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 0%, so the description must carry both parameters — and it does: all=true deletes the entire pool including run-collected entries, confirm=true is required. Semantics are clear, though types/enum-style constraints come only from the schema.

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?

Names a specific verb and resource ('Clear your dedup pool') and immediately scopes it: default clears only blocklist-imported handles, all=true wipes the whole pool. An agent can separate this from get_seen_accounts/add_seen_accounts without opening a 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?

Gives a clear selection condition between the default and all=true modes and states the confirm prerequisite. It does not explicitly name sibling tools or when to prefer them over this reset, so it falls short of full routing guidance.

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