Replace Automatic SSL domain

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

Annotations already declare destructive=true, idempotent=true and openWorld=true, so the safety profile is covered. The description adds value beyond them: the required certificates:manage permission, the mandatory human-approved acknowledgement precondition, and explicit retry-key semantics for ambiguous outcomes. It does not describe the effect on the previously assigned domain or the response shape.

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?

Four sentences, front-loaded with the purpose, then descending into preconditions, approval, and retry handling. Every sentence carries a distinct instruction, though the approval and retry clauses could be tightened.

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, no-output-schema mutation this covers the essentials an agent needs: permission scope, eligibility precondition, approval requirement, and idempotent retry behavior. The main remaining gap is what happens to the replaced domain and confirming the replacement type options, but the description points the agent at list_automatic_ssl_actions for that.

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 60%; the three documented fields (idempotencyKey, certificate_subscription_id, acknowledge_automatic_ssl_action) are already explained in the schema. The description adds intent for the undocumented domain_id (verify the exact ID via list_automatic_ssl_actions) but says nothing substantive about new_domain beyond the requirement that it be an eligible purchased DNS name. Baseline 3 for partial coverage with marginal added meaning.

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 gives a specific verb and resource ("Replace one eligible purchased DNS name") plus the constrained context ("during its Automatic SSL correction window"), so an agent can tell it apart from generic DNS edits. It stops short of naming the obvious sibling alternative (remove_automatic_ssl_domain) or contrasting the two, so it does not reach a 5.

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 prescribes a concrete workflow before invocation: read the subscription, call list_automatic_ssl_actions to confirm the exact domain ID and allowed replacement type, then obtain explicit approval. It also gives recovery guidance (refresh and read state rather than minting a new key on an ambiguous outcome), though it never states an explicit when-not-to-use or names an alternative tool.

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