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

Beyond the annotations, the description explains that this is an asynchronous setup process that requests a certificate and returns a CNAME record for the customer to add. It also clarifies that live traffic does not change until setup is complete, and it discloses the paid-plan prerequisite and root-domain DNS limitations.

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?

The description is three sentences and is front-loaded with the core action and return behavior. Each sentence earns its place by adding setup, DNS, or domain-form nuance without repetition.

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 non-destructive but asynchronous external-DNS mutation with no output schema, the description covers the important operational details: paid plan, certificate request, returned CNAME, delayed traffic cutover, and root-domain caveats. An agent has enough information to call it correctly and explain the result.

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 schema covers the domain parameter well, and the description adds useful meaning: the value is usually the www form, must not be a runlite address, and root domains have special DNS-provider constraints. It does not add explanation for siteId, leaving that to the schema, but siteId is self-explanatory in context.

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 states a specific verb and resource: it starts attaching a customer-owned domain to a site in place of the runlitehost.com address. It clearly distinguishes the tool from siblings like remove_custom_domain and check_custom_domain_status by focusing on initiating the attachment and returning the required CNAME record.

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 establishes clear context: the customer needs a paid plan, and root domains only work where the DNS provider supports CNAME-style root records, otherwise the www form should be used. It does not explicitly name check_custom_domain_status or remove_custom_domain as follow-up or alternative tools, which keeps it just short of a 5.

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