Check Domain Verification

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

Goes well past the annotations: it discloses the three distinguishable outcomes (not published, published with the wrong value, lookup did not complete), flags the incomplete-lookup case as TRANSIENT and never a verdict, and notes the success payload carries the DMARC reporting record. It also states the human-approval and exact-printing constraints, which cannot be inferred from readOnlyHint=false/idempotentHint=true. No contradiction with annotations — marking a domain verified is a state write, consistent with readOnlyHint=false, while 'nothing is applied to anyone's DNS' correctly describes the external world.

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?

Front-loaded correctly: the scoping rule and the alternative come first, and the return-value guidance follows. It is on the long side for a one-parameter tool — the 'a human publishes every record / get their approval before using any DNS tool of your own' clause is somewhat verbose and only loosely coupled to this read-and-mark operation.

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?

There is no output schema, and the description compensates fully by describing the outcome discrimination, the nameservers field, the DMARC reporting record on success, and the guidance.note relay obligation. An agent has everything needed to call it and to interpret or refuse to over-interpret 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?

Schema coverage is 100% and the single `domain` parameter is already well documented, including the not-found/ownership-disclosure behavior, so the baseline is 3. The description reinforces the precondition ('a domain the user already added to their DNS Doctor account') but adds no format, edge-case, or syntax detail beyond the schema.

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?

Uses a specific verb+resource ('check whether the ownership TXT record for a domain ... is visible yet, and mark it verified') and immediately scopes it to DNS Doctor's own ownership challenge. It explicitly names the sibling tools it is not (check_record, add_monitored_domain), so an agent can separate it from the many other record-checking tools without opening any schema.

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?

Opens with an explicit exclusivity clause ('Use this only for DNS Doctor's own ownership TXT challenge') and gives the counter-case with the exact alternative: a TXT record another service asked for (Google Workspace, Microsoft 365, Shopify, any site verification) routes to check_record. The precondition (domain already added via add_monitored_domain) is stated up front.

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