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

Adds substantial context beyond annotations: the with-domain call re-checks DNS and marks the domain verified when records resolve, and on failure returns expected_records and message that must be surfaced verbatim. It also warns that a verified domain on a never-published site still 404s and suggests offering to publish. This is consistent with readOnlyHint=false and openWorldHint=true.

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 two operating modes, then adds the important never-published caveat and sibling routing. Every sentence carries useful information and there is no redundant restatement of the title.

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 dual-mode tool with no output schema, the description explains what listing returns, what re-checking does, how failures are surfaced, and the important 404 caveat. It is complete enough for an agent to call the tool correctly in both 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?

The description thoroughly explains the domain parameter's dual semantics (omit to list, supply to re-check) and adds meaning beyond the 50%-covered schema. However, the required site_id parameter is not described at all beyond the general phrase 'attached to a site', so the description only partially compensates for the schema coverage gap.

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, then clearly distinguishes the tool's two modes: listing domains when no domain is supplied and re-checking DNS when one is. It also names the related siblings set_custom_domain and remove_custom_domain, so an agent can distinguish attach/detach/check without opening other schemas.

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?

Explicitly says when to omit domain (list every custom domain and verification state) and when to supply it (re-check DNS after records were changed at the registrar). It also routes attach and detach operations to the named sibling tools, covering both usage and alternatives.

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