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

Annotations provide readOnlyHint:false and destructiveHint:false, but the description adds crucial behavioral detail beyond those flags: it returns DNS records that the user must create externally, and the domain only goes live after those records are in place and a certificate is issued (usually within minutes). This non-immediate effect and external dependency are not inferable from the schema or annotations, and are valuable for the agent.

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, each earning its place: first states the action with constraints, second describes the return value, third explains the follow-up and timing. It is front-loaded with the core purpose and contains no filler, fluff, or redundant restating of the tool name.

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?

With no output schema, the description correctly explains that the return value is the DNS records to create. It also covers the operational flow (records → certificate → domain serving) and suggests check_domain for monitoring. For a tool with two simple parameters and no nested structures, this is nearly complete; it lacks error-case handling or idempotency notes, but those are not essential given the simple inputs.

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% and both parameters (site, domain) have clear descriptions. The tool description does not add parameter-specific information beyond reinforcing that the domain must be already owned, which is more a usage precondition than a parameter semantic. Per the calibration rule, baseline 3 is appropriate when the schema carries the parameter documentation.

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 action ('Connect a domain the person already owns') and resource ('one of their sites'), with a clear qualifier (Pro plan). It is distinct from siblings like remove_domain, list_domains, and check_domain, which are separate operations. An agent can immediately tell this is the add/connect tool.

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?

The description gives a clear use condition: the domain must already be owned and the site must be Pro plan. It also explicitly points to check_domain for following up, which guides the agent on the next step. It does not enumerate all alternatives, but the mention of check_domain and the implied contrast with remove_domain provide enough orientation.

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