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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds substantial behavioral context beyond them: irreversibility, the mandatory two-step confirmation protocol, the specific failure modes (TENANT_NOT_FOUND, TENANT_AMBIGUOUS, confirm mismatch) that all leave data intact, and that dryRun requires the same privilege as the deletion. This is exactly the extra context a destructive tool needs.

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?

The description is long but front-loaded, leading with the destructive scope and irreversibility, then the confirmation ritual, then failure modes, then dryRun, then the sibling alternative. Each sentence carries operational weight; the trailing get_integration_guide pointer is the only mildly tangential element, keeping it just under a 5.

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 mutation with no output schema, the description covers everything an agent needs: the confirmation protocol, dryRun preview semantics, all named error outcomes, the sibling alternative, and even a follow-up tool for app integration. No return-format gap because there is no output schema to describe.

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%, so baseline is 3, but the description adds real meaning: confirm must be 'the exact tenant name' (clarifying the schema's generic 'repeat the exact key'), the confirm/dryRun interaction, and that name resolution happens before confirmation. It stops short of explaining the app param, but the parameter-level workflow semantics go beyond the schema text.

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?

Opens with a specific verb+resource plus the blast radius ('Delete a tenant and everything scoped to it (its users, subscription and data)'), so the agent immediately knows the scope of destruction. It explicitly distinguishes itself from the sibling remove_user ('To remove a single person instead of the whole workspace use remove_user'), which no other sibling needs to be consulted to disambiguate.

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 sequence: resolve the tenant first, then call again with confirm set to the exact tenant name, and only after the user has explicitly agreed. It also sets a clear exclusion ('never supply the confirmation on your own initiative') and points to dryRun as the safe precursor, so the agent knows both the trigger and the guardrail.

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