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

Annotations only declare the mechanical flags (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=true). The description adds substantive behavior beyond them: re-adding an existing domain returns that row rather than erroring (reinforcing idempotency with observable semantics), the account prerequisite, the exact-string fidelity rule, and the guarantee that nothing is applied to anyone's DNS without human publishing and approval.

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 its outputs, followed by the fallback path and the guarding constraints. Every sentence carries operational weight, though the final approval sentence is somewhat long and repetitive relative to the earlier fallback sentence.

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 takes on the burden of describing return values, and it does: TXT record contents, hosting provider location, guide link, and conditional apply URL. Combined with the account prerequisite and idempotent-re-add behavior, an agent has everything needed to invoke and consume the response 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?

Only one parameter exists and schema description coverage is 100%, with the schema itself carrying a detailed per-tool breakdown of what 'domain' means for add vs. check vs. get. The description adds no parameter-level syntax or format guidance 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?

States a specific verb and resource ('Add a domain to the signed-in user's DNS Doctor monitoring') and goes further by enumerating the return payload: the ownership-check TXT record, hosting provider, guide link, and possible one-click apply URL. An agent can distinguish this from siblings like check_domain_verification or get_domain_records without opening the 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 alternative and the condition that selects it: if there is no linked DNS Doctor account, or the host connect prompt fails, use start_monitoring_signup and print its link instead. It also states the approval precondition and forbids using its own DNS tools unilaterally, so both when-to-use and when-not-to-use are covered.

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?

Annotations only tell the agent this is non-read-only, non-idempotent, open-world and non-destructive; the description adds far more: the alignment signal is derived server-side and can never be asserted by a caller, scans cap at p=quarantine, np=reject is added unless already published, and a human must approve before publishing. The five null-return causes are spelled out so a null is not mistaken for an error.

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 when-to-use conditions are front-loaded in the first clause, and the record/null/np behaviors follow in a logical order with no filler sentences. It is dense and heavy with nested parenthetical enumerations, which costs a point on readability, but essentially every sentence carries load-bearing 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 full return-value burden and does so: it describes the returned record, the np=reject tag and its preservation rule, the rationale field, and every condition under which `record` is null. An agent has everything needed to call it once and interpret the result honestly.

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% — the single 'domain' parameter already documents bare names, subdomains, the prohibition on scheme/path/port, and punycode normalization. The description adds no syntax or format detail beyond 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?

The description states a specific verb and resource ('Return a validated DMARC enforcement-upgrade record for a domain') and pins down the exact user question it answers (moving DMARC past p=none, whether tightening is safe). It is functionally distinguishable from generate_dmarc_record and validate_dmarc_record through its server-derived alignment gating, but it never names those siblings or explicitly contrasts itself with them, leaving differentiation to inference.

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 ('when the user asks how to move DMARC on from p=none', 'after any report showing DMARC below enforcement') and an equally explicit rule for the opposite case: p=reject is unlocked only by aggregate-report monitoring evidence, never by a scan. The null-record paths are enumerated as legitimate answers with instructions to relay rationale rather than fabricate 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?

Goes well beyond the annotations (readOnly/idempotent/openWorld) to disclose that the server independently re-checks DNS, returns records: null with a rationale when mail evidence is found, reports lookup failures as failures rather than packs, and that publishing is the human's decision. This is rich operational context an agent needs.

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 triggering condition and dense with actionable constraints, though it is long and reiterates the 'never set confirm_no_mail on your own judgment' point across description and schema. Nearly every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema, the description explains the return shape (records pack, or records: null with a rationale, or a failure) and the publishing workflow, so an agent has everything needed to call and interpret the 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%, so domain, rua_email and confirm_no_mail are already fully documented in the schema. The description reinforces the human-ownership and DNS-recheck nuance of confirm_no_mail but largely restates what the schema provides, so a 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?

The description states a specific verb and resource — 'Build the three-record hardening pack' — and enumerates the exact contents (Null MX, hard-fail SPF, p=reject; np=reject DMARC). It clearly distinguishes itself from siblings like generate_dmarc_record and build_dmarc_upgrade by scoping to NON-SENDING domains.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use ('when the user asks how to protect a domain that sends no email') and when-not ('NEVER for a domain that sends any mail, including transactional or one legacy system'). It also names the required precondition (human confirmation of no mail) and forbids self-judgment.

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?

Despite annotations covering the safety profile (readOnlyHint=false, idempotentHint=true), the description adds material behavior: it mutates state by marking the domain verified, reports which nameservers were queried, warns that incomplete lookups are transient, returns a DMARC reporting record on success, and constrains output formatting. This goes well past what the annotations disclose.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the mutation are front-loaded, and most sentences carry operational weight (transient-error handling, exact printing, human approval). It is dense and slightly long for a one-parameter tool, with the approval/printing rules arguably belonging in a shared policy, but nothing is truly wasted.

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 it does, describing the outcome discriminator, the nameservers queried, and the DMARC reporting record on success. Combined with the mutation semantics and the human-approval constraint, an agent has everything needed to call and interpret this 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?

With 100% schema description coverage and a single parameter, the schema already documents that 'domain' must be one this account monitors. The description reinforces the same constraint ('a domain the user has added') but adds no new syntax, format, or edge-case semantics. 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 — checking whether the ownership TXT record is visible and marking the domain verified — with two distinct effects named. An agent can distinguish it from siblings like check_propagation (DNS propagation), check_record (arbitrary lookups), and get_domain_records (retrieval only) 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?

Frames the precondition clearly: this is for a domain the user has already added, and distinguishes 'not published yet' from 'wrong value' from 'lookup did not complete', with explicit guidance that an incomplete lookup is transient and not a verdict. It doesn't name a specific alternative tool to use when the precondition fails, so it falls 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 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 declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds substantial behavior beyond that: cache-free reads from authoritative nameservers plus two caching resolvers, an agreement report (in_sync), the meaning of empty values (record genuinely absent), and the meaning of max_wait_seconds as the largest remaining cached TTL — all context an agent cannot get from annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with usage triggers and dense with useful information; every sentence earns its place except for a small redundancy where 'check whether a DNS change has landed' is stated in the opening usage clause and again as the behavior opener. Appropriately long given there is no output schema to carry return-value semantics.

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 burden of return semantics and does so: it explains the agreement/in_sync outcome, empty values, and max_wait_seconds. Combined with the annotation-covered safety profile and 100% schema coverage, an agent has everything needed to select and 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 description coverage is 100%, so the enum values, the derived query names for dmarc/spf, and the host-applicability restriction are already documented in the schema. The description restates that material ('pass the kind, not a query name', host honored for txt/cname/a/aaaa only) rather than adding syntax or edge cases 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 (reads a DNS record) and goes further by naming exactly where it reads from: the domain's own nameservers plus two public resolvers. It also draws the boundary against the check_propagation sibling by warning that the tool must never be described as propagation or worldwide coverage, so an agent can distinguish the two 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 explicit triggers — user asks whether a change landed, wants a lookup, wants to verify a freshly published record, or any answer that needs the live value. Combined with the exclusion of propagation-style framing, this gives clear when-to-use and when-not-to-use guidance, with the alternative tool effectively named by contrast.

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 declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior, so the safety profile is covered. The description adds substantial context beyond annotations: it enumerates return fields (record_valid, findings, has_pass_all, multiple_all, terms, lookup counts, offending_mechanisms), notes recursive include resolution for domain, and explains the diagnose-only design decision to never return a fix record because removal can de-authorize real senders.

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 triggers and purpose, and every sentence carries information. The return-field enumeration is long but necessary because there is no output schema; overall it is dense rather than bloated, though slightly more verbose 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?

Given no output schema, the description adequately explains the meaningful return fields and their implications. It also covers usage triggers, parameter exclusivity, recursive resolution, and the diagnose-only design, leaving no critical gap for an agent to call and interpret the tool 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 both parameters fully, including the exact-one-of rule. The description reinforces the same semantics (recursive includes for domain, own terms only for record) but adds no new syntax or format details beyond what the schema provides.

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 — 'Validate an SPF record and count what it costs' — and explicitly distinguishes itself from siblings: 'This is the SPF validator — there is no separate one.' An agent can identify its role without opening the 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?

It gives explicit trigger conditions ('when the user asks about SPF too many lookups, the 10-lookup limit, an SPF PermError, or whether an SPF record is valid'), states the parameter exclusivity rule, and clarifies it is the only validator. The when-to-use guidance 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 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 declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description nonetheless adds real context beyond it — the API-token requirement, the fact that 'dashboard_only' rows never appear in the digest mail, and the reason acking is deliberately absent. It stops short of stating rate limits or retention windows, which keeps it off a 5.

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 read itself, and every sentence is substantive. It is long and repeats the pagination-skip warning in slightly different words, so it is dense rather than perfectly tight, but the length is justified by the operational hazards it warns about.

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, so the description carries the return-shape burden and does it: it enumerates the row fields (id, domain, type, check, summary, detail map, created_at, email_sent_at, acknowledged_at, delivery_class) and names next_before as the pagination signal. An agent has everything needed to call and consume 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 coverage is 100%, so the baseline is 3 and each parameter is already documented. The description adds the cross-parameter discipline the schema only implies: `since` is an inclusive floor so rows repeat and must be de-duplicated on id, and `before`/`limit` must be exhausted before the watermark advances.

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') and scopes it to the caller's account. No sibling tool covers alert logs, and the trigger ('what changed on a monitored domain, or what the monitoring has flagged') makes the boundary against get_report/get_readiness 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 an explicit when-to-use trigger tied to a signed-in operator, plus a clear when-not-to-act direction: no ack and no delete, because acknowledging is the human's triage. It also prescribes the correct call sequence (page down before advancing `since`) rather than leaving it 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is partly covered — but the description adds material context beyond that: it issues nothing, nothing is applied to DNS, a human publishes, and records must be printed verbatim without rewriting. Those are real behavioral constraints an agent could not infer from annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the read scope, then the routing rule, then the safety constraint. Slightly long and mildly redundant ('Read-only: it issues nothing' overlaps with 'Nothing here is applied to anyone's DNS'), but each sentence carries actionable content rather than 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 still specifies what comes back (ownership check, reporting record, observed-published flag) and how to handle the empty case. Combined with the verbatim-printing instruction, an agent has everything needed to call and use this tool 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% and the single 'domain' parameter is already fully documented in the schema, including the not-found/ownership-disclosure behavior. The description adds no syntax, format, or semantics beyond what the schema provides, 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 ('Read the records a domain the user monitors still needs') and enumerates exactly which records are returned: the ownership check while unverified, and the DMARC reporting record plus observed-published status once verified. This distinguishes it from check_domain_verification, which issues records rather than reading 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 explicit routing: use check_domain_verification (once) when a verified domain has no reporting record yet. It also states the operational constraint that a human publishes every record and that approval must be obtained before calling any DNS tool, which is exactly the when/when-not guidance an agent needs.

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 read-only/idempotent, but the description adds substantial behavior the annotations cannot: the full status vocabulary, that temperror is not a failure and is never scored, what the received payload contains, and strict handling rules for result.dmarc.fix and ai_assessment.

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 status semantics, and every sentence carries operational weight (status meanings, temperror caveat, verbatim-presentation rules). It runs long, but there is little filler to cut.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by enumerating what received returns (SPF, DKIM, DMARC, score, advice) and how to present it. An agent has everything needed to call and interpret 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?

