build_parked_domain_records

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

Despite readOnlyHint=true, the description adds critical runtime behavior: the server independently re-checks DNS (existence, MX, SPF, DKIM selectors), returns null with rationale if mail is found, reports lookup failures as failures, and never auto-publishes ('Publishing is the human's decision'). No contradiction with annotations.

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?

Every sentence earns its place: purpose, domain exclusion, human-confirmation protocol, server re-check behavior, and publishing handoff. It is a dense but structured single paragraph, front-loaded with the main action.

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 compensates fully by explaining return shape (three records, or null with rationale, or failure), ordering constraint, and the human approval step. Combined with a complete parameter schema, an agent can invoke this tool correctly and interpret results.

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 covers 100% of parameters; the description adds nuance for confirm_no_mail beyond the schema by framing it as a human-only decision that 'unlocks the question, not the answer' and instructing to ask before setting. It doesn't discuss rua_email or domain, but the schema already fully documents those, so the baseline for high coverage is met with a slight bonus for the confirm_no_mail 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 opens with a specific verb and resource: 'Build the three-record hardening pack' for a NON-SENDING domain, naming the exact records (Null MX, hard-fail SPF, p=reject DMARC). It clearly scopes to parked/redirect/brand-defensive domains, distinguishing it from sibling tools like generate_dmarc_record or build_dmarc_upgrade.

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?

Explicit when-to-use and when-not-to-use: 'For parked, redirect and brand-defensive domains only — NEVER for a domain that sends any mail.' It also instructs the agent to ask the human owner before setting confirm_no_mail, and to relay rationale rather than retry, providing concrete decision rules.

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