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

Goes well beyond the annotations: discloses that the old address stops working immediately with no redirect and that distributed links/QR codes break, plus the 3-per-month rate limit, the rate_limited failure mode, and the deploy:write / owner-admin auth requirement. Note a mild tension with destructiveHint=false given the irreversible breakage, but the description is not contradictory — no data is destroyed — and it supplies the risk context the annotation omits.

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?

Front-loads the core action and its consequences, then rate limits, then the confirmation workflow, then alternatives — a sensible order. It is long, and the bracketed generic block ("This tool changes data or sends notifications") is boilerplate that only loosely fits a subdomain rename.

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 3-required-parameter mutation with no output schema, the description covers impact, reversibility, preconditions, rate limits, consent, and the unpublished-site alternative. Nothing an agent needs to call it safely is missing.

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 coverage is 100%, so the baseline is 3. The description adds real meaning on top: confirm is a consent gate tied to a specific user-confirmation workflow, and subdomain only applies to already-published sites. That workflow context is not in 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?

States a specific verb and resource: "Change the site's subdomain on the hosting domain," and immediately scopes it to the hosting domain rather than a custom one. It also distinguishes itself from publish_draft's subdomain parameter and the CLI equivalent, so an agent can route correctly among siblings.

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?

Gives explicit when-to-use rules: only when the user explicitly asks, tell them the old and new address, get an explicit yes, then pass confirm: true. It also covers the negative case (unpublished site has no address yet) and points to the right alternative — publish_draft's subdomain on the remote connector, or the CLI command.

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