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

Annotations already declare this is a safe, idempotent, closed-world read, so the description doesn't need to re-state that. It adds real value by disclosing the content's scope (DNS, SSL, apex caveats), which tells the agent what knowledge it will actually gain. Minor gap: it doesn't signal the form of the returned material (e.g., instructional markdown vs. structured data).

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?

A single sentence with the mandatory-use condition front-loaded and the content inventory trailing it. Every clause earns its place; no filler.

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 zero-parameter, read-only knowledge tool with no output schema, this covers purpose, trigger, and content scope. The only thing an agent might still wonder is the shape of the response, which is a small residual gap rather than a blocking one.

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 tool takes zero parameters, so there is no parameter semantics to document — the baseline for a no-arg tool applies. The description correctly implies the call is argument-free by framing it as pure retrieval of guidance.

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 names exactly what the tool returns — instructional content on connecting a user's own domain to a published page — and enumerates the covered subject areas (DNS instructions, SSL status, apex-domain caveats). It explicitly distinguishes itself from the sibling custom_domain_* action tools, which perform the operations rather than explain them.

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?

"REQUIRED before using the custom_domain_* tools" is an explicit, unambiguous when-to-use trigger with a named alternative set (the custom_domain_set/status/remove tools). Nothing is left to inference about ordering or prerequisites.

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