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

Annotations declare non-read-only, open-world, idempotent, non-destructive; the description adds substantial context beyond them: re-adding returns the existing row rather than erroring, nothing is applied to DNS, a human must publish records, and exact record strings must be relayed verbatim. That is meaningful behavioral and safety guidance the annotations do not convey.

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 with the core action and return payload, then safety rules. Dense but every clause carries real instruction (approval, verbatim printing, guidance.note relay). Slightly heavy with em-dashes and parentheticals, but no filler.

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?

No output schema exists, yet the description covers the return payload (TXT record, host, guide link, apply URL, guidance.note), the fallback path, and the human-in-the-loop safety requirement. Nothing essential for correct invocation 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?

Only one parameter and schema description coverage is 100%, so the schema already explains the domain argument thoroughly. The description adds no additional detail about the domain param (format, registrability, error behavior is left to the schema). Baseline 3 applies.

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+resource ('Add a domain to the signed-in user's DNS Doctor monitoring') and enumerates exactly what comes back: the ownership TXT record, hosting provider, guide link, and optional one-click apply URL. This is clearly distinguishable from siblings like start_monitoring_signup or list_my_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?

Explicit routing: 'until the human has one, or if the host's connect prompt fails, use start_monitoring_signup and print its link instead.' It also states the approval precondition before using any DNS tool and the re-adding behavior. When-to-use, when-not-to-use, and the alternative are all named.

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

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

Annotations already cover the safety profile (readOnly, idempotent, open-world, non-destructive), yet the description adds substantial context: enumerated finding types, the unverified-vs-available rule, the registry_confirmed caveat, and the explicit warning that findings are risk analysis and that no fix record exists. This is exactly the beyond-annotation disclosure the dimension rewards.

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 usage trigger and the tool's action are front-loaded, and the dense middle section (finding types, safety caveats) earns its space. It is nonetheless long, with the registry_confirmed / unverified guidance restated in slightly different words, which costs a point against the tightest possible phrasing.

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, so the description carries the full burden of describing return values, and it does so thoroughly: the tree, per-node lookup attribution, total IPv4 count, and each named finding type. Nothing an agent needs to interpret or safely relay results 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% for the single 'domain' parameter, so the schema already documents format, subdomain handling, and punycode normalization. The description adds no parameter-level detail beyond that, making the baseline 3 correct.

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: 'Audit a domain's SPF supply chain: walks every include and redirect it delegates to, and reports who can transitively send as it.' It enumerates exactly what is produced (resolved tree, per-node attribution, IPv4 count, typed findings), which is far beyond a name restatement.

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 opens with the trigger condition ('when the user asks who can send email as their domain through SPF includes, or wants an SPF supply-chain audit') and explicitly routes the alternative case to a named sibling: 'Use count_spf_lookups instead when the question is only the 10-lookup limit.'

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

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

With annotations only declaring safety flags, the description carries real behavioral weight: the alignment signal is derived server-side and cannot be asserted by the caller, np=reject is injected unless an np tag already exists, a null record is a legitimate answer with enumerated causes, and the record must be presented verbatim pending human approval. None of that is recoverable from readOnlyHint/destructiveHint/openWorldHint.

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?

It is correctly front-loaded — the triggering situations come first, then the return contract, then the null-case rules. The content mostly earns its place, though the long parenthetical null-case enumeration and semicolon-chained clauses make it dense and harder to scan than a short bulleted breakdown would be.

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 one-parameter tool with no output schema, the definition covers the decision logic, the np-tag behavior, and how to treat a null record. The only real gap is that a returned record's shape is never sketched (only `rationale` is named), leaving the agent reliant on 'present verbatim' to handle it correctly.

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%, so the single `domain` parameter is already fully documented in the schema (bare registrable names, subdomains, punycode normalization). The description adds only the phrase 'for a domain' and no extra syntax or constraint detail; baseline 3 applies when the schema does the work.

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 gives a specific verb and resource — 'Return a validated DMARC enforcement-upgrade record for a domain' — and immediately bounds what such a record can be (scan justifies at most p=quarantine; p=reject requires aggregate-report monitoring evidence). That framing separates it from a generic record builder or a raw domain scan without the agent needing the sibling schemas.

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 opens with explicit triggers ('when the user asks how to move DMARC on from p=none, whether it is safe to tighten DMARC, or what the next DMARC policy step is') and adds a second condition ('after any report showing DMARC below enforcement'). It also enumerates the when-not cases via the null-record list and warns 'never compose a record to fill the gap,' which is a usable exclusion rule rather than inference.

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

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

Adds substantial behavior beyond the annotations: the server independently re-checks DNS (existence, MX, SPF, DKIM selectors), returns records: null with a rationale on evidence of mail, reports lookup failure as failure rather than an empty pack, and expects the agent to relay rather than retry. This is consistent with readOnlyHint=true — the tool only builds records and leaves publishing to the human.

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 with the trigger and the output artifact before the safety warnings, and every clause carries weight for a gated, easy-to-misuse tool. It runs long and repeats the "never set the flag on your own judgment" instruction already present in the schema, costing it the top score.

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 still covers the return shape (the three records in order, or null with a rationale, or a reported failure) and the terminal workflow (present verbatim, human approves each). Nothing needed to call it safely 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 coverage is 100%, so the baseline is 3; the description goes modestly further by framing confirm_no_mail as "unlocks the question, not the answer" and clarifying that a call without it is always refused, which explains the parameter's gate role rather than restating its type. It also reinforces the bare-domain format for the domain parameter, though much of the confirm_no_mail wording overlaps the schema text.

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 concrete verb and artifact — "Build the three-record hardening pack" — and names the exact records produced (Null MX, hard-fail SPF, p=reject DMARC). It also scopes the resource precisely: NON-SENDING parked/redirect/brand-defensive domains, which cleanly separates it from generate_dmarc_record and 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?

Gives an explicit trigger (user asks how to protect a domain that sends no email), an explicit exclusion ("NEVER for a domain that sends any mail, including transactional or one legacy system"), and a required pre-call step (ask the owner, then set confirm_no_mail). It even warns against the tempting wrong path — inferring no-mail from a quiet scan.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces rather than repeats them ('Observation only: nothing is published'). It adds substantial non-schema context: the DMARC enforcement gate, what trust_verified true/false/null mean, that revocation is not checked, that mailboxes is eligibility not a promise, and that Outlook does not support BIMI. The only gap is return shape detail, which is largely covered anyway.

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 with the trigger scenario and every sentence carries operational information, but the body is one very dense paragraph mixing setup checks, certificate semantics, mailbox eligibility, and generated-record rules; splitting it would improve scanability for an agent.

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 thoroughly: it explains dmarc_sources, the default._bimi record, SVG Tiny PS logo validation, certificate trust states, mailbox eligibility, generated.record/null behavior, status unknown, and next_step. Nothing needed to call or interpret the tool 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 coverage is 100%, so the baseline is 3; the description goes further by tying logo_url to a downstream consequence (generated.record becomes the exact record to publish at generated.host, present verbatim) and noting certificate_url is only used together with logo_url, which the schema states but the description reinforces with output implications.

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?

Names a specific verb (a live read) and resource (one host's BIMI setup) and leads with the user intents that select it (logo in Gmail/Yahoo/Apple Mail, whether setup works, why logo is missing). No sibling tool covers BIMI, and the description makes that boundary obvious.

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 explicit trigger conditions (user asking about logo visibility in inboxes), states how to switch modes (pass logo_url/certificate_url to check a candidate logo; omit to check what is published), and includes prohibitions: never compose a BIMI record yourself, and status unknown means retry rather than a broken setup.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds genuinely useful context beyond them: it returns the verdict, its explanation, and the published key record, and explains that no fix record is returned because the key is generated by the sending platform.

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?

Three front-loaded sentences with zero waste: usage triggers first, then scope, then return behavior. Every sentence carries distinct information — trigger, one-selector constraint, and the no-fix rationale.

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 2-parameter read-only tool with no output schema, the description covers what it does, when to use it, what it returns, and why it deliberately omits a fix. An agent has everything needed to call it correctly.

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%, so both parameters are already documented with examples (google, selector1, dotted form) in the schema itself. The description restates selector examples but adds no syntax or format meaning beyond the schema — baseline 3 is appropriate.

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 precise verb (Check) and resource (ONE specific DKIM selector on a domain), and explicitly contrasts with the sibling full scan whose common-selector sweep may miss the exact selector. An agent can tell it apart from scan_domain without opening either 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?

Front-loads concrete triggering conditions — whether DKIM is set up for a sending platform, whether a specific selector exists, or why DKIM fails — and names the alternative (full scan) plus the condition selecting this tool. Nothing is left to inference.

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

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.

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

Annotations already establish readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: the tool returns facts, never a verdict; maliciousness must never be asserted; unresolvable checks count as unknown, not free; 'complete' is false while any name is unknown; unregistered names are never listed; and same_infra signals defensive registration. That is exactly the kind of semantic color annotations cannot carry.

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?

It is dense but front-loaded: the usage trigger leads, then the DNS-only scope, then return semantics, then the never-a-verdict caveat. Every sentence carries information, though the run-on middle section could be tightened slightly.

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, so the description must carry the return contract — and it does: resolving vs mail-accepting counts, up to ten resolving names with variant kind, mail acceptance, and same_infra meaning. It also covers the failure mode (unknown vs free, complete flag). Nothing an agent needs to interpret results 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% and there is only one parameter, whose schema text already explains the example.com format, registrable names vs subdomains, disallowed scheme/path/port, and punycode normalization. The description adds no additional parameter semantics, so the baseline of 3 applies.

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 checks the closest DNS variants of a user's domain for lookalike/typosquat/impersonation purposes — and scopes it as 'DNS-only'. However, the sibling get_lookalikes is never named or differentiated, so an agent cannot tell from the description alone why it should pick this over get_lookalikes rather than just invoking either.

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 opens with an explicit trigger ('Use this when the user asks about lookalike, look-alike, typosquat or impersonation domains... or whether someone has registered a name close to theirs') and routes the recurring-check case to a named alternative, start_monitoring_signup. Both the when and the off-ramp are stated rather than inferred.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds substantial behavior the annotations cannot: 'observation only,' an unanswered cell is 'unavailable' and NOT negative, and the verdict downgrades to 'unknown' below three vantage points. This tells the agent how to interpret and report results, not just that the call is safe.

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 with the when-to-use case and the scope, then parameter and interpretation notes, with no filler sentences. It is dense and long, but nearly every clause conveys actionable constraint; minor duplication of schema-covered parameter behavior keeps it from a 5.

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, so the description carries the return-value burden and does so: it describes the grid, the deterministic verdict, per-cell match/mismatch/unavailable states, and the coverage-downgrade rule. For a multi-vantage network tool this is complete enough to call and interpret correctly.

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 the schema already documents name, record_type enum, and expected_value semantics. The description largely restates these (exact name, www not stripped, expected_value toggling match/mismatch) rather than adding format or valid-value detail beyond it, so the baseline 3 applies.

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+resource (check whether a DNS change has propagated globally) and immediately gives the scope that separates it from single-vantage siblings like check_record: six vantage points across four continents plus a local resolver. An agent can distinguish this from check_record or get_domain_records 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?

Explicitly names the triggering user questions ('has my change propagated', 'why does it show in one place and not another') and the precondition (call it after the human publishes a record, since your own resolver is a single vantage point). No sibling is named as the alternative, 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.

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

Annotations already cover readOnly/idempotent safety, and the description goes well beyond them: discloses the authoritative-plus-two-resolver sampling, the full verdict vocabulary (done/wait/edit/not_registered/cant_tell), and a sampling caveat that prevents the agent from over-claiming coverage.

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 with when-to-use, then dense technical detail. Long but nearly every clause carries operational weight (kind mapping, verdict values, error semantics). Slight redundancy with the schema keeps it off a 5.

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?

No output schema, yet the description fully documents return semantics (verdict states, found_at, not_registered, cant_tell), which is exactly what an agent needs for a lookup tool whose annotations already handle safety.

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%, so the baseline is 3. The description restates kind-derived query names, host applicability, and expected_value behavior — all already documented in the schema — so it adds little beyond the structured fields.

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 (look up) and resource (DNS record) with precise scope: reads from the domain's own nameservers cache-free plus two public caching resolvers. The 'never describe this as worldwide or propagation coverage' line implicitly distinguishes it from a propagation-check sibling.

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?

Clear when-to-use triggers are given (change landed, lookup, verify just-published, or answering needs the live value). No explicit alternative tool name or when-not-to-use exclusion is stated, though the propagation caveat hints at a boundary.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds substantive interpretive context: the three verdict outcomes, the caveat that a bare PTR proves nothing because the IP operator controls its own reverse zone, and who actually owns the fix. This is exactly the kind of domain context structured fields cannot carry.

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 with the trigger condition and organized so the mechanism, the verdict vocabulary, the caveat, and the ownership note each appear once. It is dense rather than padded, though the verdict enumeration and the 'never report a bare PTR as verified' warning could be tightened slightly.

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 carries the return-value burden and does so by defining confirmed, ptr_missing, and mismatch. Combined with the usage trigger and input constraint, an agent has everything needed to call and interpret this tool without ambiguity.

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% and the single parameter is fully documented there, including the refusal of private/loopback/CGNAT ranges. The description's 'Pass a public IPv4 or IPv6 address' restates the schema rather than extending it, so the baseline 3 applies.

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 ('Check one sending IP's forward-confirmed reverse DNS (FCrDNS)') and spells out the mechanism (read PTR, resolve back, compare). It is clearly distinguishable from siblings like check_record or get_domain_records, and the opening sentence names the exact query types it serves.

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 opening sentence gives explicit trigger conditions ('when the user asks about reverse DNS, PTR records, or FCrDNS for a mail server IP') and the closing line constrains input to public addresses. It stops short of naming alternative sibling tools (e.g. check_record) for related-but-different questions, so it is clear but not fully routing.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), but the description adds what they cannot: that `domain` causes live resolution with recursive include traversal (openWorld cost), and that this tool is diagnose-only — no fix record is returned, with the reasoning that dropping a mechanism can silently de-authorize a sender. That is precisely the kind of context an agent needs before relaying output to a user.

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 with the trigger condition, then outputs, then the input branch, then the diagnose-only caveat — a sensible order. It is dense but longer than ideal; the enumerated return fields are justified only because no output schema exists, though the field list could be tightened.

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 carries the return-value burden and does so thoroughly: `record_valid`, `findings`, `has_pass_all`, `multiple_all`, `terms`, lookup count, `over_limit`/`near_limit`, `offending_mechanisms`. Combined with the recursive-vs-local input distinction and the no-fix policy, an agent has everything needed to call and interpret it.

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 parameter descriptions already state the recursion and own-terms-only semantics, so the description largely reinforces rather than extends the schema. Still, it restates the distinction compactly in-line with the usage decision ('resolves the published record and counts recursively through nested includes' vs 'parses a pasted record, its own terms only'), which helps the agent choose the right branch at a glance.

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 ('Validate an SPF record and count what it costs') and explicitly differentiates itself from the sibling set with 'This is the SPF validator — there is no separate one,' which pre-empts confusion with audit_spf_includes or validate_dmarc_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?

Opens with the exact triggering user questions ('too many lookups', the 10-lookup limit, an SPF PermError, is this record valid), and states the mutually exclusive input rule: pass EXACTLY ONE of `domain` or `record`. It also rules out the alternative tool by declaring there is no separate SPF validator.

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

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

Annotations already declare the safe read-only, idempotent, non-destructive profile, and the description adds substantial context on top: generation runs through a validating engine, the record is re-validated before return, every output carries np=reject regardless of the chosen p=, the output must be presented verbatim, and a human must approve before publishing.

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-loads the usage condition, then the mechanism, then the parameter map, then the invariant (np=reject) and the operational constraint. Every sentence carries information an agent needs; nothing is filler.

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 by describing what the generated record is (validated, np=reject-bearing) and what to do with it (present verbatim, human approval). Combined with annotations covering the safety profile, an agent has everything needed to invoke it correctly.

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%, so the baseline is 3, but the description adds real meaning: it enumerates the policy enum, names the three optional parameters, and clarifies that the np=reject tag is emitted independently of the agent-selected p= policy — a constraint the schema does not express.

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 (build a DMARC record from scratch) and scopes it with a discriminating condition: 'for a domain that has none.' That condition separates it from validate_dmarc_record and build_dmarc_upgrade without naming them.

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 ('when the user asks to create, generate or write a DMARC record for a domain that has none') and an exclusion implied by that clause, plus the instruction to never hand-compose one. It stops short of naming the sibling tools an agent should route to when the domain already has a record.

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

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

Annotations already cover readOnly/idempotent/non-destructive, but the description adds substantial context beyond them: API token requirement, newest-first ordering, the dashboard_only delivery class meaning rows are deliberately absent from digest mail, and the exact cursor contract (next_before non-null exactly when older rows remain). It stops short of stating rate limits or response envelope details, but the behavioral disclosure is well above the annotation bar.

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 with the use case, then return shape, then pagination hazards, then the read-only rationale — a sensible ordering with no true filler. It is dense and long for a single tool, and the read-only justification is somewhat editorial, but every clause carries actionable information.

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 carries the return-shape burden and does so fully: it enumerates every row field (id, domain, type, check, summary, detail map, created_at, email_sent_at, acknowledged_at, delivery_class) and names next_before as the pagination signal. Nothing an agent needs to call and iterate this 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 coverage is 100%, so the baseline is 3, but the description adds the operational meaning behind the params: 'PAGE DOWN BEFORE ADVANCING `since`', `since` as an INCLUSIVE floor implying duplicate rows to de-duplicate on id, and next_before as the sentinel for remaining older rows. That explains the failure mode of the watermark pattern rather than merely restating field types.

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 ('Read the monitoring alert log for the domains the caller's account monitors, newest first') plus the scope of what it covers, including the concrete alert types (site_down, site_partial, site_recovered, site_blocked). An agent can distinguish this from the DNS/email-testing siblings (check_record, scan_domain, list_email_tests) 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 explicit trigger conditions ('when a signed-in operator asks what changed on a monitored domain, whether its website went down, or what the monitoring has flagged'). It also gives an explicit when-NOT: no ack and no delete exist here by design, so the agent knows not to look for a mutation path and not to act on the operator's behalf.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds non-obvious behavior: nothing here is applied to DNS, a human must publish, record strings must be printed verbatim, and guidance.note should be relayed as given. It also discloses the observed-vs-published distinction in the returned data, which annotations cannot express.

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 return content is front-loaded and each sentence carries operational instruction rather than filler. It is dense with rules (verbatim printing, approval gate, note relay), which is justified but makes it longer than strictly minimal.

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 does describe the returned artifacts (record host/value, observed-publication flag, guidance.note) and the not-issuing semantics. It stops short of describing error/not-found responses or the exact response envelope, leaving a small gap for a no-output-schema tool.

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% and the single domain parameter is fully documented in the schema, including the not-found/ownership-disclosure behavior. The description adds no parameter-level syntax or format detail, so it sits at the baseline where the schema does the work.

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 names the concrete resources returned (ownership check record while unverified, DMARC reporting record plus observed-publication status once verified) with a specific verb, so the agent knows exactly what it yields. It also implicitly separates this from check_domain_verification by saying that sibling 'issues' the record while this one 'issues nothing'.

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 gives an explicit branch instruction: if a verified domain comes back with no reporting record, call check_domain_verification once. It also sets a clear boundary for downstream actions — show the human and get approval before using any DNS tool of your own.

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

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

Annotations only declare read-only/idempotent/non-destructive, and the description adds substantial behavioral context beyond that: scoring_version semantics (v2 one-decimal, 10 only when nothing deducted), the difference between accepted_pct and inbox_pct, the estimates-not-promises caveat, and the requirement to relay result.dmarc.fix verbatim or fall back to fix_withheld. It also discloses provenance constraints for ai_read/ai_assessment deductions. This is unusually rich for a read tool.

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 opening routing sentence is correctly front-loaded, but the remainder is one dense block of run-on sentences with stacked parentheticals and no structure, mixing return-value semantics, presentation rules, and scoring edge cases. Nearly every clause carries real information, yet the formatting makes it hard to scan during tool selection.

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, so the description must carry the full return-value burden, and it does: status enum, the fields inside a received result, version differences, estimate fields, and the ai_* deduction caveat. Nothing an agent needs in order to call this correctly or interpret the response 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 coverage is 100% and the test_id description already explains that it is the id from start_email_test (not the address) and that account-less tests expire in 24 hours. The prose adds no further meaning about the parameter, so the baseline 3 applies.

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 (retrieve the result of an email test) and names the sibling it pairs with: 'Use this after start_email_test.' The enumerated status values (pending | received | expired | error) make the return contract concrete enough that an agent can distinguish it from list_email_tests or get_report without opening a 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?

Gives an explicit trigger ('once the user says they sent the email') and an explicit re-invocation rule for the pending case ('ask the user to send it if they have not, then call again'). It also carves out what NOT to treat as a failure: 'A temperror is a lookup that did not complete, NOT a failure, and is never scored.'

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

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

Annotations already declare readOnly/idempotent, and the description adds substantive context beyond them: required token scope, default ordering behavior, refusal semantics for unverified or unknown domains, no ownership disclosure, dashboard-only filing, and an explicit prompt-injection warning to treat ai_assessment content as untrusted data rather than instructions.

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 with the when-to-use clause, then auth, then output shape, then the untrusted-data caveat — a sensible order. It is dense rather than padded, but the orphaned instruction about an 'included' flag is not clearly tied to anything in the schema and briefly muddies the read.

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 by enumerating the returned row shape (threat_pct, band, itemized points, site facts, optional ai_assessment) and the packet returned for a row_id. Combined with the auth, refusal and safety notes, an agent has everything needed to call and interpret this correctly.

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 the schema already documents q, sort, view, limit, domain and row_id in detail. The description restates some of that (row_id narrows to one row and adds the packet, threat ordering is default) but adds little syntax or format meaning beyond it; the passing mention of 'included' actually refers to a response field, not a parameter.

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 scope: 'Returns the account's watched lookalikes for ONE verified domain'. The framing 'the watch has found' distinguishes the persisted monitored set from an ad-hoc check (check_lookalikes) without either schema being opened.

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 explicit triggers ('Use this when a signed-in operator asks which lookalike domains ... how risky they are, or for one's takedown evidence') and states the auth prerequisite (monitoring:read). It also rules out an adjacent action ('filing a takedown is never done through agents'), though it never names check_lookalikes as the alternative for a one-off lookup.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description layers on auth requirement (API token), null-while-blocked semantics ('THAT NULL IS AN ANSWER'), human approval requirement, and the record_withheld/hosted branches. These are non-obvious behaviors an agent must relay correctly, going well beyond the annotation set.

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 with the when-to-use trigger and core verdict, then progressively details edge cases. Dense and mostly earns its length, though the hosted/record_withheld branches make it long enough that a reader must track several clauses.

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?

No output schema exists, and the description fully enumerates the return shape (ready flag, blockers, window, next_record/null, record_withheld, withheld_reason, hosted). An agent has everything needed to call and correctly relay 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 coverage is 100% and the schema already explains the verified-monitored-domain restriction and not-found behavior. The description reinforces 'ONE domain the caller's account monitors' but adds no new syntax. Baseline 3 plus marginal reinforcement puts this at 4.

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 (read/check readiness) and resource (DMARC enforcement-readiness verdict for one domain), scoped to the account's monitored domains. It distinguishes itself from scan_domain ('a scan can show a domain's current policy, but only this evidence window can say whether tightening it would start rejecting real mail').

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 trigger: 'Use this when a signed-in operator asks whether a monitored domain is ready for the next DMARC step.' Plus a when-to-use-before rule ('before proposing enforcement') and a named alternative with the differentiating condition against scan_domain.

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

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

Discloses the key hidden behavior: it reads a stored report but may scan once if none exists, which explains the readOnlyHint=false annotation. Also discloses the returned seven-check report fields, sender_requirements view, and scanned_at for staleness judgments.

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 and useful, but somewhat repetitive: 'cheap first look' / 'cheap read, and the right default for a first look' and the scan_domain preference are each stated more than once. Slight trimming would improve it.

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?

Even without an output schema, the description explains the returned report's contents (seven checks, statuses, observed records, fix_record, sender_requirements, scanned_at). Nothing essential for correct invocation 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?

The single `domain` parameter is fully documented in the schema (100% coverage), and the description adds no further syntax or format details. Baseline 3 is appropriate when the schema carries all parameter semantics.

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 (return the stored domain report) and distinguishes it from the sibling by cache semantics. An agent can tell it apart from scan_domain without opening either 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?

Explicitly says when to use this tool (recent report is enough, cheap first look) and when to use scan_domain instead (state must be re-read now, e.g., after a DNS change). The default choice is stated outright.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds material context beyond them: the monitoring:read token requirement, the account-scoped 'newest first' result ordering, and a rendering instruction to print report_url as a clickable link. It also disambiguates the scoring fields, noting scoring_version 2 is the one-decimal score.

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?

Single dense paragraph, front-loaded with the when-to-use condition before the mechanical details. Every clause carries information, though the packing of auth scope, ordering, return fields, and rendering advice into one block makes it heavier than ideal.

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, but the description enumerates every returned field (test_id, status, created_at, received_at, from_domain, score/out_of/scoring_version, dmarc_result, report_url). Combined with the auth and filtering guidance, an agent has everything needed to call and present results correctly.

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 both parameters (limit, domain) are already fully documented including the 1..50 range, default 20, and the subdomain-counts-as-organization rule. The description restates these without adding new syntax or format detail, so the baseline 3 applies.

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 (list the account's own email tests), gives ordering (newest first) and scope (optionally filtered by From domain). It explicitly contrasts with the sibling get_email_test, so an agent can distinguish list-vs-detail without opening either 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 the triggering user intent ('asks about email tests they ran before, or how a sender's earlier tests scored') and names the alternative path: 'call get_email_test with a test_id for the full result.' It also states the required auth scope, so the agent knows the precondition for calling.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavior beyond that: it requires an API token, explains the three domain states, and instructs the agent to relay next_step as given.

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 front-loaded with the usage condition and then explains return fields efficiently. The state parenthetical is slightly long, but every clause contributes useful meaning.

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 adequately explains what is returned: every monitored domain, its state with definitions, and next_step. Combined with annotations covering safety and idempotency, an agent has enough context to call and present the result correctly.

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?

There are zero parameters and schema coverage is 100%, so no parameter semantics are required. The baseline for a no-parameter tool is 4.

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 lists every domain on the caller's DNS Doctor account. It also names the returned state values and next_step, so the agent can distinguish this from sibling tools like get_domain_records or add_monitored_domain.

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 gives a clear triggering condition: use when a signed-in operator asks which domains their account monitors or what to do next on them. It does not explicitly name alternatives or exclusions, but the intended context is unambiguous.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, but the description adds substantial context beyond them: redacted:true is the post-GDPR norm not a failure, the tool is observation-only with no record composed, pendingDelete/near-expiry must be reported not acted on, and 'unknown' means the registry did not answer rather than absence. It even explains what `reason` distinguishes (rate limit, timeout, registry error, no-RDAP TLD).

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?

It is dense and long for a one-parameter read tool, but it is front-loaded with the trigger and every clause carries behavioral payload (status semantics, unknown handling, redaction norm, advisory limits). Slightly more prose than strictly necessary, but no filler sentences.

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, so the description must carry the return-value burden, and it does: it enumerates the fields returned, defines the `status` enum values, and explains the `reason` field's meaning. An agent has everything needed to call it and interpret results, including the critical 'never say a name is free unless status is exactly not_registered' guard.

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 fully documented in the schema (bare names, subdomains, no scheme/path/port, Unicode normalized to punycode). The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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 (read/look up) and resource (a domain's registration from the registry over RDAP) and enumerates exactly what it returns — registrar with IANA id, dates, EPP status codes, nameservers, DNSSEC signing, abuse contact. This is clearly distinguishable from siblings like get_domain_records or check_domain_verification, which concern DNS records and ownership proofs rather than registry registration data.

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 gives explicit trigger conditions framed as user questions (who owns it, when it expires, registrar/nameservers, is it registered, is a lock set) and labels the whole scope 'the WHOIS question', which is strong when-to-use guidance. It does not, however, name any sibling as the alternative or state when *not* to use it versus get_domain_records or check_domain_verification.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds genuinely useful behavior the annotations do not: statelessness ('Nothing is stored — the report is parsed and discarded'), accepted input formats, and a 2 MiB decoded ceiling. Malformed-input or error behavior is not covered, keeping it out of the top band.

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?

Three sentences, front-loaded with the usage trigger and then the mechanics. Mostly tight, though the format list and 2 MiB cap partly duplicate what the schema already states, which is minor redundancy rather than bloat.

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 read-only parsing tool with no output schema, the description supplies what an agent needs: the trigger, input encoding and formats, size limit, and a summary of the returned per-source alignment data. Nothing essential to correct invocation 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 the schema already documents base64 encoding, accepted formats, the size cap, and the log-only nature of filename. The description largely restates these facts rather than adding syntax or semantics beyond the schema, so baseline 3 applies.

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 (parse) and resource (DMARC aggregate RUA report), then goes further to describe the output shape: per-source aggregates covering sender, volume, and SPF/DKIM alignment share. An agent can distinguish it from unrelated siblings like check_propagation or validate_dmarc_record without opening a 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?

The opening sentence gives an explicit trigger condition (user uploads/pastes a DMARC RUA report and asks what it says), and 'Parse ONE' constrains it to a single report per call. It names no alternative or when-not condition, so it stops short of the top of the scale.

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

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

Goes well past the annotations by disclosing the dedup window (~a minute), the cache-first explanation behavior, and the operational consequence that `scanned_at` may predate a just-made DNS change, with explicit advice to wait out the window before verifying an edit — which is the real meaning behind idempotentHint=false. It also describes the report shape (status vocabulary, observed record, fixengine fix_record, sender_requirements and its pass/fail/unknown/email_test/not_visible semantics) and scopes the fix capability honestly (DMARC and DNS fixable, SPF diagnose-only).

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 with the when-to-use trigger list and ends with the decisive routing contrast against get_report, so the important parts are at the edges. It is dense and includes a long run-on opening clause plus a parenthetical aside about SPF being diagnose-only, but nearly every sentence carries operational weight; trimming would cost real information.

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 and a single parameter, the description carries the full burden and does so: it describes the returned checks, status vocabulary, fix_record presence, sender_requirements semantics, and the caveat that these are provider-published rules rather than a compliance verdict. An agent has everything needed to call it, interpret the response, and know when re-calling is required.

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%, so format, punycode normalization and subdomain handling are already covered and the baseline would be 3. The description adds a genuine behavioral constraint the schema lacks: the domain must be the user's real one, ask if unstated, and never use a placeholder. Minor missed opportunity on any per-domain limits or scoping nuance, but the value-add is real.

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 ("force a fresh scan of a domain and return its full report") and enumerates exactly what the scan covers: seven named deterministic checks, each with status values pass/warn/fail/info/temperror. It explicitly differentiates from the sibling get_report ("use get_report when a recent cached answer will do"), so an agent can route without opening either 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?

Gives an extensive trigger list (SPF, DKIM, DMARC, spam placement, MX, DNS health, blacklist, expiry) plus the fallback "whenever a conversation turns to a specific domain's email or DNS setup." It names the alternative tool and the condition that selects it, and pre-empts the two common misuse cases: ask for the real domain first, never scan a placeholder like example.com.

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

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

Goes well beyond the annotations: single-use address, ~1 hour validity, one message only, each call creates a new address, daily limit counts only arrived messages, unused addresses can coexist, and the response includes a limit field. This is unusually rich operational context for a non-idempotent, non-readOnly tool.

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 with the when-to-use clause, then the return contract, then the caller workflow. Dense but nearly every clause carries actionable detail; the daily-limit sentence is slightly packed but still useful.

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?

No output schema exists, and the description compensates fully by describing the returned single-use address, test_id, and limit, plus the required follow-up call. An agent has everything needed to invoke and continue correctly.

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?

Zero parameters, so the schema has nothing to explain and the baseline is 4. The description correctly implies no inputs are needed and instead documents the returned address/test_id/limit.

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: creates a single-use email test address so the user can see how their real email authenticates (SPF/DKIM/DMARC alignment). It clearly distinguishes itself from the read-side sibling by instructing the agent to follow up with get_email_test.

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 trigger ('Use this when the user wants to know how a real email... authenticates'), enumerates concrete scenarios (spam diagnosis, proving DKIM before tightening DMARC), and names the next step (get_email_test with the test_id). The alternative path is implied clearly by the follow-up routing.

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

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

The description adds substantial context beyond the readOnly/idempotent annotations: it states the call creates nothing, sends no email, the domain is filled in on the dashboard after sign-in, and monitoring starts only after DNS ownership proof. It also instructs the agent to show the returned signup_url as a link with the message.

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 front-loaded with usage and exclusions, and every sentence carries useful information. The first sentence is quite long and enumerates many monitoring categories, but it remains purposeful rather than redundant.

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 simple one-parameter signup-link tool with annotations covering the safety profile, the description supplies everything needed: when to use it, what it returns, that it has no side effects, and what the user must do next. No output schema is present, but return fields are explained.

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 the schema already defines the only parameter in detail. The description adds only the ownership framing ('a domain they own') and no additional syntax or format guidance 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?

The description states a specific verb and resource: get a signup URL for ongoing monitoring. It distinguishes the tool from one-off check tools by explicitly excluding 'a one-off question about whether a site is down right now.' An agent can tell what this tool does and how it differs from the check_* siblings.

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 gives clear when-to-use conditions (ongoing DMARC, RUA, new-sender, email-auth, DNS, or uptime monitoring) and an explicit when-not condition (one-off site-down question). It does not name a specific alternative sibling for the one-off case, so it stops short of full alternative routing.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, no open world), and the description adds real behavioral context beyond them: no network lookup, the shape of the findings, and the important caveat that policy upgrades are capped at p=quarantine because a pasted record carries no alignment evidence. It also instructs that returned records be presented verbatim.

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 with the trigger, then the action, then the input constraint and caveats; every sentence carries information. The upgrade/reject-policy aside is slightly long but earns its place by preventing a misuse. Minor density without waste.

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 one-param, no-output-schema validation tool with safety annotations, the description covers trigger, input form, output content (tags, findings, validity) and policy limits. Nothing an agent needs to call it 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?

Single parameter with 100% schema description coverage, so the schema already documents the 'record' argument and even the not-the-hostname nuance. The description's 'pass the record string itself' reinforces but does not extend the schema, so the baseline of 3 applies.

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+resource ('Validate a pasted DMARC record') and enumerates the outputs ('parsed tags, level'd findings, and whether it is valid'). It differentiates from DNS-based siblings by asserting 'No DNS lookup — pass the record string itself,' so an agent can tell it apart from check_record/scan_domain without opening a 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?

Explicit when-to-use trigger: 'Use this when the user pastes a DMARC record and asks whether it is valid, correct or safe.' It also clarifies the input precondition (the record string, not a hostname). It stops short of naming the validation alternatives to avoid (e.g. check_record for live DNS), so it is clear but not exhaustive.

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