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

Annotations declare destructiveHint=true, so permanence is expected, but the description adds real value beyond that: it details cascading deletion (deleting a segment deletes its prompts and answers; deleting a prompt deletes its answers), confirms no restore path, and notes the side effect of freeing plan capacity. It doesn't cover auth/permission requirements, but the cascade and irreversibility disclosures are substantive.

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?

Extremely dense and front-loaded: the action and its irreversibility lead, then cascade effects, then alternatives, then cost/capacity. Every clause earns its place with 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 destructive multi-resource deletion tool with an output schema, the description covers the safety-critical facts an agent needs: which IDs are valid, that exactly one is required, irreversibility, cascade scope, and the routing alternatives. Nothing material is missing.

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 every parameter carries a description naming its source (list_brands, get_brand_settings, list_pages, etc.), so the schema does the heavy lifting. The description reinforces the 'exactly one ID' constraint, which the schema does not enforce structurally, adding modest value above the baseline.

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 (delete) and enumerates exactly the resource types covered (competitor, segment, prompt, page, report) with the 'pass exactly one of its IDs' rule. This distinguishes it clearly from revoke_report, which is named as the alternative for a narrower action.

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?

Explicitly routes the agent: use this for permanent deletion, use save_competitor/save_segment/save_prompt to pause (preserve history), and use revoke_report to kill a report's link only. The when-to-use and when-not-to-use are both stated with named alternatives.

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