Pipefire email deliverability tools

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds useful behavioral context by disclosing what the analysis returns (auth results, alignment, delivery path, delays), which is the key trait for interpreting output on a tool with no output 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?

Two sentences, front-loaded with the action and inputs, then the return contents, then the usage trigger. No filler or repetition.

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 tool with no output schema, the description covers input format, analysis scope, and a usage trigger. Nothing an agent needs to select and 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?

Only one parameter, and the schema already documents it at 100% coverage ('the part above the message body'). The description's 'raw headers of a received email' and 'pastes headers' reinforces format expectations slightly but adds no new syntax or constraints. Baseline 3 applies when the schema does the work.

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

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

States a specific verb and resource ('Read the raw headers of a received email') and enumerates what is extracted: SPF, DKIM, DMARC results, alignment, delivery path and delays. This implicitly distinguishes it from domain-configuration siblings like check_spf or check_dkim, since it analyzes a received message rather than a domain's DNS setup, though no sibling is named.

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 a clear triggering scenario: 'Use when someone pastes headers and asks why a message went to spam or failed authentication.' This tells the agent the input shape and intent. It stops short of naming alternatives (e.g. check_dmarc for domain-level validation) or stating when not to use it.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so safety is covered. The description adds genuine behavioral context that the check is two-part — presence of the BIMI record plus whether the DMARC policy is strict enough for display — which is a real dependency an agent cannot get from the 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?

One tight sentence, front-loaded with the primary action and parenthetically clarifying the domain term. No filler, no redundancy with the schema or annotations.

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 diagnostic, the description covers what is inspected and the DMARC dependency that governs the outcome. It stops short of hinting at result shape, but with no output schema and such a simple surface, little more is needed.

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

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

Single parameter with 100% schema description coverage, including the note that URLs and email addresses are accepted, so the schema carries the parameter semantics fully. The description adds nothing about the domain argument, making the baseline 3 correct.

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

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

Names a specific verb (check) and resource (BIMI record), then glosses it in plain language ("logo in the inbox") so the agent knows the domain concept being tested. The mention of the DMARC-strictness prerequisite differentiates it from the sibling check_dmarc/check_dkim tools, which test those records directly.

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?

Usage is only implied: the agent can infer this is the right tool when the question is whether a brand logo will display in the inbox. It never states when to prefer this over check_dmarc, nor any prerequisites or exclusions. Adequate but leaves routing to inference.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower; the description still adds genuinely useful context by naming the specific blacklist providers queried (an openWorld detail) and by promising removal links in the result. It omits latency/caching behavior and rate limits, which matters for a tool that fans out DNS lookups.

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?

A single front-loaded sentence that states action, accept-ed input modes, scope of query, and output payoff with no filler. Nothing could be cut without losing information.

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

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

No output schema exists, yet the description tells the agent the result conveys listing status plus removal links, which is enough to know what comes back. With only one required parameter and full annotation coverage, the remaining gaps (multi-IP aggregation behavior, lookup latency) are minor rather than blocking.

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 documents the 'domain or IPv4' forms, but the description adds real meaning: for a domain it checks the domain's *sending IPs* (plural, implying MX resolution and fan-out), while the IPv4 path is a single-address check. That distinction is not in 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 gives a specific verb ('Check'), a specific resource (email blacklists), names the major lists queried (Spamhaus, Barracuda, SpamCop), and states both accepted target forms. This clearly separates it from the sibling DNS-authentication tools like check_spf, check_dmarc and check_mx.

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 explains what the tool does but never says when to reach for it — e.g. before a cold-email send or after a deliverability drop — nor does it name an alternative such as check_cold_email or suggest_sending_domains. Usage is left entirely 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 this as a safe, idempotent, non-destructive read. The description adds useful behavior beyond that: it discloses the scoring rubric and, importantly, the return shape — each issue with why it matters and how to fix it — which no structured field provides.

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?

