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

Annotations already declare non-read-only, destructive and idempotent, and the description goes well beyond them: state transition to in_takedown, arming of recurring record refreshes, persistence until close/resolve/dismiss, and repeat-call behavior returning created=false. The only gap is that 'destructiveHint: true' is left unqualified — the description says the match is moved and refreshed but never says what, if anything, is lost or overwritten.

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?

Purpose is front-loaded in the first clause, and each subsequent sentence carries distinct information (precondition, side effects, lifecycle, idempotency, sibling routing). It is dense but long; the sibling-routing sentence could arguably be trimmed, though nothing is pure repetition.

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?

Covers precondition, state effects, idempotency, lifecycle exit conditions, and next-step tools, and an output schema exists so return values need no explanation. For a one-parameter state-transition tool this is fully specified.

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 100% and match_id already points to list_matches, so baseline is 3. The description adds real semantic constraint on which match_ids are valid, namely that the match must be open and that a closed match errors — meaning the description adds meaning beyond 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?

States a specific verb and resource ('Start a self-guided takedown on a match') and immediately delimits scope: opens a manually worked enforcement attempt, not an automated one. The phrase 'notolens never submits or sends anything itself' cleanly separates it from any sibling an agent might mistake for a submission tool.

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 an explicit precondition ('Requires an open match (inbox or watching); a closed match errors') and names the follow-on siblings with their roles: add_takedown_event records work, update_takedown closes, get_match_evidence provides the PDF. The agent knows when to call this and what to call next.

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