dns-doctor

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

Goes well beyond the annotations: explains that re-adding an existing domain returns the row instead of erroring (concrete idempotency semantics), that nothing is written to real DNS by this tool, that a human publishes every record, and that record strings must be echoed verbatim. It also instructs relaying guidance.note for edge cases such as Automatic DMARC.

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 purpose and return shape, then constraints in priority order. It is dense but nearly every clause carries an operational rule; the long single paragraph is the only mild readability cost.

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 though an output schema exists, the description supplies the workflow context an agent actually needs: account prerequisite, fallback tool, verbatim-record rule, approval gate, and note-relay instruction. Nothing required 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?

Schema description coverage is 100% and the single `domain` parameter is thoroughly documented there, including the registrable-domain and not-found rules. The description adds no new detail about the parameter itself, 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 immediately describes the return payload (ownership-check TXT record, hosting provider, guide link, apply URL). This clearly separates it from read-only siblings like list_my_domains, get_domain_records and check_domain_verification.

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?

Names the alternative tool explicitly and the exact condition that switches to it: 'Needs a linked DNS Doctor account: 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 prerequisite (human approval) before any of the agent's own DNS tools are used.

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 safety profile (readOnly, idempotent, openWorld, non-destructive). The description adds substantial behavioral context beyond that: the exact finding taxonomy, that unverifiable domains are reported as 'unverified' and never 'available', the registry_confirmed gating rule, and the explicit constraint that findings are risk analysis rather than instructions because no SPF fix record exists. This is unusually rich disclosure 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?

Front-loaded with the usage trigger and alternative, and the finding taxonomy is compact. It is long, but most of the length is load-bearing safety guidance; there is mild redundancy where the registry_confirmed: false caution is restated, which 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?

For a single-parameter read-only audit with an output schema, the description supplies everything an agent needs: trigger conditions, finding semantics, interpretation caveats, and the sibling alternative. Return shape is covered by the output schema, so nothing essential 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?