Schema coverage is 100% and the single test_id parameter is fully documented in the schema itself (including that it is not the test address and the 24-hour retention). The description adds no parameter-level detail beyond the schema, 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 (retrieve the result of an email deliverability test) and anchors itself to the sibling start_email_test, so an agent can distinguish it from list_email_tests 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 call it (after start_email_test, once the user says the email was sent) and what to do on each branch, e.g. ask the user to send and call again when status is pending. Names the predecessor tool and the trigger condition.

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 cover the safety profile (readOnly, idempotent, non-destructive), but the description adds substantial behavioral context beyond them: API token requirement, the meaning of a null next_record, the record_withheld/withheld_reason branch, verbatim relay of returned records, and required human approval before publication.

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 the core behavior, and the operational guidance is genuinely load-bearing. It is slightly repetitive, restating the 'never compose a record' instruction for both the null and withheld cases, which could be consolidated.

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 full burden of explaining return values, and it does: readiness verdict, blockers, the evidence window, next_record (null while blocked), and record_withheld with withheld_reason. An agent has everything needed to call and interpret this 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 already fully documented in the schema, including the verified-monitored-domain constraint and the not-found refusal. The description restates that scoping ('ONE domain the caller's account monitors') but adds no 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: read the DMARC enforcement-readiness verdict for ONE monitored domain, computed from its aggregate RUA report window. It also distinguishes itself from the sibling scan_domain by explaining that a scan shows current policy while only this evidence window can say whether tightening would start rejecting 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 triggering condition ('when a signed-in operator asks whether a monitored domain is ready for the next DMARC step') and explicit sequencing ('use this before proposing enforcement'), plus a named alternative (scan_domain) with the reason to prefer this tool over it. 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?

Annotations declare idempotent=true and readOnlyHint=false, but the description supplies the behavior those hints only imply: it reads a cached report and scans at most once if none exists, which explains the non-read-only hint. It also discloses the fields returned and the presence of `scanned_at` so the agent can judge staleness itself — context not available in annotations or schema.

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 routing rule and the seven-check return enumeration is compact and useful. It loses a point for redundancy: the same scan_domain preference is stated at both the opening and the closing sentence, and 'the cheap first look'/'the cheap read'/'right default for a first look' restate one idea three times.

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 fully: the seven checks, their per-check anatomy (status, observed record, optional fix_record), and the scanned_at timestamp. Combined with the annotations and complete parameter coverage, an agent has everything needed to call and interpret this 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?

Only one parameter and schema description coverage is 100% — the schema already documents accepted input forms (bare names, subdomains, no scheme/path/port, punycode normalization). The description adds no extra parameter meaning, 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 ('Return the stored report for a domain') and immediately distinguishes itself from the sibling scan_domain, which is named explicitly. An agent can tell the two apart 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 explicit routing rule in both directions: use this when a recent report is enough ('the cheap first look'), use scan_domain when state must be re-read now, with a concrete example (after a DNS change). Nothing about when-to-use 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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), yet the description still adds non-structured behavior: the required monitoring:read token scope, the newest-first ordering guarantee, and the instruction to render report_url as a clickable link. The auth requirement in particular is behavioral context 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?

