delete_dns_credential

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds genuine extra context: the downstream impact on domain verification and the concrete auth prerequisites (PROOF_API_KEY + server restart, or start_login session). It doesn't state reversibility or error behavior, but it goes meaningfully beyond the annotations and does not contradict them.

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 core action and its consequence are front-loaded in the first two sentences. The ACCESS block is somewhat verbose and reads as boilerplate, but it is genuinely actionable for an unauthenticated caller.

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 single-parameter destructive tool with annotations covering the safety profile and no output schema, the description is nearly complete: it covers the action, its consequence, and authentication. Minor gap is the absence of any note on reversibility or failure modes.

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?

Only one parameter (id) with 100% schema description coverage ('DNS credential ID to delete'), so the schema carries the semantic load. The description adds no format or sourcing detail for the id, making the baseline 3 appropriate.

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?

Specific verb (delete) plus resource (stored DNS provider credential), clearly distinguishable from siblings like create_dns_credential and list_dns_credentials. The added consequence sentence ('Domains using this credential will need new credentials for automated verification') further sharpens what this tool actually does.

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 gives a clear decision-relevant consequence for deleting (downstream domains lose automated verification), which helps an agent judge whether to call it. It does not, however, explicitly point to alternatives such as revoking or re-creating credentials via create_dns_credential, 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.