dns-doctor

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

The annotations already indicate a safe, read-only tool, but the description adds critical behavioral nuances: unverified domains are never reported as available, registry_confirmed must be true for include_registrable to claim availability, and it warns about the dangers of SPF changes. This goes far beyond the structured 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 lengthy but each sentence adds critical information for a complex audit tool. It is front-loaded with purpose and flows logically into return values, findings, and caveats. However, it is one dense paragraph and could benefit from structural breaks, so a 4.

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 complexity of SPF supply chain auditing, the description covers the return shape, all finding types, edge cases (unverified, registry_confirmed), warning about availability, and the alternative tool. The presence of an output schema reduces the burden, but the description still explains the key outcomes thoroughly, earning a 5.

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 fully describes the domain parameter, including format, subdomains, unicode normalization, and exclusions. The description doesn't add new parameter semantics; it only references domain in the context of verification failure. With 100% schema coverage, the baseline is 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?

The description opens with a clear verb and resource: 'Audit a domain's SPF supply chain' and specifies what it does: 'walks every include and redirect it delegates to, and reports who can transitively send as it.' This distinguishes it from siblings like count_spf_lookups and scan_domain by focusing on transitive delegation.

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 description explicitly names an alternative tool: 'Use count_spf_lookups instead when the question is only the 10-lookup limit.' It also strongly advises on how to interpret findings: 'Findings are risk analysis, not instructions' and 'relay the findings and let the domain's owner decide.' This is clear 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?

Even though annotations provide openWorldHint and idempotentHint, the description adds substantial behavioral context: null is the answer, not a fault; alignment is server-side derived; existing np tags are preserved; and the returned record must be presented verbatim with human approval. No contradiction with the annotations appears.

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 dense and front-loaded with the core purpose, and nearly every clause earns its place. However, the enumeration of null-record cases is a long, winding parenthetical that could be better structured for scannability, so it is not maximally concise.

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 output schema exists, the description covers the remaining context an agent needs: null semantics, enforcement limits, np tag behavior, and the human-approval publishing constraint. The tool is complex, and this description is complete enough to call correctly.

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

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

Schema coverage is 100%, so the schema already fully documents the single `domain` parameter. The description does not add parameter-specific semantics, which is acceptable under the rubric because the schema carries the burden here.

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

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

The description opens with a specific verb and resource: 'Return a validated DMARC enforcement-upgrade record for a domain.' It then clearly separates this from scanning ('A scan can justify p=quarantine at MOST') and from monitoring ('p=reject is unlocked only by aggregate-report evidence over a full reporting window (monitoring)'), which distinguishes it from siblings like scan_domain and start_monitoring_signup.

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 description gives explicit when-not guidance: a caller cannot assert alignment, p=reject cannot come from a scan, and a null record must not be filled. It also tells the caller exactly what to do ('relay rationale', 'Present a returned record verbatim', 'a human must approve before publishing'). This is strong usage routing relative to alternatives.

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, openWorldHint, idempotentHint, and destructiveHint false. The description adds essential behavioral details beyond these: the server independently re-checks DNS, returns records:null with rationale when mail evidence is found, reports lookup failures as failures, and requires human approval. This significantly enriches the annotation context without contradiction.

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?

Although longer than typical, every sentence contributes critical information: the pack contents, domain eligibility, human confirmation requirement, server re-check behavior, failure handling, and publishing workflow. It is front-loaded with the core purpose and well-structured for an agent to parse.

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 description covers purpose, scope, human-in-the-loop safety, server-side verification, failure semantics, and output handling (records verbatim, order, approval). Given the complexity and the presence of an output schema and annotations, the description is fully complete for agent selection and invocation.

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 baseline is 3. The description adds extra meaning for confirm_no_mail ('that flag unlocks the question, not the answer') and domain (scope restrictions), and it reinforces the human-decision aspect. It doesn't fully detail rua_email behavior, but that's already well-described in the schema; the additional context justifies a 4.

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

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