Two tight sentences with the verb and resource front-loaded, then the rubric, then the return contract. No filler and nothing that could be cut without losing information.

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

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

With no output schema, the description carries the burden of explaining returns and does so (issues plus rationale and fix), and the annotation set covers the safety profile. The only gap is the absent guidance on sequence 'kind' handling and when this tool is preferable to its siblings.

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 only 33%, but the description does cover the two required parameters by naming 'subject and body'. It says nothing about the 'kind' parameter (first/follow-up/last), though the schema documents that itself. The rubric list refers to output checks rather than adding parameter-level 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 names a specific verb and resource — score a cold email (subject and body) out of 10 — and enumerates the rubric dimensions (length, reading level, the ask, subject line, spam wording). It implicitly separates itself from test_subject_line by covering both subject and body, but never names a sibling tool outright.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no routing to alternatives such as test_subject_line or analyze_email_headers. Usage is only implied by the tool's subject matter.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds real behavioral context the annotations don't: it automatically probes several well-known selectors before falling back to a user-supplied one, which explains why a result may appear even when the caller knows no selector.

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?

A single sentence that front-loads the action and resource and then qualifies the selector behavior. Nothing is redundant or padded.

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 DNS lookup the safety story is complete via annotations, but with no output schema the description says nothing about what a result looks like — e.g. whether it reports which selector matched or what a negative finding means. Adequate but leaves that 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 description coverage is 100%, so both params are already documented, including the 'URL or email also works' flexibility. The description's remark about auto-tried common selectors mirrors the schema rather than extending it, so the baseline 3 applies.

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

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

