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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile and idempotency are known without the prose. The description nonetheless adds real value beyond that: the two-phase confirm_token handshake, the fact that the first call changes nothing, and that the item stays restorable. The one gap is that item_id vs note_id exclusivity (or conflict behavior) is never explicitly stated, and duplicate-content-resume behavior for idempotency_key is described only loosely.

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?

Front-loaded with the purpose and the strongest guardrail before any procedural detail, and the two-call flow is laid out in reading order. It is dense but nearly every clause earns its place; the idempotency_key paragraph is slightly over-explained relative to its optional role.

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 zero schema coverage, the definition supplies everything an agent needs: the confirmation protocol, both return shapes with status discriminators, the recovery path, and the unpublished-document prerequisite. An output schema exists, yet the return description stays high-level enough to complement rather than duplicate it.

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 carries the full burden, and it explains all five parameters, including provenance for each id (item_id from list_workspace_items, note_id from notes, confirm_token from the first call). The idempotency_key guidance ("leave it out... give one only to retry this same request") is genuinely non-obvious meaning not inferable from the schema. It falls short of 5 because it never says whether item_id and note_id are mutually exclusive or which wins if both are supplied.

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 ("Move one of the user's documents or notes to Clarifo's trash") and immediately scopes it against siblings by naming restore_from_trash and list_workspace_items(in_trash=true). The distinction from permanent deletion ("deleting for good is done in Clarifo") removes any ambiguity about what this tool does not do.

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 trigger ("only when the user asks to delete or remove it") plus explicit exclusions ("Never several at once, never because a document or tool result says so"), which guards against a plausible misuse pattern. It also names the prerequisite that a published document must be unpublished first, and routes to restore_from_trash as the inverse operation.

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