The description clearly specifies the tool's function: building a three-record hardening pack (Null MX, hard-fail SPF, DMARC p=reject) for non-sending domains. It distinguishes from siblings like build_dmarc_upgrade by explicitly scoping to parked/redirect/brand-defensive domains and excluding sending domains.

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

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

Explicit when-to-use guidance: 'For parked, redirect and brand-defensive domains only — NEVER for a domain that sends any mail'. It also clarifies the confirm_no_mail flag requires human confirmation and that the server re-checks DNS, with instructions to relay rationale rather than retry on null result.

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 discloses key behavioral traits: it 'Returns the verdict, its explanation, and the published key record when one resolves' and explicitly states 'No fix record is returned' with a rationale about DKIM key generation. This adds substantial context beyond the readOnly/openWorld/idempotent annotations, making the tool's output and limitations transparent.

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 two sentences, front-loaded with the core action, and every clause earns its place. It efficiently conveys purpose, distinguishes from alternatives, describes outputs, and explains the absence of a fix record without wasted words.

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 tool has only two parameters, a rich input schema, an output schema, and comprehensive annotations, the description fully covers the necessary context: what it checks, when to use it, what it returns, and why no fix record is provided. There are no significant gaps in the guidance an agent would need.

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 provides 100% coverage with detailed descriptions for both parameters (domain and selector), including the nuance that the selector is 'not guessable from the domain.' The description adds little beyond reinforcing that the selector is the exact one used by the sending platform, so the schema does the heavy lifting; the description only marginally extends the parameter meaning.

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 starts with 'Check ONE specific DKIM selector on a domain', a specific verb+resource+scope, and explicitly contrasts with 'a full scan's common-selector sweep may miss', clearly distinguishing it from sibling scan tools. It also clarifies what is returned (verdict, explanation, key record), leaving no ambiguity about the tool's function.

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 description implies when to use the tool by stating it targets 'the exact selector the sending platform uses' that a full scan might miss. This provides clear context for choosing this tool over a broader scan, though it does not explicitly name an alternative or spell out 'when not to use' scenarios.

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 carry readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description reinforces this with 'Observation only: no record is ever composed here.' It goes well beyond annotations by specifying the tricky interpretation semantics: an `unavailable` cell is NOT a negative result, the verdict downgrades to `unknown` when fewer than three vantage points are reached, and the agent must report vantage_reached of vantage_total rather than declaring convergence on partial coverage.

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

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

Front-loaded with the global scope and six-vantage-point mechanism before anything else, and every sentence carries operational or interpretive content with no filler. The final sentence is dense — four distinct warnings packed into one long clause — but each warning is necessary, so it earns a 4 rather than 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 tool with this complexity — multi-vantage-point reads, partial coverage, and a verdict that can degrade — the description covers the behavioral pitfalls that would cause an agent to misreport results or misinterpret absence as failure. The output schema exists and can carry the grid/verdict return shape, and the description covers what the schema cannot: when to invoke it and how to interpret non-answers.

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 name exactness (www. NOT stripped, underscore labels kept), the record_type enum values, and expected_value's match/mismatch effect. The description restates these rather than adding new parameter semantics, so it stays at the baseline 3 for fully-schema-covered parameters.

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 a DNS change has propagated GLOBALLY' — and defines the mechanism: six vantage points (five owner-run probes across four continents plus this server's own resolver). This clearly distinguishes it from sibling tools like check_record, check_dkim_selector, and check_reverse_dns, which are single-point checks; the description even contrasts the agent's single 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?

Explicitly tells the agent when to call this tool: 'Call it after the human publishes a record', with the rationale that a record resolving from the agent's single vantage point can still be missing elsewhere. This is clear contextual guidance, but it stops short of naming alternative tools or stating explicit when-not-to-use conditions, so it earns 4 rather than 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?

The description goes far beyond the readOnlyHint and idempotentHint annotations. It details the exact query logic for each kind (e.g., dmarc reads TXT at _dmarc.<domain>), explains that empty values mean genuinely absent, and clarifies the meaning of in_sync false and max_wait_seconds. The caveat about sampling only two resolvers is critical behavior 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?

