delete_collection

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantial context: sub-collections are deleted cascadingly, items are only unfiled (not deleted), there is no confirmation step, and the version parameter enforces optimistic concurrency. This greatly enriches the behavioral profile beyond the annotation flags.

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 well-structured with clear line breaks, starting with the prominent 'DESTRUCTIVE' warning. Every sentence earns its place: cascade behavior, item safety, no-confirmation caution, version requirement, and idempotency explanation. It is detailed yet scannable.

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 cascading side effects, concurrency checks, and idempotency, the description covers all critical aspects: preconditions, side effects, parameter semantics, and related tools. No output schema is present, but a delete operation needs no return-value explanation, so this is complete.

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 must compensate. It thoroughly explains version (must match server's current version or delete is refused) and idempotency_key (opaque string that triggers replay behavior). The 'key' parameter is not explained, but its purpose is obvious from the tool name, so the overall compensation is strong.

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?

The description opens with 'DESTRUCTIVE -- permanently deletes the collection,' which clearly identifies the verb and resource. It distinguishes itself from sibling deletion tools by explaining the cascade to sub-collections and that items are not deleted, differentiating it from delete_item_permanently and remove_from_collection.

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?

The description explicitly advises checking list_collections first if sub-collections matter, providing a concrete prerequisite and caution. It also points to delete_item_permanently's docstring for the full idempotency_key explanation, guiding the agent to relevant alternative/reference documentation.

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