Specific verb + resource ('look up a domain's DKIM public key') that clearly separates a diagnostic lookup from the sibling generate_dkim_record. It never names a sibling or explicitly states the contrast, so it stops short of a 5.

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 usage ('trying the selectors ... plus one you name') and tells the agent it may optionally supply a selector, but gives no when-to-use/when-not or routing against check_domain_email_setup/check_dmarc. Usage is inferred rather than 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, openWorldHint, and non-destructive behavior, lowering the bar. The description still adds useful domain context by enumerating the exact checks performed (_dmarc existence, policy, reporting, outdated tags) and the practical meaning of the result (impersonation exposure).

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?

Two sentences, front-loaded with what is inspected and closed with the interpretation, with no redundant or filler 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?

No output schema exists, so the description must convey returns; it does so by listing the record attributes examined and the impersonation verdict. Minor gaps remain around the no-record case and the precise response shape, but it is adequate for a single-domain read-only lookup.

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

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

Only one parameter and schema description coverage is 100%, so the schema already documents that a URL or email address is accepted. The description adds no syntax or format 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 (Check) and resource (domain's DMARC record) and enumerates what it inspects: existence at _dmarc, policy values, report collection, outdated tags, and impersonation risk. It is unambiguous, but it never differentiates itself from siblings like check_spf, check_dkim, or check_domain_email_setup, which likely overlap.

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 closing sentence ('Tells you whether the domain can be impersonated by email') implies a usage context for email-security assessment, but there is no explicit when-to-use, when-not-to-use, or pointer to the sibling tools that cover the rest of an email-auth audit. Usage must be inferred.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds real behavioral value by disclosing the return shape: per-check pass/warn/fail, what was found, and remediation guidance, plus the implicit fact that multiple DNS lookups happen against live external records.

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?

Two sentences, both front-loaded and dense: the first states scope and output shape, the second states when to use it. Nothing is wasted, though the first sentence is a long compound clause carrying four check types plus three output elements.

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

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

With no output schema, the description compensates by describing the per-check status model (pass/warn/fail), findings, and fix guidance. Combined with fully covered parameters and rich annotations, an agent has everything needed to invoke and interpret it.

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

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

Schema coverage is 100%, so both 'domain' and 'selector' are documented in the schema, including the note that common DKIM selectors are tried automatically. The description adds no parameter detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb and resource (check a domain's email setup) and enumerates exactly what is verified: MX, SPF, DKIM and DMARC. This distinguishes it from the single-record siblings like check_spf/check_dkim/check_dmarc by framing it as the aggregated 'in one go' check.

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 concrete triggering situations: 'why their email goes to spam', 'whether their domain is set up right', 'before sending cold email'. It does not explicitly name the alternative per-record tools (check_spf, check_dkim) or state when to prefer them over this aggregate, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and network-access profile is covered. The description adds only subject-matter context about what MTA-STS enforces, not tool behavior such as lookup mechanics, failure modes for domains without a policy, or what the result 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?

One sentence, front-loaded with the verb and resource, with no redundant filler. The trailing relative clause on encryption is mildly explanatory rather than operational, keeping it just short of maximal efficiency.

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

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

For a one-parameter read-only check with full annotations, the description is sufficient to invoke the tool correctly, but with no output schema the agent has no idea what comes back (policy presence, mode, max_age, MX hosts) or how a missing policy is signaled. A sentence on the return shape would close the 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 description coverage is 100% and the schema already documents the single 'domain' parameter, including that a URL or email address also works. The description adds nothing about parameter format or accepted inputs, 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?

Names a specific verb+resource (check a domain's MTA-STS policy) and briefly explains what MTA-STS is, which is genuinely clarifying for an agent. It does not, however, distinguish itself from close siblings such as check_domain_email_setup or check_bimi, so the agent must infer the boundary from the tool name 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?

There is no when-to-use guidance: no statement of when a targeted MTA-STS check is preferable to the broader check_domain_email_setup, no prerequisites, and no exclusions. The description supplies domain background ('forces encrypted delivery of incoming mail') but nothing that routes the agent between 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 already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety behavior is covered. The description adds that provider identification is included in the result, but says nothing about response format, ordering, or DNS failure behavior; with annotations present, a 3 is appropriate.

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?

A single front-loaded sentence with no wasted words; both the resource and the additional provider insight are conveyed immediately.

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

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

For a simple read-only lookup with full annotation coverage and a fully documented parameter, the description covers what the tool does and what it returns at a high level. It could optionally mention output shape (hostnames/priorities), but 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?

Schema description coverage is 100% and the single parameter is fully documented there, including that URLs or email addresses are accepted. The description adds no parameter detail beyond "a domain's", 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 ("List") and resource ("MX records"/mail servers) plus the extra value of identifying the email provider. An agent can distinguish it from siblings like check_spf or check_dmarc 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?

Usage is implied by the tool name and description, but there is no explicit guidance on when to use this versus related checks such as check_domain_email_setup or check_spf. No exclusions or prerequisites 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 cover readOnly, idempotent, open-world, and non-destructive. The description adds real behavioral substance beyond them by naming the specific validation criteria applied (existence, validity, 10-lookup cap, all mechanism), which tells the agent what a 'pass' actually checks.

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?

One sentence, front-loaded with the action and resource, and dense with the enumerated checks. No filler, no redundancy with the 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?

For a simple read-only check with full annotation coverage and a fully documented schema, the description is nearly complete. It does not describe the shape of the result (e.g., pass/fail plus diagnostics), and with no output schema present that is a small remaining 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% and the schema already documents that a URL or email address is accepted, so the description adds no extra meaning about the single domain parameter. Baseline 3 for a fully documented single param.

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 (check) and resource (a domain's SPF record), then enumerates the exact facets examined: existence, validity, the 10 DNS lookup limit, and the all mechanism. The record type naturally distinguishes it from siblings like check_dkim, check_dmarc, and check_bimi.

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?

Usage is implied by the described checks — an agent can infer this is for validating an existing SPF setup — but there is no explicit when-to-use guidance and no mention of the alternative generate_spf_record, nor any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered and the description is consistent with it. The description adds that the result is a publishable TXT record and where it belongs, but says nothing about the keyType default or whether the output is a single string, so it adds only modest 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?

A single front-loaded sentence with no filler; the operation and its output destination are stated compactly and nothing 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?

With no output schema, the description usefully states what the return value is (a formatted TXT record), which covers the main richness gap. It still omits the keyType default and any note about the required public key format beyond the schema, so it is nearly but not 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 only 33%: only publicKey is documented, while selector and keyType are bare (keyType has an enum but no default). The description recovers the selector's meaning by placing it into the DNS hostname, but leaves keyType (rsa vs ed25519) and its default unexplained, so it only partially compensates for the coverage gap.

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

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

The description names a specific verb (format) and resource (DKIM public key as a TXT record), so the transformation is unambiguous. It does not explicitly distinguish itself from the sibling check_dkim or from generate_spf_record/generate_dmarc_record, so it stops short of a 5.

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?

There is no statement of when to use this tool versus check_dkim, nor any precondition such as 'use after generating a keypair.' The record location hint ('publish at selector._domainkey.yourdomain') only faintly implies a setup context, which is not enough to count as 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 readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so the safety profile is fully covered without the description. The description adds that the result is a TXT record intended for publication at a specific DNS location, which is useful output context, but says nothing about validation behavior, errors on invalid input, or whether the record is deterministic for the same inputs.

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?

A single front-loaded sentence with no filler; the verb and produced artifact come first and the qualifier about where to publish follows. Nothing here is wasted or redundant.

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

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

With no output schema, the description must carry the return-value burden; it does state at a high level that the output is a DMARC TXT record for _dmarc.yourdomain. However, it leaves out how optional inputs shape the record (sp tag, rua tag) and gives no sense of the actual returned string or structure, which is a meaningful gap for a generator tool.

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

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

Schema description coverage is only 50% ('domain' and 'subdomainPolicy' carry no description), so the description is expected to compensate. Instead it only echoes the two already-documented inputs ('policy and report addresses') and says nothing about the required domain field or how subdomainPolicy maps to the DMARC sp tag.

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

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

The description gives a specific verb ('Build') and resource ('a valid DMARC TXT record') plus the intended publication location (_dmarc.yourdomain), so the agent knows exactly what artifact this produces. It does not explicitly contrast itself with the sibling check_dmarc or generate_spf_record/generate_dkim_record, but the resource specificity makes the distinction clear.

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?

There is no statement of when to use this tool versus the check_* or other generate_* siblings, and no prerequisites (e.g. that a domain must exist or that this is a generation step in an email-setup workflow). The phrase 'from a policy and report addresses' only restates the inputs, not usage context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is well covered. The description adds one piece of real behavioral value — that the output includes warnings about the 10-lookup limit — but says nothing about the returned record format, what happens with conflicting inputs, or how strict/-all is chosen by default.

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?

A single front-loaded sentence that establishes the artifact first and the warning behavior second, with no padding. Slightly long and comma-heavy, but every clause carries information.

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

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

For a 7-parameter, all-optional generator with no output schema, the description should at minimum explain what is returned and how the optional mechanism flags combine. It covers the purpose and one output trait (lookup-limit warnings) but leaves the caller guessing about the record format, defaults for the boolean flags, and the meaning of the undocumented parameters.

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 only 43%: strict, includes, and providers are documented in the schema, while a, mx, ip4, and ip6 have no description anywhere. The description's 'email services it sends with' loosely gestures at providers/includes but explains none of the mechanism flags, so it does not compensate for the coverage gap.

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

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

States a specific verb and resource — 'Build a valid SPF TXT record for a domain' — and names the input basis ('the email services it sends with'), which separates it from the sibling check_spf, which inspects an existing record. It stops short of naming that sibling explicitly, so the distinction must be inferred from the verb.

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?

Usage is implied by 'generate' versus the check_* siblings, but the description never says when to use this tool rather than generate_dkim_record, generate_dmarc_record, or check_spf, nor that it is for creating new records rather than auditing existing ones. No preconditions or exclusions 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 readOnly, idempotent, non-destructive and closed-world. Beyond that, the description adds a genuinely non-obvious trait: the output is speculative guesses, not verified addresses, and must be validated. It still omits return shape (count, ordering) but the caveat is real added value.

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?

Two short sentences, zero waste. The core behavior and the example formats come first, and the verification caveat is correctly placed last as a qualifier.

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

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

With no output schema, the description should sketch what comes back; 'list the likely email address formats' gestures at it but gives no detail on format or volume. Combined with the undocumented 'middle' parameter, the definition is adequate but leaves clear gaps for a 4-parameter tool.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it only partially does. The permutation examples imply how 'first' and 'last' are combined, but the optional 'middle' parameter is never mentioned and nothing explains that only first+domain are required or what the maxLength limits mean.

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 ('list ... likely email address formats') and resource, with concrete example patterns (first@, first.last@, flast@). It is immediately distinguishable from the check_*/generate_* siblings, which all do verification or record generation rather than permutation.

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 caution 'Guesses only: verify before sending' implies a usage context (use before actual outreach, treat output as unverified), but it never states when to prefer this over alternatives like check_mx or check_domain_email_setup, nor any prerequisites. Usage is implied rather than specified.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and openWorld, so the safety profile is covered. The description adds that availability is checked live (.com/.net), which explains the openWorldHint network behavior, but it says nothing about rate limits, latency, or how many domains are returned.

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?

Two short sentences, front-loaded with what the tool produces and why, followed by the input instruction. No redundant restating 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?

For a one-parameter tool with full schema coverage and a complete annotation set, the description covers purpose, rationale, and input form adequately. It would be slightly stronger if it hinted at the shape of the output (e.g., how many suggestions or what availability data looks like), but no output schema exists to carry that.

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 single 'brand' parameter (business name or domain, max 80 chars) is already fully documented in the schema. The description restates the accepted input form but adds no syntax, format, or constraint detail beyond it — 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?

Specific verb+resource ('suggest lookalike sending domains') plus a stated goal ('so the main domain is never put at risk') and a scope qualifier ('with live .com/.net availability'). This is clearly distinguishable from siblings like check_* and generate_* which do DNS/record work.

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 cold-email use case is stated explicitly, giving the agent clear context for when this tool applies, and the input guidance ('Give a business name or its website') tells the agent how to invoke it. No alternatives or exclusion conditions are named, but the sibling set is non-overlapping so that gap is minor.

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 this a safe, idempotent, read-only, closed-world operation, so the safety profile is covered. The description adds that output includes a 1-10 score plus 'fixes,' which is useful, but says nothing about result structure, determinism of scoring, or any limits beyond the schema's maxLength.

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?

A single front-loaded sentence that states the action, the output scale, the evaluation criteria, and the remediation in one pass. 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?

With no output schema, the description usefully describes what comes back (score, scored dimensions, suggested fixes), which is the main thing an agent needs. For a one-parameter, no-side-effect tool this is close to sufficient; only the scoring behavior and any input constraints remain unstated.

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

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

There is one obvious string parameter ('subject') at 0% schema description coverage, so the description carries the burden of explanation but supplies none. The word 'length' refers to a scoring dimension, not to the parameter's 200-character limit, so no meaning is added beyond the self-evident name.

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

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

The description gives a specific verb (score) and resource (a cold email subject line) and enumerates the exact dimensions scored: length, wording that hurts opens, and spam trigger words. This is clearly distinct from every sibling (SPF/DKIM/DMARC/blacklist checks), though it never explicitly names an alternative to distinguish itself.

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?

Usage is only implied: 'cold email subject line' signals the pre-send context, but there is no statement of when to reach for this versus check_cold_email or the other deliverability checks, and no prerequisites or exclusions are given.

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