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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description goes well beyond them by asserting irreversibility, warning that dependent clients will break, disclosing the confirmation-by-repeating-the-filename safeguard, and revealing the underlying call shape 'DELETE {destroy_url}'.

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 severity warning is front-loaded in capitals, followed by the effect, the confirmation contract, and the HTTP shape -- four dense sentences with no filler or repetition.

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?

With no output schema, nothing more is needed: for a destructive, irreversible operation the description covers consequences, the required confirmation parameter, and the request format, which is everything an agent needs to invoke it correctly.

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 a baseline of 3 applies, and the description adds genuine meaning: it explains why confirm_filename must repeat the last path segment (a deliberate guard) and gives a concrete example filename, rather than merely restating the schema.

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 states a specific verb and resource ('delete one package file from its repository') and immediately disambiguates with the domain gloss '(a gem is yanked)', which cleanly separates it from siblings like promote_package or get_package.

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?

It establishes the context in which this tool applies (removing a package file whose dependents will break) and gives an explicit calling instruction -- pass destroy_url and repeat the file name as confirm_filename. It does not name an alternative tool to use instead when the goal is only to move or archive a package, so it stops short of full when/when-not guidance.

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