Front-loaded with the usage trigger and the auth prerequisite, then the return shape, so the most decision-relevant content comes first. The mid-sentence enumeration of eight return fields makes it dense, but with no output schema that detail is load-bearing rather than 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, so the description carries the return-value burden itself and does so by naming each field (test_id, status, created_at, received_at, from_domain, score/out_of, dmarc_result, report_url). Together with the trigger condition, auth scope, ordering, and follow-up routing, an agent has everything needed to call and use this 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%, so both parameters (limit, domain) are already documented including the default and the 1..50 bound. The description's "optionally only those whose From names one organization" restates the domain filter without adding format or edge-case detail beyond the schema's own example.com note.

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 (list email tests) and scopes it to the account's own past tests, newest first. It explicitly distinguishes itself from the sibling get_email_test, which it directs the agent to for a single test's full result.

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?

"Use this when a signed-in user asks about email tests they ran before, or how a sender's earlier tests scored" gives a concrete trigger, and "call get_email_test with a test_id for the full result" names the alternative and the condition that selects it.

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?

Annotations are terse (readOnlyHint=false, idempotentHint=false, openWorldHint=true) and the description adds the crucial context behind them: cache-first explanations, a ~1 minute dedup window, and the warning that scanned_at may predate a DNS edit so verification must wait for the window. It also discloses the status vocabulary and that fix_record is generated only where one exists. This is behavior beyond what structured fields 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 usage trigger and the returned checks before the cache caveat, and nearly every clause carries information. It is, however, one dense run-on paragraph where the trigger list and the cache/dedup caveat could be split for faster scanning.

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 contents (per-check status, observed record, fix_record), the caching/dedup behavior, and the verification caveat. An agent has everything needed to call it and interpret an unchanged report 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?

