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

Goes well beyond the annotations (destructiveHint=true, idempotentHint=false): it names what is archived (Stripe product and prices), the exact refusal error and that nothing mutates in that case, the required confirmation flow with the 'never supply it on your own initiative' guardrail, the dryRun preview semantics, and the PLAN_NOT_FOUND failure mode.

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 core action, refusal behavior, and the confirmation gate; every clause carries operational weight. It is long and uses shouted emphasis (NO, REFUSED, REQUIRES CONFIRMATION), but no sentence is filler, so the length is justified for a destructive operation.

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 4-parameter destructive tool with no output schema, the description covers the mutation's side effects, the refusal branch, the two-step confirmation workflow, error codes, and a pointer to get_integration_guide for downstream app code. Nothing an agent needs to invoke this safely 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%, so the baseline is 3; the description earns one more by supplying the call-ordering semantics (dryRun first, then re-call with confirm set to the exact key) that the schema fields describe only individually. Much of the confirm/dryRun text overlaps the schema descriptions, so it is additive rather than fully novel.

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 (delete a subscription plan) and immediately scopes it: only plans NO workspace is on, with the side effect (Stripe product/prices archived). It distinguishes itself from the nearest siblings by naming archive_plan, set_tenant_plan, and delete_tenant as the alternatives in the refusal path.

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 explicit when-to-use and when-not-to-use: a plan in use is REFUSED with PLAN_IN_USE and nothing changes, and the agent is told exactly which sibling to pick for each user choice (archive_plan, set_tenant_plan, delete_tenant). It also states the required sequence (dryRun first, then confirm) and the prerequisite guide lookup.

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