With 1 parameter at 100% schema description coverage, the schema already documents the domain argument fully (bare names, subdomains, punycode normalization). The description adds no further parameter-level 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 (audit) and resource (a domain's SPF supply chain / includes), enumerates exactly what it walks and returns, and explicitly contrasts itself with count_spf_lookups. An agent can distinguish it from the sibling lookup/count tools 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?

Opens with an explicit trigger ('Use this when the user asks who can send email as their domain through SPF includes, or wants an SPF supply-chain or third-party sender audit') and names the alternative with its selecting condition ('Use count_spf_lookups instead when the question is only the 10-lookup limit'). When-to-use and when-not-to-use are both present.

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 generic safety profile; the description adds the substantive behavior: the alignment signal is derived server-side and cannot be asserted by the caller, np=reject is appended unless already published, and null is a legitimate answer with a full enumeration of null-producing conditions. It also warns against composing a record to fill a gap and mandates verbatim presentation plus human 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?

Usage conditions are front-loaded in the first sentence and every clause carries behavioral information — no filler. It is dense and parenthetical-heavy, running long for a single-parameter tool, which keeps it just short of 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?

An output schema exists, so return-shape explanation is not owed, yet the description still covers the one thing the schema cannot: that null is the answer rather than an error and why. For a single-parameter, evidence-gated tool this leaves nothing an agent needs unanswered.

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 parameter has 100% schema description coverage covering bare names, subdomains, rejected schemes/ports, and punycode normalization, so the schema carries the load. The description adds no domain-format detail beyond the schema, which is the expected baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — return a validated DMARC enforcement-upgrade record for a domain — and scopes it against the neighboring build/generate/validate DMARC tools by naming exactly what it produces (an upgrade record justified by evidence). An agent can tell it apart from generate_dmarc_record and validate_dmarc_record from the description alone.

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 enumerates triggering situations ('how to move DMARC on from p=none', 'whether it is safe to tighten', 'what the next policy step is', 'after any report showing DMARC below enforcement') and states the evidentiary ceiling (scan justifies quarantine at most; reject requires monitoring). This is a model of when-to-use guidance.

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, openWorld, idempotent, non-destructive) to disclose that a call without confirm_no_mail is always refused, that the server independently re-checks DNS (existence, MX, SPF, DKIM selectors), that it returns records:null with a rationale to relay, and that lookup failures are reported as failures, never as a pack. It also clarifies that publishing is left to the human, which is consistent with readOnlyHint.

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 long, but it is front-loaded with the triggering use case and each sentence carries operative content (scope limits, the flag's semantics, error handling, publication handoff). Slight density cost, but little 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?

Given a publishing-safe mutation-adjacent tool with an output schema, the description is complete: it covers scope, preconditions, the enforcement flag, server-side re-verification, refusal behavior, and the human-approval handoff. Nothing an agent needs in order 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema: it explains that the domain should be bare (e.g. example.com), that confirm_no_mail unlocks the question (not the answer), and that the server re-checks regardless - reinforcing the parameter's intent rather than merely restating it.

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: it builds a three-record hardening pack (Null MX, hard-fail SPF, p=reject DMARC) for non-sending domains. This clearly distinguishes it from siblings like generate_dmarc_record or build_dmarc_upgrade without needing to open 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 explicit when-to-use (parked, redirect, brand-defensive domains) and when-not (never a domain that sends any mail, including transactional or a single legacy system). It also names the required precondition - ask the owner before calling - and the gate that enforces 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, so the bar is lower, yet the description goes further: it discloses the DMARC enforcement gate, the exact semantics of certificate.trust_verified (true/false/null plus trust_reason, revocation unchecked), that mailboxes is eligibility and not a promise, that Outlook does not support BIMI, that status unknown means a failed lookup rather than a broken setup, and that nothing is published. This is unusually rich behavioral context.

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 user-facing triggers, then the mechanics, then the caveats in roughly priority order. It is dense rather than wasteful, but the paragraph is long and a few clauses (e.g., the mailbox eligibility list) could be tightened without losing 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?

For a read-only diagnostic with an output schema, the description covers the gaps that matter: how to interpret generated.record, generated.host, status, next_step, and certificate trust fields. An agent knows how to invoke it, when to retry, and how to relay results verbatim without inventing a BIMI record.

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 a baseline of 3 applies, but the description adds real meaning: logo_url causes the candidate logo to be checked instead of the published one and makes generated carry the record for it, and certificate_url is only meaningful together with logo_url. That cross-parameter dependency is beyond what the schema states.

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 ('A live read of one host's BIMI setup') and enumerates exactly what it inspects: the DMARC gate, the default._bimi record, the logo, and the certificate. It is unmistakably distinct from siblings like check_record or validate_dmarc_record, so an agent can route to it 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?

Opens with concrete trigger conditions ('when the user asks how to get their logo shown in Gmail... whether their setup works, or why their logo does not show') and adds a conditional mode: pass logo_url to check a candidate, omit it to check what is published. It also tells the agent what to do when generated.record is null (relay rationale, do not compose a record yourself).

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), so the bar is lower. The description still adds real context: it returns a verdict, explanation and the published key record, and explicitly notes that no fix record is returned because DKIM keys are 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?

Front-loaded with the trigger condition, then scope, then return contract in four tight sentences. Slightly dense but every sentence carries distinct information about when to call it or what comes back.

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?

An output schema exists, so return values need not be spelled out, yet the description still explains the verdict/explanation/key payload and preempts a likely follow-up question about why no fix record is offered. Nothing needed to call the tool correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: the selector is the exact one the sending platform names and is 'not guessable from the domain', with dotted forms like 's1.prod' exemplified. That clarifies why both parameters are mandatory.

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 specific DKIM selector on a domain') and scopes it precisely against the sibling scan_domain behavior by noting the common-selector sweep may miss this. An agent can distinguish it from the 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?

Gives three concrete user-intent triggers (is DKIM set up for a platform, does a selector exist, why DKIM fails) and explains when this beats a full scan. It stops short of naming the alternative tool or stating an explicit when-not condition, so it is clear but not fully routing-explicit.

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: live RDAP lookup, exact status values, registry_status and expires_at behavior, deletion states, unknown reasons, and hourly rate-limit cost per name. It also clarifies that the tool is observation-only and does not register, store, or publish anything.

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 use case and the batching rule, then proceeds through status semantics and caveats. It is dense but mostly earns its length; a few clauses could be tightened without losing safety-critical 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?

Complete for this tool's complexity: the output schema can carry return details, while the description covers the safety-critical interpretation of statuses and the operational cost of each name. No important invocation or interpretation gap is left for the agent.

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 schema already documents the names array thoroughly, including count limits and punycode normalization. The description still adds useful invocation semantics by emphasizing a single batch call and noting that each name counts against the hourly 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: checks candidate domain names for existing registrations. It is clearly distinguishable from siblings such as lookup_registration because it is scoped to bulk candidate-name selection and registration status.

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 it: while the user is choosing a domain name and wants to know which candidates are registered. It also gives hard usage rules, including batching up to 20 names in one call and never treating 'not_registered' as broadly 'available'.

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 readOnlyHint=false but destructiveHint=false and idempotentHint=true; the description reconciles this by disclosing the mutation is only an internal 'mark it verified' state change and that nothing touches the user's DNS. It also distinguishes transient lookup failures from real verdicts and mandates human approval before any DNS write. Slightly less than perfect only because it doesn't say what happens when verification flips to verified (side effects, monitoring start).

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 rule and the alternative, which is the right ordering. The tail of the paragraph (exact record printing, approval workflow, guidance.note relay) is behaviourally load-bearing but dense; a couple of clauses could be tightened without loss.

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?

An output schema exists so return shape needn't be restated, and the description still explains the outcome taxonomy and nameserver attribution an agent must interpret. Combined with the transient-vs-verdict rule and the approval guardrail, nothing needed to call and interpret 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?

Only one parameter at 100% schema coverage, so the schema already carries the 'must be an already-monitored domain' constraint. The description reinforces it in prose ('a domain the user already added to their DNS Doctor account'), adding modest emphasis rather than new syntax.

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 whether the ownership TXT record ... is visible yet, and mark it verified') and immediately scopes it to DNS Doctor's own TXT challenge, differentiating it from check_record and add_monitored_domain by name.

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 'use this only for X' rule plus a named alternative (check_record) with the exact condition that selects it (TXT record requested by Google Workspace, Microsoft 365, Shopify, or any site verification). No inference required.

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 cover the safety envelope (readOnly, idempotent, openWorld). The description goes well beyond them: up to ten resolving names returned, same_infra interpretation, unknown-vs-free semantics, complete=false while any name is unknown, unregistered names omitted, and the critical 'never a verdict / never call one malicious' constraint. This is exactly the behavioral context an agent cannot derive from 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?

Front-loads the trigger condition, then packs behavioral rules into dense, information-bearing sentences ('resolving only means the name is registered', 'unknown, never as free'). It is long, but nearly every clause prevents a concrete misuse, so little is 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?

For a read-only, output-schema-backed lookup, the description supplies everything needed to call and interpret it correctly: scope, trigger, the safety/'never a verdict' caveat, and the escalation path to start_monitoring_signup. Nothing material 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, documented at 100% schema coverage including bare names, subdomains, punycode normalization and what does not belong. The description adds only the general 'DNS-only' framing, not parameter-specific detail, so the 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+resource ('checks the closest variants of the name') and immediately scopes it as DNS-only, so an agent can distinguish it from get_lookalikes and DNS-record siblings. The opening usage clause names the exact user intents (lookalike, typosquat, impersonation) that select this tool.

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 states when to use it ('when the user asks about lookalike, look-alike, typosquat or impersonation domains') and names start_monitoring_signup as the alternative for recurring checks. It does not, however, clarify the boundary versus the similarly named get_lookalikes sibling, so the routing is not fully 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?

Beyond the readOnly/idempotent annotations, it discloses real behavioral traits: cells that fail to answer are 'unavailable' and explicitly NOT negative, the verdict downgrades to 'unknown' under three vantage points, and the caller should report vantage_reached/vantage_total rather than claim convergence. 'Observation only: no record is ever composed here' further clarifies scope beyond what the annotations 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?

The description is long but front-loads the when-to-use trigger and the core global-propagation mechanic. It is dense with edge-case semantics rather than padding, though the parameter recap overlaps the schema and the opening 'check whether a DNS change has propagated' repeats the usage sentence 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 an output schema present, the description need not explain return values, and it still covers the critical interpretive edge cases (unavailable ≠ negative, partial-coverage downgrade to unknown). For a network-dependent read tool with three parameters, nothing an agent needs in order to call and interpret 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?

Schema description coverage is 100%, so the schema already documents name, record_type enum and expected_value, including that www. is not stripped and expected_value switches cells to match/mismatch. The description largely restates this, adding only marginal reinforcement, 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 precise verb+resource (check whether a DNS change has propagated globally) and names the exact mechanism (six vantage points across four continents plus the server's own resolver). It is clearly distinguishable from single-lookup siblings like check_record because it explicitly contrasts 'GLOBAL' propagation against 'you have ONE network vantage point.'

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 whether a DNS change has propagated globally, or why a record shows in one place and not another,' plus timing guidance ('call it after the human publishes a record'). It does not name a sibling alternative such as check_record for the single-name lookup case, so it stops short of full when/when-not 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 readOnly/idempotent/openWorld/non-destructive, but the description goes well beyond them: it discloses that lookups are cache-free, enumerates the full verdict vocabulary (done/wait/edit/not_registered), explains what not_registered and cant_tell mean, and warns that two resolvers is the entire sample. This is exactly the behavioral 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 use-when trigger and information-dense throughout, with each clause carrying distinct guidance. It is on the long side and a few clauses could be tightened, but there is little genuine 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?

An output schema exists so return values need not be restated, yet the description still covers the pieces an agent must interpret: verdict semantics, not_registered, found_at, and cant_tell as a fault rather than absence. Nothing essential to calling or interpreting 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, but the description adds real meaning beyond the schema: it stresses passing `kind` rather than a query name, notes that dmarc/spf derive their own query name and must not be prefixed, and ties `expected_value` to the edit/found_at behavior.

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/look up) and resource (a DNS record), plus the mechanism that defines it: reading from the domain's own nameservers cache-free and two public resolvers. This distinguishes it clearly from siblings like check_propagation, get_domain_records, and 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?

Explicitly names when to use it (verifying a change landed, looking up a record, verifying a just-published record, or whenever the live value is needed), and adds a negative scope note that it is not worldwide propagation coverage. Alternative routing to check_again_after_seconds is implied via the 'wait' verdict.

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, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful semantics beyond that: the three verdict outcomes, the reasoning that a PTR alone proves nothing, and the operational note that only the IP's controller can fix it. It omits rate limits or lookup-timeout behavior, which is the only gap.

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 trigger sentence, then adds supporting semantics. Every clause carries real information (verdict meanings, the PTR-vs-FCrDNS distinction, who owns the fix), though the four-sentence block is denser than strictly necessary for a one-parameter read tool.

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?

An output schema exists, so return structure is covered elsewhere, and the description fills in the interpretive layer an agent needs — what each verdict means and how to communicate the result. For a single-parameter, read-only tool this is fully complete.

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 schema already documents that the IP must be public and that private/loopback/CGNAT are refused. The description's "Pass a public IPv4 or IPv6 address" largely restates that, so baseline 3 applies — adequate but not additive over 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?

States a specific verb and resource — reads the IP's PTR record, then resolves the hostname back to confirm it matches. It also names the exact domain concept (FCrDNS), which no sibling tool in the list addresses, so an agent can route here without ambiguity.

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 a clear trigger ("Use this when the user asks about reverse DNS, PTR records, or FCrDNS for a mail server IP") and warns against a common misuse (never report a bare PTR as verified). It does not name a specific sibling alternative or an explicit when-not-to-use case, so it stops 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 readOnlyHint/idempotent/destructiveHint=false, so safety is covered; the description adds genuinely new behavior: recursion through nested includes for domain mode, own-terms-only for record mode, and the deliberate diagnose-only design ('no SPF fix record is ever returned') with its rationale. Permissions/rate-limit context is absent, but not needed for a read-only validator.

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?

Trigger conditions are front-loaded and the diagnose-only constraint is placed last as a deliberate caveat. However, the middle sentence enumerates return fields (record_valid, findings, has_pass_all, multiple_all, terms, over_limit...) that the output schema already supplies, so some content is redundant rather than earning 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?

With an output schema present and 100% schema coverage, an agent has everything required to invoke this correctly; the description adds the trigger framing and mode-selection rule that schemas can't express. It is complete, though the return-field enumeration slightly duplicates the output schema.

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 are already documented in the schema, including mutual exclusivity and the 'never a domain name' warning. The description restates the same distinction (recursive include counting vs. own terms only) without adding syntax that isn't already in 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 ('Validate an SPF record and count what it costs') and explicitly positions itself against siblings with 'This is the SPF validator — there is no separate one,' which disambiguates from validate_dmarc_record, audit_spf_includes, and check_record. An agent can tell what it does 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?

Front-loads concrete trigger conditions ('too many lookups', 10-lookup limit, SPF PermError, record validity) and gives the selection rule for its two modes via 'Pass EXACTLY ONE of domain ... or record'. Usage is fully determined.

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 read-only, idempotent, non-destructive, closed-world, and the description adds substantial non-obvious behavior: generation runs through a validating engine rather than free-form composition, np=reject is appended unconditionally regardless of the chosen p=, the output is re-validated before return, and it must be presented verbatim with human approval before publishing. Nothing here contradicts the annotations — generating a text record is consistent with readOnlyHint=true.

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 sentence, followed by dense, useful detail about validation, the forced np=reject tag, and the approval workflow. Slight redundancy in re-listing the policy enum values already spelled out in the schema 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?

An output schema exists so return values need no explanation, and annotations carry the safety profile. The description covers the remaining agent-critical facts — the automatic np=reject tag, re-validation, verbatim presentation, and required human approval — leaving no meaningful gap for a 4-parameter generator.

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 enum for policy is fully documented in the schema, so the baseline is 3. The description restates the policy enum values and names the optional parameters, which is largely redundant with the schema; its genuinely additive note (the automatic np=reject tag) is a record-construction behavior rather than a parameter semantic.

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 (generate/create) and resource (DMARC record) plus a scope constraint — 'for a domain that has none' — which cleanly separates it from sibling build_dmarc_upgrade (which upgrades existing records) and validate_dmarc_record. An agent can route correctly 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?

Explicit trigger is given ('when the user asks to create, generate or write a DMARC record for a domain that has none'), and the 'has none' clause acts as an implicit exclusion from the upgrade tool. However, no sibling is named as the alternative for domains that already have a record, so the routing is left partly 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=true and destructiveHint=false, and the description consistently reinforces that with an explicit read-only decision and rationale. It adds crucial behavioral context beyond annotations: API-token requirement, inclusive `since`, de-duplication on id, pagination risk, and the meaning of `dashboard_only` rows.

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 triggering use case and then moves into operational details. It is dense and purposeful, though listing every returned column is somewhat redundant given the output schema exists, and the pagination warning is verbose even though it is important.

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 an output schema and full parameter coverage, the description supplies everything else an agent needs: auth requirement, account/domain scope, pagination safety, de-duplication guidance, read-only boundary, and the significance of dashboard-only rows. 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?

Schema description coverage is 100%, so the schema already documents parameters well. The description still adds meaningful workflow semantics beyond the schema, especially that `next_before` must be paged through before advancing `since`, that `since` is inclusive, and that rows should be de-duplicated on id.

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: read the monitoring alert log for monitored domains, newest first, including uptime incidents. It clearly distinguishes this monitoring/log tool from the DNS and email-testing siblings by scope and returned 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 explicitly names the operator questions that should trigger this tool: what changed, whether a site went down, or what monitoring flagged. It also states a clear when-not boundary by explaining there is no ack or delete here because that is the human's triage action.

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 given. The description still adds genuinely new context: nothing is applied to DNS, a human publishes, approval must be obtained, record strings must be printed verbatim, and guidance.note must be relayed as given for edge cases. That is real added value beyond the annotations, though it stops short of describing response shape or failure conditions in depth.

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 before the operational constraints. Every sentence carries a distinct rule (routing to check_domain_verification, verbatim printing, human approval, note relay) with no restatement of the name or title.

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?

Output schema exists, so return values need not be explained, and the description still flags the guidance.note field. For a one-parameter read tool with full annotation coverage, nothing an agent needs in order 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?

Schema coverage is 100% and the single domain parameter is documented in detail, including the not-found / ownership-non-disclosure behavior. The description adds no parameter-level syntax or format beyond what the schema already provides, so baseline 3 is 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?

States a specific verb (read) and precise resource (the records a monitored domain still needs), then enumerates the two record classes: the ownership check pre-verification and the DMARC reporting record post-verification plus its observed publication state. This clearly differentiates it from siblings like check_domain_verification, which it explicitly says issues the record rather than reading it.

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: if a verified domain returns with no reporting record, call check_domain_verification once because that tool issues it. It also sets the boundary against DNS-writing tools of the agent's own, requiring human approval and showing records first.

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 read-only, idempotent, non-destructive behavior, but the description adds substantial context beyond that: status meanings, scoring-version differences, temperror semantics, DMARC fix handling, SPF diagnose-only scope, and AI-derived deduction attribution. There is no contradiction with annotations, and the extra behavioral detail is unusually rich.

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 correct usage and status semantics, and nearly every sentence carries operational value. It is dense and lengthy for a single paragraph, and some returned-field enumeration overlaps with the output schema, but the length is largely justified by the tool's behavioral complexity.

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

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

Given the complex result semantics, the presence of an output schema, and the annotations, the description covers the critical gaps an agent would otherwise miss: how to interpret pending, how to treat temperror, how to relay provider estimates, and how to handle DMARC fix text. It is complete for correct invocation and interpretation.

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 that test_id is the value returned by start_email_test, not the test address, including retention and not-found behavior. The description does not add further parameter-specific detail, so the 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 clearly states the specific operation: retrieving an email test result after start_email_test. It distinguishes the polling/retrieval step from the sibling start_email_test and names the returned status values, so an agent can identify the tool's role immediately.

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 timing: use after start_email_test once the user says they sent the email. It also explains the pending loop — ask the user to send it if needed, then call again — which is precisely the kind of procedural guidance an agent needs for a polling tool.

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 readOnly/idempotent annotations, the description discloses the auth scope required, the refusal semantics for unverified or foreign domains (ownership never disclosed), that ai_assessment.summary is untrusted third-party content to be treated as data not instructions, and that filing is never performed through the tool. That is a rich behavioral profile an agent could not derive from 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 trigger and the one-domain scoping constraint, and every sentence contributes (auth scope, result shape, untrusted-content caveat, no-filing rule). It is dense and somewhat long, but no sentence is filler; only the return-field inventory is arguably redundant given the output schema.

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, six-parameter tool with an output schema and full annotation coverage, the description supplies everything an agent needs: invocation trigger, auth prerequisite, scoping limits, ordering default, row-level drill-down, refusal behavior, and the prompt-injection caution. Return values are understood not to need explanation, and the description still sketches them without bloating.

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, limits, and filters are already fully documented. The description adds only marginal parameter context — the default threat-first ordering and that row_id pulls an evidence packet plus filing targets — which largely restates the schema descriptions. Baseline 3 applies when the schema carries the 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?

The description states a specific verb and resource — returns the account's watched lookalikes for ONE verified domain — plus the ranking (highest threat % first) and the optional row-level evidence packet. The scope is unmistakable, though it never names the sibling check_lookalikes, so an agent must infer the scan-vs-watched distinction from context.

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 a signed-in operator asks which lookalike domains ... the watch has found, how risky they are, or for one's takedown evidence') and states the prerequisite token scope (monitoring:read). It also routes row-level requests to the row_id parameter, but offers no explicit when-not guidance versus check_lookalikes.

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 safe-read profile (readOnly, non-destructive, idempotent), yet the description adds substantial context beyond them: API token requirement, what happens on non-monitored domains, the meaning of a null next_record, and the two special result states (record_withheld and hosted) with their required handling. It also states the human-approval and verbatim-presentation obligations.

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 core action, and every paragraph addresses a real decision point. However, the instruction 'never compose a record' is restated three times across the null, record_withheld, and hosted cases, which is avoidable repetition in an otherwise dense description.

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 tool with an output schema and full annotation coverage, the description still anticipates every ambiguous outcome: blocked (null), withheld, and hosted-on-Automatic-DMARC. An agent knows what to relay in each case and what not to synthesize, leaving no gap that would cause a wrong call or a wrong report.

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 already documented in the schema including the not-found refusal and ownership non-disclosure. The description reinforces 'ONE domain the caller's account monitors' but adds no syntax or format detail beyond what the schema provides, 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 and resource — 'Read the DMARC enforcement-readiness verdict for ONE domain' — plus the basis of computation (the aggregate RUA report window). It also explicitly separates itself from scan_domain, so an agent can route correctly without opening 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?