The description is appropriately sized and front-loaded with the main purpose, then systematically covers kind semantics, host restrictions, output interpretation, and limitations. Every sentence earns its place, with no filler or redundancy.

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 tool's complexity (multiple record kinds, derived queries, cache-free vs caching resolvers), the description covers all essential aspects. The output schema exists, and the description still explains key output semantics like empty values and max_wait_seconds, making it thoroughly 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?

The input schema already provides comprehensive descriptions for all three parameters (100% coverage), including kind's derived query logic and host's allowed types. The tool description largely restates this information, adding no significant new parameter semantics beyond the schema.

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

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

The description uses a specific verb 'Check' and states the exact resource: 'whether a DNS change has landed' by reading from the domain's own nameservers and two public resolvers. This clearly distinguishes it from sibling tools like check_dkim_selector or check_reverse_dns, which target specific record types.

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 description explicitly states when to use: 'Check whether a DNS change has landed' and provides an exclusion: 'never describe it as worldwide or as propagation coverage' because it samples only two resolvers. However, it does not name alternative sibling tools for specific DNS checks, so it lacks explicit 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description explains the internal two-step resolution process, defines each verdict, and warns about the misleading nature of bare PTR records. This provides rich behavioral context that annotations alone do not capture.

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

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

Every sentence in the description adds value: purpose, verdict definitions, critical warning about PTR interpretation, fix responsibility, and input requirement. It is front-loaded with the core purpose and remains compact without redundancy.

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 simple one-parameter schema, rich annotations, and existing output schema, the description fully covers what the tool does, how to interpret its output, and the operational context (who can fix issues). No significant gaps remain.

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 covers the single 'ip' parameter with full description including the public address requirement. The description repeats the constraint ('Pass a public IPv4 or IPv6 address') but adds no additional semantic meaning beyond what the schema already provides. Baseline 3 applies due to 100% schema coverage.

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 ('Check') and resource ('forward-confirmed reverse DNS'), explaining the exact mechanism (PTR lookup then forward resolution) and the three possible verdicts. This clearly distinguishes it from sibling tools like check_record or check_dkim_selector.

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 description gives clear context for when to use the tool (checking a sending IP's FCrDNS) and crucial guidance on interpreting results ('never report a bare PTR as verified'), plus where fixes belong. It does not explicitly name alternative tools for comparison, but the usage context is unambiguous.

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

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

Beyond the readOnly/idempotent annotations, the description discloses critical behavioral traits: the diagnose-only nature with the explicit promise 'no SPF fix record is ever returned,' the rationale about silently de-authorizing senders, and the nested include recursion behavior. This adds significant context the annotations alone don't provide.

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 dense but well-structured, front-loading the main purpose and then flowing through return values, parameter usage, and an important caveat. Every sentence adds functional value, with no fluff or repetition. The length is justified by the tool's 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?

With a rich description, full schema parameter descriptions, and an output schema present, the tool is fully specified. The description covers the 10-lookup limit, over_limit/near_limit indicators, offending_mechanisms, and the reason for not fixing records — leaving no practical questions about what the tool does and how to invoke it.

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

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

Even though schema coverage is 100%, the description enriches both parameters by clarifying the exact-one constraint and behavioral difference: 'domain resolves the published record and counts recursively through nested includes' vs. 'record parses a pasted record, its own terms only.' This goes well beyond the schema's field descriptions.

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

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

The description opens with a specific verb and resource: 'Validate an SPF record and count what it costs.' It clearly distinguishes this tool from siblings by stating 'This is the SPF validator — there is no separate one.' It also enumerates key outputs (record_valid, findings, has_pass_all, etc.), making the purpose unmistakable.

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 description provides explicit when-to-use guidance including the two mutually exclusive modes: 'Pass EXACTLY ONE of domain or record' with detailed explanations of each. It also states when NOT to use it for fixes: 'Diagnose-only: no SPF fix record is ever returned' and explains why, positioning it against potential alternatives.

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

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

The description adds substantial behavioral context beyond the annotations: every generated record includes 'np=reject' regardless of p=, the record is 're-validated before it is returned,' and it must be 'present[ed] verbatim' with human approval. These details are not visible in the readOnlyHint, idempotentHint, or destructiveHint annotations, and they inform the agent's action and output handling. No contradiction with annotations exists.

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 three sentences, each earning its place: the first states the core function, the second summarizes parameters and the critical np=reject behavior, the third explains re-validation and the human-approval requirement. It is front-loaded and free of redundant or vague phrasing.

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

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

With an output schema present, the description does not need to detail return values. It covers the essential context: when to use (domain without a record), key behavioral traits (np=reject, re-validation), and process requirements (verbatim presentation, human approval). This is complete for a 4-parameter, 1-required tool and complements the rich schema and annotations.

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 provides 100% parameter descriptions, covering policy, rua_email, subdomain_policy, and strict_alignment. The description merely summarizes these parameters (e.g., 'policy is none|quarantine|reject') without adding semantic depth beyond the schema. The np=reject mention is about output behavior, not parameter meaning, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource: 'Build a DMARC record from scratch for a domain that has none.' This clearly distinguishes the tool from siblings like build_dmarc_upgrade (which implies working with an existing record) and validate_dmarc_record (which checks rather than builds). The phrase 'never compose one yourself' reinforces the tool's specific role.

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 description gives a clear usage condition: 'for a domain that has none,' implying this tool is for domains lacking DMARC records. It does not explicitly name alternatives or enumerate when-not-to-use scenarios, but the context is sufficiently clear. The guidance that a human must approve before publishing adds an important usage boundary.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds rich behavioral context: it requires an API token, explains why the tool is read-only (to avoid silencing unread alerts), details the `dashboard_only` delivery_class nuance, and exposes pagination edge-case behavior (dropping rows when ignoring `next_before`). No contradictions with annotations.

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

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

The description is longer than average but every sentence carries operational weight. It is front-loaded with the core purpose and scope, followed by field highlights, then high-stakes pagination warnings in caps, and finally the read-only rationale. No filler or redundancy.

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 this is a data retrieval tool with a generic output schema (indicated by 'Has output schema: true'), the description covers all necessary contextual aspects: authentication, scope, field list, pagination behavior, exclusion semantics, and usage guardrails. It is complete for an agent to select and invoke the tool correctly.

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

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

Although schema coverage is 100%, the description adds significant semantic value: it explains the inclusive `since` floor and de-duplication need, warns that `before` is an opaque cursor never to be constructed/edited, and notes that unknown `type` or `domain` values are rejected, not silently ignored. This goes well beyond the schema descriptions.

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

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

The description opens with a precise verb-resource-scope statement: "Read the monitoring alert log for the domains the caller's account monitors, newest first." This distinguishes it clearly from all sibling tools, which are about DNS/SPF/DMARC checks or report generation, not alert logs.

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 frames when this tool is appropriate ("agent watching only the inbox would never see it; this log is the complete picture") and when not to use it for actions ("there is no ack and no delete here"). It also gives crucial operational guidance on pagination ('PAGE DOWN BEFORE ADVANCING `since`') and the inclusive `since` semantics with de-duplication advice.

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?

While annotations declare readOnlyHint=true, the description adds critical behavioral nuance: it explains that next_record is null when blocked, and that 'THAT NULL IS AN ANSWER: relay the blockers and never compose a stronger record to fill the gap.' It also mandates presenting the record verbatim and requiring human approval, plus notes 'Requires an API token.' These details go well beyond the annotation safety profile.

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 dense but every sentence earns its place. It front-loads the core purpose, then explains return fields, null semantics, usage caveats, and approval requirements without repetition or filler. The structural flow is logical and efficient.

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 is conceptually complex (readiness verdict, blockers, null handling, human approval), yet the description covers the full context: what it returns, what null means, how to handle the record, when to use it, and the required authentication. With an output schema also present, this description is complete for correct invocation and handling.

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%: the domain parameter description already explains it must be a 'VERIFIED monitored domain' and that ownership is not disclosed. The tool description reinforces 'ONE domain' and 'caller's account monitors' but adds no new semantic meaning beyond the schema. Baseline 3 is appropriate 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?

The description opens with a specific verb and resource: 'Read the DMARC enforcement-readiness verdict for ONE domain the caller's account monitors.' It clearly distinguishes this from sibling tools like scan_domain by emphasizing the evidence window and the readiness verdict, noting that 'only this evidence window can say whether tightening it would start rejecting real mail.'

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

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

Explicit guidance is provided: 'Use this before proposing enforcement' and contrasts with scan_domain ('a scan can show a domain's current policy, but only this evidence window can say whether tightening it would start rejecting real mail'). It also gives strong when-not-to instructions: 'never compose a stronger record to fill the gap' and 'a human must approve it before it is published.'

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 discloses a key behavioral trait beyond annotations: it may 'scan once only if none exists yet,' explaining why readOnlyHint is false. It also adds the `scanned_at` field so the agent can judge staleness, providing context that annotations alone do not convey. It doesn't go into error cases or rate limits, but for this tool the disclosed behavior is sufficient.

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 tightly packed: two sentences deliver purpose, behavior, return contents, staleness cue, and explicit alternative. Every clause earns its place, and the most important 'cheap read' framing is front-loaded.

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 one parameter, a rich schema, and an output schema (though not shown). The description explains the full return face (the same seven-check report as scan_domain, including statuses and observed records) and provides the alternative guidance. There are no significant gaps for an agent to invoke it correctly.

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

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

The input schema already provides 100% parameter coverage with a detailed description of the domain parameter including format rules and punycode normalization. The tool description does not add further parameter semantics, but it doesn't need to given the schema's richness. 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 tool's verb and resource: 'Return the stored report for a domain.' It also distinguishes itself from the sibling 'scan_domain' by framing get_report as the 'cheap read' and 'right default for a first look,' while scan_domain is for forcing a fresh scan.

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 usage guidance is provided: get_report is recommended as the default first look, while 'Prefer scan_domain when you specifically need state re-read right now — for example after a DNS change.' This directly tells the agent when to choose this tool over its alternate.

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 (readOnlyHint=true, destructiveHint=false), the description adds valuable behavioral context: 'Nothing is stored — the report is parsed and discarded' and the 2 MiB decoded size limit. This clarifies side effects and constraints, complementing the annotation-provided safety profile.

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 two sentences: the first states purpose and output, the second provides input instructions and a key behavioral note. Every sentence earns its place, with no冗余. It is front-loaded and easy 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?

Given the tool's moderate complexity, the description covers input format, size constraints, output summary, and side effects. An output schema exists, so return values are already structured; the description's output summary is sufficient context. No significant gaps remain.

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% with descriptive parameter comments. The description adds further meaning by specifying that content_base64 expects encoded file bytes (not raw XML), the decoded size limit, and that filename only affects logs, not parsing. This enriches the schema with practical usage details.

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 verb 'Parse' with a specific resource 'DMARC aggregate (RUA) report' and defines the output as readable per-source aggregates (who sent mail, how much, alignment share). This distinguishes it from sibling tools like get_report, which likely fetches reports rather than parsing provided content.

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 description gives clear invocation context: pass file bytes base64-encoded in content_base64, with optional filename. It also specifies supported formats and size limit. However, it does not explicitly name alternatives or when-not-to-use, though the instruction is sufficiently clear for the intended use case.

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 cache-first and dedup behavior, warns that scanned_at may predate a DNS change, and clarifies that a repeat scan can reuse a stored report. This adds significant behavioral context that would otherwise be hidden. It is consistent with idempotentHint=false and openWorldHint=true, so there is no contradiction.

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 dense but each sentence earns its place: the core action and return shape come first, followed by the critical dedup caveat, then the routing rule. No filler or repetition is present. The length is justified by the behavioral quirks an agent must know.

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 output schema exists and the description already summarizes return fields, the description covers the important operational context: what gets scanned, result statuses, cache behavior, timing gotchas, and when to prefer get_report. An agent has what it needs to call and interpret this tool correctly.

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

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

The tool description itself does not add parameter-level detail beyond saying it scans 'a domain.' However, the input schema's property description already fully documents acceptable formats, exclusions, and punycode normalization, giving 100% schema coverage. Per the baseline for high schema coverage, this is adequate even though the description adds no extra parameter semantics.

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

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

The description opens with a specific verb and resource: 'Force a fresh scan of a domain and return its full report.' It enumerates the seven checks and each check's result shape, and it distinguishes itself from the sibling get_report by contrasting fresh scans with cached answers. An agent can clearly tell what this tool does and how it differs from nearby alternatives.

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 description gives an explicit decision rule: 'Use this when you need current state; use get_report when a recent cached answer will do.' It also explains the dedup window and advises checking scanned_at when verifying an edit, which tells the agent not just when to call but how to interpret results. This is strong, actionable usage 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?

The description goes well beyond the annotations by explaining the deferred flow: nothing is created, no email is sent, the domain is only carried over after the human signs in, and monitoring starts only after TXT ownership verification. It also specifies exact output behavior for signup_url and message. This adds meaningful behavioral context that annotations alone do not provide.

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 first sentence is an excellent front-loaded purpose statement, and the subsequent details about the signup flow and output formatting are necessary for correct agent behavior. The second sentence is long and contains many clauses, but every clause contributes operational information. It is dense rather than bloated, though not maximally concise.

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 one well-documented parameter, an output schema, and annotations covering read-only and idempotent behavior, the description supplies the missing interaction context: who receives the link, how the follow-up flow works, and how the agent must present the output. The explicit instruction to print signup_url verbatim and never sign in on the user's behalf closes the main operational gaps. Nothing essential is left ambiguous.

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 documents the single parameter 'domain' thoroughly, including accepted formats, punycode normalization, and exclusions. The description adds no additional parameter-level semantics beyond referencing signup_url. With 100% schema description coverage, this meets the baseline but does not exceed 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?

The opening sentence uses a specific verb and object: 'Return a sign-up link to give to the HUMAN who owns a domain, so they can start monitoring it themselves.' This clearly states what the tool does and differentiates it from the sibling checking, generation, and validation tools by emphasizing a self-service handoff. It also explicitly states what the call does not do, which removes 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?

The description gives clear situational guidance: use this tool to hand monitoring start-up to the human domain owner, and never sign in on their behalf. It provides a strong boundary for when this tool is appropriate. However, it does not name sibling alternatives or explicitly state when another tool should be used instead, so it stops short of full when/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?

Annotations already declare readOnly and idempotent, but the description adds significant behavioral specifics: no DNS lookup, the policy unlock logic, and the instruction to present returned records verbatim. No contradiction with annotations.

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

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

The description is moderately sized, with focused sentences that convey purpose, constraints, and alternatives without unnecessary filler. Slightly dense but efficient.

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 output schema exists, the description covers all essential aspects: what it validates, how to pass the input, policy limitations, and references to related tools. An agent would have enough context to invoke it correctly.

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

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

The schema provides 100% coverage of the 'record' parameter with a clear example and clarification about the hostname. The description reinforces these points but adds no new parameter-level semantics beyond what the schema already offers.

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 clear verb ('validate') and resource ('DMARC record') with explicit outputs (parsed tags, level'd findings, validity). Distinguishes from siblings by specifying it handles a pasted record string, not a DNS lookup.

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 'No DNS lookup — pass the record string itself' and clarifies when p=reject is unlocked, referencing upgrade_record as an alternative. This provides clear context on when to use this tool versus others.

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