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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the safety profile is covered. The description adds valuable non-schema context that this can trigger changes requiring human approval, but the word 'Refresh' implies a benign re-read and the description never clarifies that the call is non-idempotent or what side effects occur beyond migration.

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?

Two sentences, zero waste, with the action front-loaded and the approval caveat immediately after. Every clause carries information the agent cannot get from the name alone.

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?

An output schema exists, so return values need not be explained, and the migrate_to_server semantics are carried by the schema. Still missing: when re-verification should be triggered, whether approval_id is mandatory for agent callers or optional, and what 'refresh' does beyond reading current status.

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 50%: approval_token and migrate_to_server are documented in the schema, while domain_id and approval_id are not. The description's mention of human approval is the only hint about approval_id's role, and it adds no meaning for domain_id; with half the parameters undocumented, this is adequate but not compensating.

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+resource: 'Refresh custom-domain DNS and SSL verification status,' which an agent can distinguish from add_domain, delete_domain, and list_domains. It stops short of naming a sibling or the condition that selects this tool, so it is clear but not fully differentiated.

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?

Usage is implied (re-check verification after DNS/SSL changes) rather than stated, and the second sentence adds a real constraint — agent-initiated domain changes need human approval by default — which hints at when approval_id is required. There is no explicit when-to-use/when-not vs. alternatives such as add_domain or delete_domain.

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