Gives an explicit triggering condition ('when a signed-in operator asks whether a monitored domain is ready for the next DMARC step'), a sequencing rule ('use this before proposing enforcement'), and a named alternative with the reason to prefer this tool over a scan. Exclusions are clear.

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?

Explains the side effect that justifies readOnlyHint=false: it scans once only if no report exists, otherwise it is a pure read. Adds caching/staleness semantics via scanned_at, which the annotations cannot convey, and describes what the returned report contains.

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 rule, but the single paragraph is repetitive: 'cheap first look'/'cheap read'/'right default for a first look' restate the same point, and the scan_domain preference is stated twice. It could be tightened without losing content.

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 an output schema exists, the description still usefully notes the report contents and scanned_at for staleness. With one simple parameter, annotations, and the explicit scan_domain comparison, 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?

The schema already fully documents the single domain parameter (bare name, subdomain, unicode to punycode), so the description need not add syntax. It says nothing extra about the parameter, making the baseline 3 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 specific verb and resource (return the stored report for a domain) and explicitly contrasts it with scan_domain. An agent can immediately tell it is the cached-read sibling of scan_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?

Gives an explicit decision rule: use this when a recent report is enough, use scan_domain when state must be re-read now, with a concrete example (after a DNS change). 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?

Beyond the read-only annotations, the description adds the monitoring:read auth requirement, newest-first ordering, the domain-filtering behavior, the returned fields, and the scoring_version interpretation. It also tells the agent to render report_url as a clickable link, which is useful operational context not covered by the 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?

