build_parked_domain_records

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

Adds substantial context beyond the annotations: the server independently re-checks DNS and returns null-with-rationale on evidence of mail, lookup failures are reported as failures never as a pack, and publishing waits on human approval of each record. The readOnlyHint is consistent because the tool only generates records for review rather than publishing them.

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?

Purpose and scope are front-loaded, and each subsequent sentence carries a distinct behavioral constraint: human confirmation, server re-check, failure semantics, and the approval flow. The repeated 'sends no email' phrasing reinforces a critical safety boundary rather than padding, so the length is justified by the tool's complexity.

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?

Despite having no output schema, the description fully specifies return semantics: the verbatim three-record pack, null with rationale when DNS evidence of mail exists, and failure on lookup failure. Combined with the schema's complete parameter coverage and the explicit human-approval flow, nothing an agent needs to invoke and handle the tool correctly is missing.

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 description coverage is 100%, so all three parameters are already documented thoroughly in the input schema; the description adds no new parameter-level detail or syntax. It does reinforce confirm_no_mail's meaning ('unlocks the question, not the answer'), but that mirrors the schema, keeping this at the baseline of 3.

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 with named deliverables: 'Build the three-record hardening pack... a Null MX, a hard-fail SPF record, and a p=reject; np=reject DMARC record.' The scope ('For parked, redirect and brand-defensive domains only') clearly distinguishes it from the check/audit/validate siblings and from build_dmarc_upgrade, which serves sending domains.

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?

Gives an explicit trigger ('Use this when the user asks how to protect a domain that sends no email from being spoofed') and a hard exclusion ('NEVER for a domain that sends any mail, including transactional or one legacy system'). It also states the precondition that only the human domain owner may set confirm_no_mail, so an agent knows to ask before invoking.

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