The single 'domain' parameter is documented at 100% schema coverage, including bare names, subdomains, punycode normalization and disallowed scheme/path/port. The description adds no parameter-level detail beyond 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 ('force a fresh scan') and resource ('domain'), then enumerates the exact seven checks returned. It explicitly distinguishes itself from the sibling get_report, 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 (check, audit, diagnose, troubleshoot SPF/DKIM/DMARC/MX/blacklist/expiry, or fix what a scan found) and closes with an explicit alternative: 'Use this when you need current state; use get_report when a recent cached answer will do.' When-to-use and when-to-use-something-else are both stated.

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 the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds substantial context beyond that: a single-use address valid about an hour for one message, a returned test_id, that every call mints a new address, and that calls count against a daily limit reported in the response.

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 when-to-use trigger, then the return payload, then the required next step. Despite covering several facts, every sentence carries actionable information and none is 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?

With no output schema, the description fully carries the burden: it explains what is returned (single-use address plus test_id), the validity window, the user-facing instruction, the follow-up tool, and the rate limit. An agent can complete the workflow without guessing.

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 tool takes zero parameters and schema coverage is 100%, so the baseline is 4. The description correctly adds no parameter detail because none exists; there is nothing further for it to clarify.

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 (start an email authentication test) and immediately scopes it to the real-world scenarios it serves: SPF/DKIM/DMARC alignment, spam diagnosis, DKIM proofing. It is cleanly distinguishable from the sibling get_email_test, which it explicitly routes to as the follow-up step.

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 triggering conditions ('when the user wants to know how a real email from them actually authenticates...') and names the alternative path (call get_email_test with the test_id afterwards). It also surfaces the daily-limit constraint that governs whether a call is appropriate.

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?