The description is front-loaded with the usage trigger and then moves efficiently into auth, ordering, and follow-up behavior. It is somewhat over-detailed in enumerating returned fields despite having an output schema, but the field list and report_url instruction are not wasteful enough to undermine the structure.

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 list tool with annotations and an output schema, the description covers the missing contextual pieces: when to use it, required auth, filtering and ordering, and the related get_email_test call. An agent has enough information to invoke it 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?

The input schema already has 100% description coverage for both limit and domain, so the schema carries the parameter semantics. The description restates the optional organization-level domain filtering but adds no syntax or edge-case detail beyond the schema. Baseline 3 is appropriate when structured fields do the heavy lifting.

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 uses a specific verb and resource: it lists the account's email tests, newest first, with an optional domain filter. It explicitly distinguishes itself from get_email_test, which retrieves the full result for a single test. An agent can select it against the sibling retrieval tools 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?

It gives an explicit triggering condition: a signed-in user asking about prior email tests or how a sender's earlier tests scored. It also states the required API token scope and names get_email_test as the follow-up when a specific test_id is needed. This is clear when-to-use and alternative guidance.

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 read-only, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new context: an API token is required, the meaning of each state (including that verification_lapsed pauses monitoring), and the instruction to relay next_step verbatim rather than paraphrase it.

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 trigger condition before the output description, and every clause carries information — the parentheticals exist to define the state values. It runs slightly long in a single breath, but nothing is redundant or restated.

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 an output schema present, return fields need not be explained, yet the description still glosses the two important ones (state and next_step) and covers auth. Nothing an agent needs to call and interpret 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the schema is trivially complete at 100% coverage. Baseline 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 ('Lists every domain on the caller's account') and scopes it to the caller's own account, which separates it from sibling tools like get_domain_records or check_domain_verification that operate on a named domain. The enumerated state values (verified, pending, verification_lapsed) make the output shape predictable before 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?

Gives an explicit trigger: use when a signed-in operator asks which domains their account monitors, or what to do next on them. It does not name a competing sibling or state when-not-to-use, but the caller-anchored condition is specific enough that an agent will route here correctly.

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 openWorldHint, so the safety profile is covered. The description adds genuinely useful behavior beyond that: redacted:true is the post-GDPR norm rather than a failure, `unknown` means the registry did not answer (not absence), and `reason` distinguishes rate limit, timeout, registry error, or no RDAP service. The flat 'Observation only, report never advise' framing is the one place the description restates the read-only guarantee the annotations already make, so the score lands just under 4.

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 payload, then the status semantics, then the sibling routing — a logical order with no wasted sentences. It is dense and runs long for a one-parameter tool, and the 'REPORT, never advice to buy' line is more prescriptive than informative, keeping 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?

Return values are largely covered by the output schema, yet the description still supplies the interpretive keys an agent needs (`status` tri-state, `reason`, `redacted`) and the hard rule never to call a name free unless status is exactly not_registered. For a single-parameter read tool this leaves no meaningful gap.

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% for the single `domain` parameter, and the schema itself already documents bare names, subdomains, rejection of scheme/path/port, and punycode normalization. The description adds no format or validation 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?

States a specific verb and resource (reads a domain's registration from the registry over RDAP) and immediately enumerates the exact questions it answers — owner, expiry, registrar, nameservers, registered status, transfer/delete locks. It is clearly separable from siblings like check_domain_names and check_domain_verification.

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 when-to-use trigger ('when the user asks who owns a domain... the WHOIS question') and names the alternative for the multi-name case: call check_domain_names once with up to 20 names instead of this tool per name. Both the selecting condition and the exclusion are 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 already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: 'Nothing is stored — the report is parsed and discarded,' plus the accepted container formats and the 2 MiB decoded ceiling. It does not discuss failure modes for malformed input, but the annotations carry most of the burden.

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 triggering scenario before mechanics. Every sentence earns its place: trigger, output shape, input encoding and limits, and the no-persistence guarantee. 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?

An output schema exists, so the description need not enumerate return fields; it still summarizes what the parse yields at the right altitude. Inputs, formats, size ceiling, and the storage guarantee are all covered, leaving nothing an agent needs in order to call 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 both parameters are already fully documented in the schema, including the content-based format detection for `filename`. The description restates the base64 encoding, format list, and size limit, which is consistent but largely duplicative of the structured field. Baseline 3 applies when the schema does the heavy lifting.

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?

Specific verb (parse) plus a precise resource (ONE DMARC aggregate RUA report) and an explicit statement of the produced output: per-source aggregates with sender, volume, and SPF/DKIM alignment share. This clearly distinguishes it from sibling tools like validate_dmarc_record or check_record, which operate on records rather than uploaded report files.

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 a concrete trigger condition: the user uploads or pastes a DMARC aggregate XML report and asks what it says. The 'Parse ONE report' phrasing implicitly bounds scope to a single file. However, no alternative sibling is named for adjacent cases (e.g., multiple reports, or validating a record instead), so it stops short of full when-not guidance.

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, the description discloses the dedup window, the scanned_at caveat when verifying edits, cache-first explanations, fixengine-generated fix_record behavior, and the status vocabulary used by the report. These details materially affect how an agent should interpret and re-run the scan, and they are consistent with the non-readOnly, non-destructive, open-world 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?

The important use-case and the distinction from get_report are front-loaded, and nearly every sentence carries operational value. It is dense and somewhat long, but the length is justified by the number of checks, caveats, and delivery rules it needs to convey.

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?

The tool has an output schema, so the description does not need to fully enumerate return values, but it still gives enough context about statuses, fix records, sender_requirements, and caching to set correct expectations. For a one-parameter scan tool with annotations and an output schema, the definition is complete.

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 parameter format is already documented. The description still adds useful semantic guidance about the domain value: it must be the user's real domain, placeholders must be avoided, and the agent should ask if the domain has not been stated.

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: force a fresh domain scan and return a full report with seven named checks. It clearly distinguishes this tool from get_report by framing this as current-state scanning versus cached answers, so an agent can identify it 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 triggers such as checking SPF, DKIM, DMARC, MX, DNS health, blacklist status, or expiry, and it names the alternative get_report when a recent cached answer will do. It also specifies the prerequisite that the user must provide a real domain, including asking first and never scanning placeholders.

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 safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description corroborates rather than contradicts them. It adds real behavioral context beyond annotations: the address is single-use, valid about an hour, each call mints a new address, the daily limit only counts messages that actually arrive, several unused addresses can be open simultaneously, and the response's 'limit' field reports which allowance applied. Missing are anything about auth requirements or error behavior, so a 4 rather than 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?

The opening clause is front-loaded with the use case, and the trailing sentences cover return shape, follow-up call, and quota semantics. It is dense and every sentence carries information, though the single long paragraph juggles several concerns and could be broken up for 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?

With an output schema present, the description needn't document return fields, and it still names the key outputs (address, test_id, limit). Combined with the workflow instruction and quota caveats, an agent has everything needed to call this correctly and hand off to get_email_test.

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, so per the rubric the baseline is 4. The description correctly implies a parameter-free invocation via 'Each call creates a new address', leaving nothing ambiguous about inputs.

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 precise verb and resource ('start_email_test' creates a single-use test address to measure how a real email authenticates), and enumerates the scenarios it addresses (SPF/DKIM/DMARC alignment, spam placement, proving DKIM before tightening DMARC). It is clearly distinguishable from the sibling get_email_test, which it names 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?

It gives explicit triggering conditions ('when the user wants to know how a real email from them actually authenticates'), spells out the exact end-to-end workflow (send one email, then call get_email_test with the test_id), and implicitly routes the agent away from using this tool for retrieving results.

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, yet the description still adds non-obvious behavior: nothing is created and no email is sent, the domain is entered on the dashboard after sign-in, and monitoring only begins once ownership is proven with a DNS record. It also tells the agent to render signup_url as a link alongside the message, which is a presentation requirement no structured field captures.

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 condition and the exclusion are front-loaded and every clause carries information. The opening sentence is long and heavily enumerated, with an explanatory parenthetical about five locations/four continents that is nice color but weighs down the entry point.

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?

An output schema exists and the description still orients the agent to its two fields; safety is covered by annotations and reinforced by the no-write/no-email statement. The full lifecycle (signup link → dashboard entry → DNS proof → monitoring active) is spelled out, leaving no ambiguity about what happens after the call.

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 already documents format, subdomain support, and punycode normalization, so the baseline applies. The description adds only the ownership precondition ('a domain they own'), not any format 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?

The second sentence states precisely what the call returns (signup_url plus a short message) and what it does not do (create anything, send email), so the agent knows this is a link hand-off, not a setup action. It separates itself from diagnostic siblings via 'not for a one-off question about whether a site is down right now', but it never contrasts with the very close sibling add_monitored_domain, which is the one real source of selection confusion.

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 concrete, enumerated trigger list (DMARC/RUA monitoring, new-sender monitoring, auth alerts, DNS and uptime-down alerts) and an explicit exclusion for one-off 'is it down now' checks. What's missing is naming the actual alternative tool for that excluded case, so the agent must infer it from the sibling list.

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/non-destructive/idempotent/closed-world, so the safety profile is covered. The description adds real behavioral value beyond that: this is pure string parsing with no DNS lookup, and its output must be presented verbatim. The p=quarantine/p=reject explanation clarifies the policy-upgrade boundary that motivates why a static pasted record can't unlock stricter policies.

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 output summary are front-loaded and efficient. The trailing discussion of `upgrade_record` and p=reject is longer than strictly needed for this tool, though it earns some place by explaining the 'safe' framing in the trigger.

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 annotations covering safety and an output schema covering return shape, the description only needs to supply the trigger, the no-DNS input constraint, and the verbatim-presentation obligation — all of which are present. Nothing an agent needs to invoke 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?

Schema coverage is 100% and the single `record` parameter is fully documented in the schema, including the 'value only, not the hostname' constraint. The description reinforces but does not extend that semantics ('pass the record string itself'), so 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 specific verb (validate) and resource (DMARC record), then immediately enumerates what it produces: parsed tags, leveled findings, and a validity verdict. It also names a sibling (`upgrade_record`) so the 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?

The opening sentence gives an explicit trigger — 'when the user pastes a DMARC record and asks whether it is valid, correct or safe' — and the 'No DNS lookup — pass the record string itself' line routes away from DNS-based siblings. It does not, however, distinguish this from other parsing siblings like parse_dmarc_report or check_record, so it falls short of full when-not coverage.

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 goes well beyond the annotations: 10-minute rechecks for up to 48 hours, exactly one email to the account address, four termination conditions, idempotent re-invocation, and 'nothing is applied to anyone's DNS'. That is strong disclosure and consistent with readOnlyHint=false and destructiveHint=false, but the write-ish server-side state creation implied by readOnlyHint=false is only explained indirectly rather than stated.

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 condition and free of filler, but it is one long paragraph packing lifecycle, idempotency, account requirements and return behavior together. Splitting the notification triggers from the argument guidance would make it easier to scan.

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 though an output schema exists, the description covers the non-obvious operational facts an agent needs: no email address may be requested, a linked account is required, the watch is per signed-in user, and watch.note must be relayed. Nothing material 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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine routing value: 'same arguments as check_record' and the conditional instruction to pass expected_value when publishing a specific value, which the schema only implies. It does not add format details for host/domain beyond what the schema already documents.

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: it 'starts a free watch on ONE record for the signed-in user' and rechecks with 'the same verdict as check_record', which directly separates it from the sibling check_record and from check_propagation. An agent knows exactly what this creates 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?

Gives an explicit trigger ('when the user asks to be told when a DNS change they are making has finished'), names the sibling whose semantics it mirrors, and spells out when nothing is started: already-live records, non-answering nameservers, lookup faults. It also pre-empts the duplicate case by saying a repeat request returns the running watch.

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