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

Annotations declare destructiveHint=true but say nothing about scope or recovery; the description fills both gaps by stating the cascade (connections and anchored opportunities go with it) and the reversal path via compass_pages_restore. It also discloses the interactive approval behavior (may return `needs_confirmation`, name the page and wait), which is non-obvious runtime behavior not captured anywhere in structured fields.

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-loads the operation and its soft-delete semantics before the usage routing. Every sentence does distinct work: mechanism, cascade, reversal, use-case, counter-case, id provenance, confirmation flow.

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, confirmation-gated tool with no output schema, the description covers mutation scope, reversibility, the required interaction loop, and prerequisite id lookup. An agent has everything needed to call it correctly, including knowing it may have to pause for user approval.

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%, so the baseline is 3 and the schema already carries per-parameter text. The description still adds meaning the schema does not: where pageId values originate, and the approval protocol that gives approvalId its purpose.

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+resource ('Moves a page to the trash') and immediately qualifies the mechanism as a soft delete, so the agent knows this is recoverable rather than permanent. It explicitly distinguishes itself from compass_pages_update and points at compass_pages_restore, so no sibling ambiguity remains.

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 when-to-use ('a page you or an extraction created wrongly, or one the user says no longer belongs') and an explicit when-not ('to fix a wrong title or body, use compass_pages_update instead'). It also routes the agent to the id source (compass_pages_list / compass_pages_search) before the call is made.

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