Beyond the annotations (readOnly, idempotent, non-destructive, closed-world), the description adds real workflow context: nothing is created, no email is sent, the domain is entered by the user on the dashboard after sign-in, and monitoring only starts after DNS ownership proof. That is behavioral detail an agent could not infer from the structured fields.

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?

Usage triggers are front-loaded, then the return values, then the invariant behavior, then the display instruction. Every sentence carries distinct, useful information with no repetition or 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?

With no output schema, the description correctly names the return fields (signup_url, message), and with annotations covering the safety profile and a fully documented single param, nothing an agent needs to call this 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?

There is a single parameter with 100% schema description coverage, and the schema already explains the domain format (bare registrable names, subdomains, no scheme/path/port, punycode normalization). The description adds no meaning about the parameter, 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 outcome: it returns signup_url (a dnsdoctor.dev page) plus a short message. It also pre-empts confusion with a create tool by declaring 'this call creates nothing and sends no email', which implicitly separates it from the add_monitored_domain sibling, though that sibling is never named explicitly.

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 strong explicit when-to-use list: ongoing DMARC monitoring, RUA report monitoring, new-sender monitoring, email-authentication alerts, and ongoing DNS monitoring of an owned domain. It also gives a follow-up instruction to show the link with the message, but gives no explicit when-not or named alternative (e.g. add_monitored_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?

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.