Delete registry credentials

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false, idempotentHint=true), the description adds genuinely useful behavioral context: the specific downstream effect of deletion is pipeline failures at the image pull step, and the operation requires a two-step confirmation flow. These traits are not enumerable from annotations alone and materially shape how an agent should reason about calling the tool.

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?

Three short sentences, zero filler, with the core purpose front-loaded before the consequence and workflow notes. Every sentence earns its place: what it removes, what breaks afterward, and how the process works.

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?

The schema fully documents all five parameters (including conditional requirements and scope precedence), annotations cover the safety profile, and an output schema exists, so the description need not repeat structured information. The description supplies the missing operational context (impact on pipelines, two-step flow). A minor gap is that the mechanics of the two steps are not spelled out, but they are inferable from the confirm_token schema description.

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 the baseline is 3 with the schema doing the heavy lifting. The description's "Two-step" disclosure adds real value beyond the schema by explaining why confirm_token exists (it comes from a prior call to the same tool), which the schema states but does not motivate. This workflow context meaningfully enriches parameter understanding.

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 a specific verb and resource — "Removes stored credentials for a registry" — which precisely states what the tool does and differentiates it from siblings like get_registry, create_registry, and update_registry. The title, description, and annotations (destructiveHint=true) align consistently. It also adds operational detail (pull-step failures) that makes the purpose unmistakable.

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 consequence warning — "Pipelines that pull private images from it start failing at the pull step" — gives an agent clear decision-relevant context about the impact of using the tool, and "Two-step" conveys the confirmation workflow required for correct invocation. It does not explicitly name alternatives such as update_registry for credential rotation, so it stops short of full exclusion guidance.

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