Scan, fix, verify and monitor DNS: SPF, DMARC, DKIM, propagation, health, expiry. Validated fixes.
Scored across 20 tools
Most tools have clearly distinct purposes, but the set includes several closely related pairs (check_record vs check_propagation, get_report vs scan_domain, and multiple DMARC record builders). The detailed 'Use this when' framing separates them well, so confusion is possible but unlikely.
Every tool follows a consistent lowercase snake_case verb_noun pattern (check_*, build_*, get_*, etc.), making the set highly predictable. Repeated verbs form coherent families, so naming is uniform throughout.
20 tools is at the heavy end, but the server covers a broad domain: monitoring, scanning, SPF/DKIM/DMARC analysis, record generation, propagation, WHOIS, and alerts. A few tools are functionally redundant, making it slightly over-stuffed rather than perfectly scoped.
Core workflows are well covered: scanning, per-record checks, DMARC/SPF/DKIM generation or validation, monitoring signup, alerts, and reports. Notable gaps include no way to list or remove monitored domains and no SPF fix record, though the latter appears to be an intentional design choice.
Add a domain to the signed-in user's DNS Doctor monitoring and return the ownership-check TXT record they must publish, plus where their DNS is hosted, a provider-specific guide link and, when their provider supports it, a one-click apply URL. Re-adding a domain they already monitor returns that domain rather than an error. Print every record host and value EXACTLY as returned — never rewrite, reformat or improve a record string. Nothing here is applied to anyone's DNS: a human publishes every record, and you must show them what you are about to add and get their approval before using any DNS tool of your own.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The domain, e.g. example.com. For add_monitored_domain: any registrable domain the linked account owns (re-adding one it already monitors returns that row). For check_domain_verification and get_domain_records: a domain this account already monitors, verified or still pending. Any other name — another account's, or one nobody monitors — is refused as not found; ownership is never disclosed. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the call as idempotent and non-destructive, and the description adds concrete behavioral detail: it returns the ownership-check TXT record, does not apply anything to DNS, requires human publication and approval, and instructs the agent to print record strings exactly as returned. This goes well beyond the annotation flags and prevents an agent from assuming it can or should modify DNS directly. No contradiction with readOnlyHint=false or idempotentHint=true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences cover the core action, return contents, idempotency, and the critical human-approval/exact-printing constraints, with the main verb and resource front-loaded in the first sentence. No filler or repetition of schema fields. Every sentence adds operational value.
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 an output schema, the description covers the required preconditions (linked account, owned domain), return contents, idempotent behavior, and the essential constraint that no DNS changes are applied by the tool. It also includes the exact-output and approval instructions that an agent needs to act safely. The only minor omission is an explicit 'when not to use', but the schema and sibling context make this manageable.
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 of the single required domain parameter, including ownership and re-add semantics, so the description does not need to add much. The description reinforces that the domain belongs to the signed-in user's account and that re-adding returns the existing domain, matching the schema. Baseline 3 is appropriate because the schema carries 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 opens with a specific verb and resource: 'Add a domain to the signed-in user's DNS Doctor monitoring' and enumerates the exact return payload (TXT record, hosting location, guide link, optional apply URL). This makes it distinct from sibling tools like check_domain_verification or get_domain_records, which operate on already-monitored domains. No ambiguity about what the tool does.
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 clearly frames when the tool is used — when a domain needs to be added to the signed-in user's monitoring — and the schema's domain parameter further distinguishes it from check_domain_verification and get_domain_records by noting those require an already-monitored domain. It does not explicitly name alternatives or state 'use X instead', but the context is sufficiently clear. The idempotent re-add behavior also tells agents they can safely call it even if the domain is already monitored.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks who can send email as their domain through SPF includes, or wants an SPF supply-chain or third-party sender audit. Audit a domain's SPF supply chain: walks every include and redirect it delegates to, and reports who can transitively send as it. Returns the resolved tree, per-node lookup attribution, the total authorized IPv4 address count, and typed findings — include_broken (a target that no longer publishes SPF, a PermError today), include_registrable (a delegated-to domain that does not exist, so a stranger who registers it becomes an authorized sender), include_expiring (registration lapsing within 30 days), pass_all_nested (a +all deep in the chain) and spf_record_unusable (the audited domain's OWN record is missing or does not parse, so there is no chain to walk). A domain we could not verify is reported as unverified and NEVER as available — never tell anyone a name is free on this tool's say-so unless the finding is include_registrable AND carries registry_confirmed: true. A registry_confirmed: false finding rests on DNS alone, which cannot tell an unsold name from one in redemption or on clientHold: report the mechanism as broken and the takeover risk as possible, but never as an available domain. Findings are risk analysis, not instructions: no SPF fix record exists here or anywhere else in DNS Doctor, because dropping a mechanism can silently de-authorize a real sender — relay the findings and let the domain's owner decide. Use count_spf_lookups instead when the question is only the 10-lookup limit.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The domain to check, e.g. example.com. Bare registrable names and subdomains both work; scheme, path or port do not belong here. Unicode names are accepted and normalized to punycode. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint, the description details how the audit works (resolved tree, per-node attribution, total authorized count), enumerates each finding type (include_broken, include_expiring, include_nested, unverified semantics), and discloses DNS limitations and the never-report-available rule. It is unusually transparent about failure modes and risk interpretation.
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 front-loads the trigger condition, then gives the mechanism, outputs, and safety caveats in a logical order. It is long, but every sentence adds a safety or semantic distinction that the agent needs; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one param and no output schema, the description must carry the behavioral contract. It does: it enumerates the five finding types, explains the unverified-vs-available semantic, states there is no fix record anywhere, and defers to count_spf_lookups for the 10-lookup question. The agent has everything needed to invoke it and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema already documents the single domain parameter at 100% coverage, including what is allowed and which forms work. The description adds no parameter-level detail; it focuses on behavior, which is appropriate given complete 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 opens with an explicit use condition ('Use this when the user asks...') and then defines the action precisely: audit a domain's SPF supply chain by walking includes and redirects and reporting who can send transitively. This clearly differentiates it from sibling tools like count_spf_lookups.
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?
States when to use the tool explicitly, names count_spf_lookups as the alternative for the 10-lookup limit question, and gives behavioral guardrails for interpreting unverified vs. available domains. This is full when-to-use/when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks how to move DMARC on from p=none, whether it is safe to tighten DMARC, or what the next DMARC policy step is for a domain (a scan can justify quarantine at most; reject needs monitoring evidence) — and after any report showing DMARC below enforcement. Return a validated DMARC enforcement-upgrade record for a domain. A scan can justify p=quarantine at MOST: the alignment signal (valid aligned SPF and a DKIM selector) is derived server-side — a caller can never assert it — and p=reject is unlocked only by aggregate-report evidence over a full reporting window (monitoring), never by a scan. record is null when there is no honest upgrade to offer (the domain does not exist; the DMARC lookup itself hit NXDOMAIN while the existence probe did not resolve; the DMARC lookup temp-failed; no alignment signal was observed at all, so a non-enforcing domain is told to publish rua= reporting first and an enforcing one is left alone; or the domain already applies a policy at least as strong as this scan justifies): a null record is the ANSWER, not a fault — relay rationale and never compose a record to fill the gap. A returned record also carries np=reject (the DMARCbis tag covering non-existent subdomains, which can have no legitimate aligned mail) unless the domain already publishes an np tag, which is preserved as-is. Present a returned record verbatim; a human must approve before publishing.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The domain to check, e.g. example.com. Bare registrable names and subdomains both work; scheme, path or port do not belong here. Unicode names are accepted and normalized to punycode. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses rich behavioral details: the alignment signal is derived server-side and cannot be asserted by the caller, null record is a valid answer and not a fault, np=reject is added unless already published, and a human must approve before publishing. This goes well beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is verbose but justified by the tool's conditional logic. It front-loads the trigger conditions and return purpose. However, it repeats the 'scan can justify quarantine at most' idea twice (once in the intro clause and once in the main body), which could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with significant conditional behavior, the description is complete: it covers when to use it, what the output record is, all null-record cases, the meaning of a null result, the np=reject behavior, and the human-approval requirement. The presence of an output schema means return fields need not be enumerated, but the semantic edge cases are fully handled here.
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 sole parameter 'domain' at 100% coverage, including examples, subdomain support, and punycode normalization. The description adds no new parameter-specific meaning beyond the schema; it references the domain generically. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Return a validated DMARC enforcement-upgrade record for a domain.' It also distinguishes this from generic DMARC generation/validation by specifying the exact scenarios (moving off p=none, tightening DMARC, next policy step, post-report below enforcement), which separates it from siblings like generate_dmarc_record and validate_dmarc_record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear when-to-use conditions ('Use this when the user asks how to move DMARC on from p=none...') and when-not conditions ('a scan can justify p=quarantine at MOST', 'p=reject is unlocked only by aggregate-report evidence'). It does not explicitly name alternative sibling tools, so it stops short of full alternative routing, but the guidance is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks how to protect a domain that sends no email from being spoofed. Build the three-record hardening pack that makes a NON-SENDING domain unusable for spoofing: a Null MX, a hard-fail SPF record, and a p=reject; np=reject DMARC record. For parked, redirect and brand-defensive domains only — NEVER for a domain that sends any mail, including transactional or one legacy system. Do NOT set confirm_no_mail on your own judgment or because a scan looked quiet: only the human who owns the domain can confirm it sends nothing, so ask them first. That flag unlocks the question, not the answer — the server re-checks DNS itself (existence, MX, SPF, DKIM selectors) and returns records: null with a rationale when it finds evidence of mail; relay that rationale rather than retrying. A lookup failure is reported as a failure, never as a pack. Publishing is the human's decision: present the records verbatim, in the order given, and let them approve each one.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The domain to check, e.g. example.com. Bare registrable names and subdomains both work; scheme, path or port do not belong here. Unicode names are accepted and normalized to punycode. | |
| rua_email | No | Mailbox to receive DMARC aggregate (RUA) reports, as a plain address like dmarc@example.com. Strongly recommended: without it nobody can see who sends as the domain. | |
| confirm_no_mail | Yes | Must be true, and only the HUMAN who owns the domain may decide it: it records their confirmation that this domain sends no email at all. Never set it on your own judgment or because a scan looked quiet — ask them. It unlocks the question only; the server independently re-checks DNS for evidence of mail and refuses when it finds any. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool readOnly/idempotent, and the description adds valuable behavioral context: the server re-checks DNS itself, returns null with rationale when mail evidence exists, reports lookup failures as failures, and never publishes anything. 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?
Dense and front-loaded with the purpose and a clear use-when. All sentences carry weight; the strong warnings are justified by the safety implications, though the length approaches the upper limit for a description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations and output schema, the description still adds necessary context: the three records to build, the DNS re-check behavior, the null-with-rationale response mode, failure handling, and the human-approval gate. Nothing an agent needs to invoke it safely is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema descriptions are already detailed, so the baseline is 3. The description adds a useful guardrail beyond the schema — do NOT set confirm_no_mail on your own judgment or because a scan looked quiet — and stresses that the flag only unlocks server-side verification. Minor param-level nuance keeps it 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?
Purpose is explicitly stated with a specific verb and resource: build a three-record hardening pack (Null MX, hard-fail SPF, p=reject DMARC) for non-sending domains. It clearly distinguishes from siblings by restricting use to parked/redirect/brand-defensive domains and excluding any mail-sending domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States exactly when to use it (non-sending protection), explicitly excludes any domain that sends mail, and gives a firm when-not-to-act rule about confirm_no_mail — only the human owner can confirm. It also tells the agent to ask the human first rather than deciding on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks whether DKIM is set up for a sending platform, whether a specific selector exists, or why DKIM fails. Check ONE specific DKIM selector on a domain — the exact selector the sending platform uses (e.g. google, s1), which a full scan's common-selector sweep may miss. Returns the verdict, its explanation, and the published key record when one resolves. No fix record is returned: a DKIM key is generated by the sending platform, so the fix is always to publish what that platform gives the owner.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The domain to check, e.g. example.com. Bare registrable names and subdomains both work; scheme, path or port do not belong here. Unicode names are accepted and normalized to punycode. | |
| selector | Yes | The DKIM selector to probe — the name before ._domainkey, e.g. 'google', 'selector1', or a dotted form like 's1.prod'. The sending platform's settings page names it; it is not guessable from the domain. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses the exact return contents: 'Returns the verdict, its explanation, and the published key record when one resolves.' It also explicitly states that no fix record is returned and why, adding behavioral context that complements the annotations 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?
The description is efficient and front-loaded. The first sentence establishes usage context, followed by the core action, return details, and a critical caveat about fix records. Every sentence earns its place; there is no fluff 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?
The tool has an output schema, so return structure is already defined; the description adds context on what those outputs mean (verdict, explanation, key record) and clarifies the absence of a fix record. It covers when to use it, how to call it, and what to expect, making it complete for an agent to invoke 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?
With 100% schema coverage, the baseline is 3, but the description significantly enhances parameter meaning. For domain, it clarifies acceptable formats ('Bare registrable names and subdomains both work; scheme, path or port do not belong here') and normalization ('Unicode accepted to punycode'). For selector, it explains the structure ('name before ._domainkey'), examples, and that it comes from the platform's settings page, providing actionable guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise action: 'Check ONE specific DKIM selector on a domain', with a clear resource (domain and selector). It distinguishes from other tools by noting it targets the exact selector the platform uses, which a full scan's common-selector sweep misses, and explicitly mentions it does not return a fix record, setting it apart from tools like scan_domain or build_* tools.
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 opens with explicit usage triggers: 'Use this when the user asks whether DKIM is set up... whether a specific selector exists, or why DKIM fails.' It also gives a key distinction from a full scan and explains that no fix record is returned because the fix is always platform-driven, guiding when NOT to expect a fix from this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether the ownership TXT record for a domain the user has added is visible yet, and mark it verified when it is. The result says WHICH outcome occurred and which nameservers were asked, so you can tell 'not published yet' from 'published with the wrong value' from 'our lookup did not complete' — a lookup that did not complete is TRANSIENT, never a verdict about their DNS. On success the result also carries the DMARC reporting record that turns monitoring on. Print every record host and value EXACTLY as returned — never rewrite, reformat or improve a record string. Nothing here is applied to anyone's DNS: a human publishes every record, and you must show them what you are about to add and get their approval before using any DNS tool of your own.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The domain, e.g. example.com. For add_monitored_domain: any registrable domain the linked account owns (re-adding one it already monitors returns that row). For check_domain_verification and get_domain_records: a domain this account already monitors, verified or still pending. Any other name — another account's, or one nobody monitors — is refused as not found; ownership is never disclosed. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as idempotent, non-destructive, and not read-only, and the description adds important behavioral nuance: it marks verified on success, distinguishes 'not published yet' from 'wrong value' from 'incomplete lookup', and states incomplete lookups are transient, not DNS verdicts. It also discloses that the tool never applies DNS changes itself and that a human publishes records, which is valuable beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average, but every sentence earns its place: purpose, outcome disambiguation, success side effect, exact-print instruction, and human-DNS safety caveat. It is front-loaded with the core action and structured so operational cautions follow the primary behavior without burying it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with an output schema, the description covers the essential runtime behavior: what triggers verification, how to interpret ambiguous results, what success carries, and what the agent must not do. Combined with the rich input schema and annotations, nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the only parameter, domain, and that schema description is unusually detailed about eligibility and refusal behavior. The tool description adds essentially only the phrase 'domain the user has added,' which adds little beyond the schema. Baseline 3 is appropriate when the schema carries the semantic weight.
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: check whether the ownership TXT record for a domain the user has added is visible yet, and mark it verified when it is. This clearly distinguishes the tool from generic record checks and states the mutating verification outcome. It also explains the result disambiguates failure modes, reinforcing the tool's exact purpose.
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 operational context: this is for verifying an added domain's ownership TXT record. The input schema reinforces when it is permitted by requiring the domain to already be monitored and explicitly refusing other names as not found. It does not explicitly compare against sibling tools like check_propagation or check_record, so it stops 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.
Use this when the user asks whether a DNS change has propagated globally, or why a record shows in one place and not another. Check whether a DNS change has propagated GLOBALLY: six vantage points (five owner-run probes across four continents plus this server's own resolver) each read the same name through several resolvers, and the grid plus a deterministic verdict comes back. Call it after the human publishes a record — you have ONE network vantage point, and a record that resolves for you can still be missing elsewhere. name is the exact name (www. is not stripped, _dmarc.example.com works), record_type is A|AAAA|CNAME|MX|TXT|NS, and the optional expected_value turns each cell into match or mismatch instead of agreement-only. Observation only: no record is ever composed here. A cell that did not answer is unavailable, which is NOT a negative result, and when fewer than three vantage points were reached the verdict downgrades to unknown — report vantage_reached of vantage_total rather than calling a name converged on partial coverage.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The exact DNS name to look up, e.g. example.com, www.example.com or _dmarc.example.com. It is used as given — a leading www. is NOT stripped and underscore labels are kept — so pass the name the record is actually published at, not the registrable domain. | |
| record_type | No | The record type to read at that exact name (default A). SPF and DMARC records are TXT — pass TXT with the right name rather than expecting a derived query name. | A |
| expected_value | No | Optional value the record should now hold, e.g. '1.2.3.4' or the new DMARC record text. Supply it and each cell is reported as match or mismatch against it; omit it and the check only reports whether the vantage points agree with each other. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Rich behavioral disclosure well beyond annotations. The 'Observation only: no record is ever composed here' statement reinforces readOnlyHint, while the description uniquely discloses that an unanswered cell is 'unavailable' and NOT a negative result, that the verdict downgrades to 'unknown' under partial coverage, and that the verdict is deterministic. These are operationally critical and absent from annotations; no contradiction 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?
Long but dense and front-loaded with the when-to-use clause. Every sentence carries operational weight — the unavailable semantics, partial-coverage downgrade, single-vantage-point warning, and exact-name handling all earn their place given the verdict complexity. No filler or tautology, though it could be trimmed slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Exceptionally complete for a complex tool. Covers the vantage-point topology, the verdict grid, match/mismatch mode, unavailable-cell semantics, the partial-coverage downgrade, and even the reporting instruction (report vantage_reached of vantage_total). With an output schema present to handle return values, nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description restates the record_type enum and reinforces the expected_value behavior (match/mismatch vs agreement-only), but adds little beyond what the schema already documents; the 'SPF and DMARC records are TXT' hint duplicates schema guidance. It does not compensate beyond the schema's thoroughness.
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 (DNS propagation) with an explicit scope: GLOBALLY across six vantage points. The purpose is clearly distinguished from sibling lookups like check_record by emphasizing the multi-vantage global verdict versus a single network point, and the use case 'why a record shows in one place and not another' pins down intent precisely.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Opens with explicit when-to-use conditions ('when the user asks whether a DNS change has propagated globally, or why a record shows in one place and not another') and adds timing guidance ('Call it after the human publishes a record'). It contrasts with the single-vantage-point limitation but does not name alternatives or give explicit when-not-to-use exclusions, leaving a small gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks whether a DNS change has landed, wants a DNS record looked up, or wants to verify a record they just published — or whenever answering needs the live value of a record. Check whether a DNS change has landed: reads the record from the domain's OWN nameservers (cache-free) and from two public caching resolvers, and reports whether they agree. kind is one of spf|dmarc|txt|mx|cname|a|aaaa — pass the kind, not a query name: dmarc reads TXT at _dmarc. and spf reads apex TXT, each filtered to the matching record. host prepends a label (txt, cname, a and aaaa only). Empty values mean the record is genuinely absent. When in_sync is false, max_wait_seconds is the largest remaining cached TTL — the wait before those resolvers refresh. This samples two resolvers, so never describe it as worldwide or as propagation coverage.
| Name | Required | Description | Default |
|---|---|---|---|
| host | No | Optional label to prepend to the domain (e.g. 'mail' to check mail.<domain>) — honored for txt, cname, a and aaaa only; spf, dmarc and mx derive their own query name. | |
| kind | Yes | Which record to read; the right query is derived from it — 'dmarc' reads TXT at _dmarc.<domain> filtered to v=DMARC1, 'spf' reads the apex TXT filtered to v=spf1, so don't prefix the domain yourself. | |
| domain | Yes | The domain to check, e.g. example.com. Bare registrable names and subdomains both work; scheme, path or port do not belong here. Unicode names are accepted and normalized to punycode. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it reads from the domain's own nameservers (cache-free) and two public caching resolvers, reports agreement via in_sync, and explains that empty values mean the record is genuinely absent. It also discloses the limitation that it samples only two resolvers and should not be described as worldwide. This is valuable behavioral disclosure beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-organized: it front-loads the trigger conditions, then explains the mechanism, then parameter semantics, then output interpretation. Every sentence earns its place, though it is longer than strictly necessary. The structure is logical and scannable.
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 (3 params, 7 enum kinds, derived query names, output semantics like in_sync and max_wait_seconds), the description covers all the essential context: when to use, how to pass parameters, how to interpret empty values, and the limitation of two resolvers. The output schema exists, so return values need not be explained in the description. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters well. The description adds value by explaining the derived query names for spf and dmarc, clarifying that kind should be the record type not a query name, and noting that host is honored only for txt, cname, a, and aaaa. This goes beyond the schema's descriptions and helps the agent construct correct arguments.
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-resource pairing: 'Check whether a DNS change has landed' and explicitly lists the user intents that should trigger this tool (asking whether a change landed, wanting a record looked up, verifying a just-published record). It also distinguishes itself from siblings by noting it reads from the domain's own nameservers and two public resolvers, which separates it from check_propagation and 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 explicit when-to-use guidance ('Use this when the user asks whether a DNS change has landed...') and also provides a when-not-to-use signal: 'never describe it as worldwide or as propagation coverage.' It also clarifies the kind parameter semantics so the agent doesn't pass a query name, and explains how host prepends a label. This is strong routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks about reverse DNS, PTR records, or FCrDNS for a mail server IP. Check one sending IP's forward-confirmed reverse DNS (FCrDNS): reads the IP's PTR record, then resolves that hostname back and reports whether it returns to the same IP. verdict is confirmed (the pair agrees — what receivers want to see), ptr_missing (the IP publishes no reverse record), or mismatch (a PTR that does not resolve back). A PTR on its own proves nothing, because the IP's operator writes its own reverse zone — only the forward confirmation is evidence, so never report a bare PTR as verified. The fix is always made by whoever controls the IP (the hosting or mail provider), never in the sending domain's own DNS. Pass a public IPv4 or IPv6 address.
| Name | Required | Description | Default |
|---|---|---|---|
| ip | Yes | The sending IP to check, IPv4 or IPv6. Must be a public address — private, loopback and CGNAT ranges have no meaningful reverse DNS and are refused. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it explains the FCrDNS verification logic, the three possible verdicts, and the caveat that a PTR alone proves nothing. It also discloses that private/loopback/CGNAT ranges are refused. This goes beyond the annotations without contradicting them.
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-organized: it front-loads the trigger condition, then explains the verification logic, verdicts, and caveats. Every sentence earns its place, though it is slightly long. The structure is logical and scannable.
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 a rich output schema, the description is complete. It covers when to use it, what it does, what the verdicts mean, the key caveat about PTRs, and the fix location. An agent has everything needed to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents the 'ip' parameter well. The description adds meaning by explaining what the IP is used for (the sending IP to check), the requirement that it be public, and the refusal of private/loopback/CGNAT ranges. This complements the schema rather than repeating 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 description states a specific verb ('check') and resource ('one sending IP's forward-confirmed reverse DNS'), and explicitly names the domain (reverse DNS, PTR records, FCrDNS). It distinguishes itself from siblings by focusing on a single IP's FCrDNS check, which is a unique operation among the listed tools.
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 says when to use it ('when the user asks about reverse DNS, PTR records, or FCrDNS for a mail server IP') and provides clear exclusions: it checks one IP, not multiple; it refuses private/loopback/CGNAT ranges. It also tells the agent what not to do ('never report a bare PTR as verified') and where the fix belongs, which is strong usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks about SPF 'too many lookups', the 10-lookup limit, an SPF PermError, or whether an SPF record is valid. Validate an SPF record and count what it costs. Returns record_valid (the record parses as RFC 7208 SPF), findings (per-term diagnostics), has_pass_all (a +all that authorizes the whole internet to send as this domain), multiple_all (more than one all, which makes everything after the first unreachable), the parsed terms, and the lookup count against the limit of 10 with over_limit/near_limit and the offending_mechanisms that push it over. Pass EXACTLY ONE of domain (resolves the published record and counts recursively through nested includes) or record (parses a pasted record, its own terms only). This is the SPF validator — there is no separate one. Diagnose-only: no SPF fix record is ever returned, because removing a mechanism can silently de-authorize a real sender — relay the findings and let the domain's owner decide what to drop.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No | Domain whose PUBLISHED SPF record should be resolved and counted recursively (nested includes cost lookups too). Pass exactly one of domain or record, never both. | |
| record | No | A pasted SPF record to parse instead of resolving one, e.g. 'v=spf1 include:_spf.google.com ~all'. Counts this record's own terms only. Pass exactly one of domain or record, never both. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool never returns a fix suggestion ('diagnose-only: no SPF fix record is ever returned'), which prevents the agent from assuming it can write/change records ('diagnose-only'), and explains why — silently de-authorizing real senders. This is deeply transparent behavior disclosure for a read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and comprehensive but a bit long/rambling. It lists many return fields that are already in the output schema accordion (record_valid, findings, terms, etc.), which is redundant with the output schema. Front-loads usage well but repeats the fix-record warning twice, and its structure is one long paragraph.
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?
Covers trigger conditions, behavior with both inputs, output semantics, and an important safety caveat. Combined with the output schema, an agent has everything needed 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?
The schema descriptions for `domain` and `record` already explain each parameter and the exclusivity. The description reinforces this by restating 'Pass EXACTLY ONE of domain or record, never both' and elaborating on what each mode does (resolves and counts recursively vs. parses own terms only). This adds semantic clarity 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 names a specific verb ('Validate', 'count'), a resource (SPF record), and the exact diagnostic use cases ('too many lookups', '10-lookup limit', 'PermError'). It is clearly distinguished from siblings like audit_spf, which is about broad checks, and build_spf_record, which constructs records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: when user asks about SPF lookups, PermError, or validity. Also states the alternative is not needed; there is no separate tool. The phrasing 'Use this when...' and 'Pass EXACTLY ONE of...' gives firm usage guidance. Sibling list reinforces this is the validator.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks to create, generate or write a DMARC record for a domain that has none. Build a DMARC record from scratch for a domain that has none, using a validating engine — never compose one yourself. policy is none|quarantine|reject; optional rua_email (aggregate-report destination), subdomain_policy, and strict_alignment. Every generated record carries np=reject — the DMARCbis tag for non-existent subdomains, which can have no legitimate aligned mail — independently of the p= you choose. The generated record is re-validated before it is returned. Present it verbatim; a human must approve before publishing.
| Name | Required | Description | Default |
|---|---|---|---|
| policy | Yes | The requested p= policy: 'none' monitors only, 'quarantine' sends failing mail to spam, 'reject' refuses it outright. Start at 'none' unless the domain's aggregate reports already justify enforcement. | |
| rua_email | No | Mailbox to receive DMARC aggregate (RUA) reports, as a plain address like dmarc@example.com. Strongly recommended: without it nobody can see who sends as the domain. | |
| strict_alignment | No | Set true to emit strict alignment (aspf=s adkim=s), requiring an exact domain match instead of the organizational-domain match. Leave false unless you know every sender aligns strictly. | |
| subdomain_policy | No | Optional sp= policy for subdomains when it should differ from the main p= policy. Omit to let subdomains inherit p=. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description goes beyond by revealing the generated record always carries np=reject regardless of p=, that the record is re-validated before return, and that it must be presented verbatim with human approval before publishing. These are behavioral details not available in the schema or 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 the key trigger condition front-loaded. Each sentence adds information: when-to-use, core behavior, parameter roles, special np=reject behavior, validation, and approval requirement. No filler, though slightly wordy given the structured schema already covers parameter descriptions.
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 annotations cover the read-only/idempotent nature, the description fully explains what the tool does, why, and the important constraints (np=reject, re-validation, human approval). Nothing an agent needs to invoke it correctly or interpret the result 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 descriptions already cover all parameters at 100%, so the baseline is 3. The description adds meaningful context, such as explaining that np=reject is independent of p=, and reinforces the purpose of rua_email and strict_alignment. This raises the value beyond mere schema repetition.
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 ('create, generate or write') and resource ('DMARC record for a domain that has none'), and differentiates from siblings like build_dmarc_upgrade and validate_dmarc_record by emphasizing building from scratch. The phrase 'never compose one yourself' further clarifies the tool's role as a validating engine, making its purpose unambiguous.
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 opens with 'Use this when the user asks to create, generate or write a DMARC record for a domain that has none,' which gives clear invocation guidance. It implies situations such as existing records or upgrades are handled elsewhere, though it does not explicitly name sibling tools or state when-not-to-use conditions. The context is clear enough for an agent to apply correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when a signed-in operator asks what changed on a monitored domain, or what the monitoring has flagged. Read the monitoring alert log for the domains the caller's account monitors, newest first. Requires an API token. Each row carries id, domain, type, check, summary, a deterministic detail map, created_at, email_sent_at, acknowledged_at and delivery_class — a 'dashboard_only' row was deliberately kept out of the digest mail, so an agent watching only the inbox would never see it; this log is the complete picture. PAGE DOWN BEFORE ADVANCING since: next_before is non-null exactly when older rows remain, and a caller that ignores it, takes a full page and moves its watermark to the newest row it saw drops every row it did not receive. since is an INCLUSIVE floor, so rows repeat rather than go missing — de-duplicate on id. READ-ONLY by decision: there is no ack and no delete here, because acknowledging an alert is the human's own triage on their dashboard and an agent that acks on their behalf silences a row they have never seen. Report what the log says and let them clear it.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Optional alert-type filter, e.g. 'record_changed'. An unknown value is rejected rather than silently returning an empty page — omit it unless you know the exact type. | |
| limit | No | Page size, 1..100 (default 50). Page down with `before` before you advance `since`, or you will skip every row you did not receive. | |
| since | No | Optional ISO-8601 timestamp: return alerts created at or after it (INCLUSIVE). Poll by storing the newest created_at you have seen and passing it back — rows repeat rather than go missing, so de-duplicate on id. | |
| before | No | The opaque cursor from a previous page's next_before, relayed verbatim to fetch the next older page. Never construct or edit one. | |
| domain | No | Optional filter to ONE of the account's verified monitored domains. Omit it for every domain the account monitors; an unowned or unknown name is refused as not found. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations by disclosing the read-only design rationale (no ack/delete) and the pagination pitfall (page down before advancing `since`). It also explains the inclusive `since` semantics and the delivery_class nuance (dashboard_only rows not in digest mail). This is substantial behavioral context that annotations alone do not provide, and it does not contradict the readOnlyHint, idempotentHint, or destructiveHint flags.
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?
While the description is lengthy, every sentence contributes essential usage, safety, or behavioral guidance. It is front-loaded with the purpose and usage, then covers fields, pagination, and read-only rationale in a logical order. There is no filler or redundant repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 optional parameters, pagination, auth requirement, and a rich output schema), the description covers everything needed: usage, auth, field semantics, pagination rules, and the read-only design. The output schema exists, so return-value details are already structured; the description adds the missing context about delivery_class and acknowledged_at. This is complete for safe and correct 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?
The input schema already has 100% coverage with detailed descriptions for every parameter, including the inclusive `since` floor and de-duplication instruction. The tool description reinforces these semantics but adds little new parameter-level meaning beyond restating the schema. Per the rubric, a baseline of 3 is appropriate when schema coverage is high.
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 a specific verb ('Read') and resource ('the monitoring alert log for the domains the caller's account monitors, newest first'). It also differentiates from all sibling tools, none of which relate to alert monitoring, so there is no ambiguity about which tool to select.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'when a signed-in operator asks what changed on a monitored domain, or what the monitoring has flagged.' It also notes the requirement of an API token and provides clear direction on read-only usage, advising to 'Report what the log says and let them clear it.' This leaves no doubt about the appropriate context and boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the records a domain the user monitors still needs: the ownership check while it is unverified, and once verified the DMARC reporting record plus whether we have OBSERVED that record published. Read-only: it issues nothing — if a verified domain comes back with no reporting record yet, call check_domain_verification once, which issues it. Print every record host and value EXACTLY as returned — never rewrite, reformat or improve a record string. Nothing here is applied to anyone's DNS: a human publishes every record, and you must show them what you are about to add and get their approval before using any DNS tool of your own.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The domain, e.g. example.com. For add_monitored_domain: any registrable domain the linked account owns (re-adding one it already monitors returns that row). For check_domain_verification and get_domain_records: a domain this account already monitors, verified or still pending. Any other name — another account's, or one nobody monitors — is refused as not found; ownership is never disclosed. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds meaningful behavioral context: it issues nothing, it reports whether the record was OBSERVED as published, and it requires printing record host/value EXACTLY as returned without rewriting. It also clarifies that records are published by a human, not by this tool. 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 front-loaded with the core purpose, followed by the key alternative and the critical output and safety constraints. Each sentence earns its place; there is no filler or repetition of the schema. The exact-printing instruction and the human-approval caveat are both essential for correct agent behavior.
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 tool with rich schema coverage, output schema available, and annotations covering read-only/idempotent safety, the description adds the remaining critical context: the conditional call to check_domain_verification, the observed-published distinction, exact-output handling, and the human-approval workflow. Nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter and the schema description covers it 100%, including what values are acceptable and how different callers relate to the domain. The description does not need to add parameter details; the schema already carries the full meaning. A baseline 3 is appropriate because the description adds no additional parameter-level 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 opens with a specific verb and resource: 'Read the records a domain the user monitors still needs', and then defines exactly which records are involved (ownership check, DMARC reporting record, observed-published status). This clearly distinguishes the tool from siblings like check_domain_verification, which issues records rather than reading them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool versus check_domain_verification: 'if a verified domain comes back with no reporting record yet, call check_domain_verification once, which issues it.' It also warns that no DNS changes should be made without human approval, which is practical usage guidance beyond the read-only annotations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when a signed-in operator asks whether a monitored domain is ready for the next DMARC step. Read the DMARC enforcement-readiness verdict for ONE domain the caller's account monitors, computed from its aggregate (RUA) report window. Requires an API token. Returns whether the domain is ready to step its policy up, the blockers that say why it is not, the window the verdict rests on, and next_record — the validated record for the next step, generated by the engine and null while blocked. THAT NULL IS AN ANSWER: relay the blockers and never compose a stronger record to fill the gap. Present a returned record verbatim; a human must approve it before it is published. Use this before proposing enforcement — a scan can show a domain's current policy, but only this evidence window can say whether tightening it would start rejecting real mail.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | One of the token account's VERIFIED monitored domains, e.g. example.com. Any other name — another account's, or one nobody monitors — is refused as not found; ownership is never disclosed. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite strong annotations (readOnly, idempotent, non-destructive), the description adds crucial behavioral context: next_record is null while blocked, null is itself an answer, agents must not compose a stronger record, returned records must be presented verbatim, and human approval is required before publishing. It also warns that unmonitored domains are refused without disclosing ownership.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the primary use case and remains dense without wasted words. Each sentence earns its place: usage, verdict scope, return fields, null semantics, record handling, and differentiation from scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with a rich input schema, full annotations, and an output schema present, the description covers everything the agent needs: when to call it, what it returns, what the null case means, and the safe workflow. 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 schema already thoroughly documents the domain parameter, including verified monitored domain requirement and not-found behavior. The tool description reinforces 'ONE domain' but does not add meaning beyond the schema's parameter documentation, 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 names a specific verb and resource: 'Read the DMARC enforcement-readiness verdict for ONE domain the caller's account monitors.' It clearly differentiates from the sibling scan tool by saying a scan can show current policy but only this evidence window can judge readiness.
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 states when to use the tool ('when a signed-in operator asks whether a monitored domain is ready for the next DMARC step') and when it is the right choice before proposing enforcement. It also contrasts with scan_domain, explaining that only this tool's evidence window can determine whether tightening would reject real mail.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this for the same questions as scan_domain when a recent report is enough (the cheap first look); use scan_domain when the state must be re-read now. Return the stored report for a domain, scanning once only if none exists yet — the cheap read, and the right default for a first look. Returns the same seven-check report as scan_domain (SPF, DKIM, DMARC, MX, DNS hardening, domain/TLS expiry, blacklist; each with a status, the observed record and any fixengine fix_record), including scanned_at so you can judge staleness yourself. Prefer scan_domain when you specifically need state re-read right now — for example after a DNS change.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The domain to check, e.g. example.com. Bare registrable names and subdomains both work; scheme, path or port do not belong here. Unicode names are accepted and normalized to punycode. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false, idempotentHint=true, and openWorldHint=true, and the description earns credit by explaining why: it may scan once if no report exists (the side effect behind readOnlyHint=false), repeated calls return the same stored report, and `scanned_at` lets the agent judge staleness. It also reveals the cost profile ('cheap read') and that the world changes over time, whichcoheres with openWorldHint. No contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the critical routing decision and delivers high-value information about the report's contents and staleness signal. However, it is mildly repetitive: the cheap look / cheap read / right default for a first look triad restates the same idea, and the final 'Prefer scan_domain' sentence largely repeats the opening conditional.
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 a rich output schema and meaningful annotations, the description covers everything an agent needs: what triggers a scan, what the wrapper includes (seven checks plus `scanned_at`), and when to pick the sibling instead. The presence of an output schema means the return structure need not be spelled out, and the staleness caveat is explicitly delegated to the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single `domain` parameter is already fully documented in the schema (registrable names and subdomains both work, no scheme/path/port, unicode normalized to punycode). The description adds no per-parameter meaning beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens by placing the tool relative to scan_domain and then states a specific action: 'Return the stored report for a domain, scanning once only if none exists yet.' It names the concrete resource (the seven-check domain report) and enumerates the checks (SPF, DKIM, DMARC, MX, DNS hardening, expiry, blacklist), which makes the operation unmistakable and distinct from sibling tools.
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 routing rules in both directions: use get_report when a recent report is enough, use scan_domain when the state must be re-read now, with a concrete example ('after a DNS change'). It states the selection condition, the alternative, and the trade-off (cheap vs. fresh), leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks who owns a domain, when it expires, which registrar or nameservers it has, whether it is registered, or whether a transfer or delete lock is set — the WHOIS question. Read a domain's registration from the registry over RDAP: registrar (with IANA id), registration/last-changed/expiry dates, EPP status codes verbatim, nameservers, whether the delegation is DNSSEC-signed, and an abuse contact where one is published — redacted: true is the post-GDPR norm, not a failure. Observation only: no record is composed, and pendingDelete or a near expiry is something to REPORT, never advice to buy. status is registered | not_registered | unknown, and unknown is NOT absence — the registry did not answer, and reason says whether that was a rate limit, a timeout, a registry error, or a TLD with no RDAP service. Never tell anyone a name is free unless status is exactly not_registered.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The domain to check, e.g. example.com. Bare registrable names and subdomains both work; scheme, path or port do not belong here. Unicode names are accepted and normalized to punycode. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds critical behavioral context beyond those: 'Observation only: no record is composed,' 'redacted: true is the post-GDPR norm, not a failure,' and the meaning of status=unknown ('NOT absence — the registry did not answer, and reason says whether that was a rate limit, a timeout, a registry error, or a TLD with no RDAP service'). This is exactly the kind of non-obvious behavior an agent needs to know.
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 trigger conditions, then the data returned, then the behavioral caveats. It is longer than the HIGH calibration example, but the tool's semantics (RDAP, GDPR redaction, unknown status) genuinely require this much explanation. 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 a rich output schema, the description covers everything an agent needs: what the tool returns, how to interpret redaction, how to interpret unknown status, and what not to do with the results. The output schema exists, so return-value details need not be repeated. The sibling list confirms this tool is the WHOIS/RDAP specialist, and the description makes that role unambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the domain parameter well. The description adds value by clarifying that bare registrable names and subdomains both work, that scheme/path/port do not belong, and that Unicode names are normalized to punycode. This goes beyond the schema's own description, so a 4 is warranted.
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 ('Read a domain's registration from the registry over RDAP') and enumerates the exact data returned: registrar, dates, EPP status codes, nameservers, DNSSEC flag, abuse contact. It also explicitly frames the tool as the answer to 'the WHOIS question,' which distinguishes it from sibling tools like check_record or scan_domain. This is a model of purpose clarity.
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-to-use guidance: 'Use this when the user asks who owns a domain, when it expires, which registrar or nameservers it has, whether it is registered, or whether a transfer or delete lock is set.' It also provides exclusions: 'Never tell anyone a name is free unless status is exactly not_registered' and 'pendingDelete or a near expiry is something to REPORT, never advice to buy.' This is strong usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user uploads or pastes a DMARC aggregate (RUA) XML report and asks what it says. Parse ONE DMARC aggregate (RUA) report into readable per-source aggregates: who sent mail as the domain, how much, and what share was SPF/DKIM aligned. Pass the file's bytes base64-encoded in content_base64 (XML, .gz or .zip; up to 2 MiB decoded) with an optional filename. Nothing is stored — the report is parsed and discarded.
| Name | Required | Description | Default |
|---|---|---|---|
| filename | No | Optional original attachment filename, recorded in logs only — format detection is content-based, so this changes nothing about parsing. | |
| content_base64 | Yes | One DMARC aggregate (RUA) report file, base64-encoded: the .xml, .xml.gz or .zip attachment exactly as received, up to 2 MiB decoded. Encode the file bytes — do not paste raw XML here. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states that nothing is stored and the report is parsed and discarded, and it discloses supported formats and the 2 MiB decoded size limit. With readOnly and idempotent hints already present, this adds meaningful behavioral detail without redundantly repeating the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences front-load the trigger and purpose, then pack constraints and side-effect disclosure with zero filler. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the input encoding, accepted formats, size constraint, optional filename, the single-report scope, the output shape, and the no-storage guarantee. Nothing is needed to call it correctly that is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents base64 encoding, formats, size limits, and the filename param. The description restates these constraints but doesn't add substantial meaning beyond the schema, so a mid score 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?
Description states a specific verb ('Parse ONE DMARC aggregate RUA report'), a precise resource (DMARC aggregate/RUA XML report), and exactly what output results (per-source aggregates with volume and SPF/DKIM alignment). The 'Use this when user uploads or pastes... asks what it says' phrasing clearly distinguishes it from sibling tools that build or monitor DMARC records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit trigger condition is given: use when the user uploads or pastes a DMARC aggregate report and asks what it says. No explicit when-not-to-use or alternative tool is named, but the trigger is specific enough to route the agent correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks to check, audit, diagnose or troubleshoot SPF, DKIM, DMARC, email authentication, email deliverability DNS, why their mail lands in spam, MX, DNS health, blacklist status, or domain/SSL expiry for a domain, or wants to fix what a scan finds (fix records for DMARC and DNS; SPF is diagnose-only) — or whenever a conversation turns to a specific domain's email or DNS setup. Force a fresh scan of a domain and return its full report: seven deterministic checks — SPF, DKIM, DMARC, MX, DNS hardening, domain/TLS expiry and blacklist listing — each with a status (pass/warn/fail/info/temperror), the observed record, and a fixengine-generated fix_record where one exists. Explanations are cache-first. A repeat scan of the same domain within the dedup window (about a minute) reuses the stored report rather than re-reading DNS, so scanned_at may predate a DNS change you just made — when you are verifying an edit, check scanned_at and call again after the window rather than treating an unchanged report as the new state. Use this when you need current state; use get_report when a recent cached answer will do.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The domain to check, e.g. example.com. Bare registrable names and subdomains both work; scheme, path or port do not belong here. Unicode names are accepted and normalized to punycode. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are sparse (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). The description adds crucial behavioral detail: the cache-first dedup window of about a minute, that scanned_at may predate a DNS change, and how to handle verification. It also notes fix_record generation and SPF being diagnose-only. 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 long but each sentence earns its place: trigger conditions, the seven checks, cache behavior, and sibling differentiation. It's front-loaded with the usage trigger, and while it could be slightly tighter, the length is justified by the tool's complexity and the need to convey the dedup caveat.
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 (seven checks, cache semantics, fix_record, sibling overlap), the description covers all necessary aspects: what it does, what the report contains, how to interpret stale data, and when to use an alternative. An output schema exists, so return-value details are covered there, leaving the description to handle selection and behavioral caveats, which it does completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'domain' already has a thorough schema description (coverage 100%) covering examples, subdomains, excluded scheme/path/port, and Unicode normalization. The tool description adds nothing about the parameter beyond what the schema already states, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('scan') and a specific resource ('a domain'), and enumerates the seven deterministic checks it performs. It clearly distinguishes itself from sibling tools like get_report by explicitly framing itself as the fresh-scan tool, so an agent can tell them apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an exhaustive list of trigger phrases ('check, audit, diagnose, troubleshoot...') and explicitly contrasts with get_report: 'Use this when you need current state; use get_report when a recent cached answer will do.' This is a textbook example of when/when-not guidance with named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants DMARC monitoring, RUA report monitoring, new-sender monitoring, email-authentication alerts, ongoing DNS monitoring, or to start a DNS Doctor trial — and at the end of any scan that found issues on a domain the user owns. Return a sign-up link to give to the HUMAN who owns a domain, so they can start monitoring it themselves. Nothing is created and no email is sent by this call: the returned signup_url opens a page that explains monitoring and asks them to sign in there themselves; the domain is carried over to their dashboard, already filled in, only after that, and monitoring itself starts once they prove ownership with a TXT record. Print the returned signup_url verbatim as a clickable markdown link on its own line — never paraphrase, shorten, or describe it without printing it — and relay message; never sign in on their behalf.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The domain to check, e.g. example.com. Bare registrable names and subdomains both work; scheme, path or port do not belong here. Unicode names are accepted and normalized to punycode. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior, and the description adds valuable process detail: the signup_url opens a page, the domain is carried over only after the human signs in, monitoring begins only after TXT ownership verification, and the agent must not sign in on their behalf. This goes well beyond what annotations 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?
All sentences carry necessary information and the trigger conditions are front-loaded. However, the description is a dense, run-on paragraph with many embedded clauses; it is appropriately sized but could be easier to scan with clearer separation between usage, behavior, and output instructions.
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 the trigger, target user, lack of side effects, deferred sign-up flow, TXT verification requirement, and exact output formatting instructions including relaying message and printing signup_url verbatim. With an output schema present, no essential information is missing for an agent to invoke this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter domain is already fully documented in the schema with examples, allowed forms, disallowed parts, and punycode normalization, so schema coverage is 100%. The description reinforces ownership context but adds no new parameter syntax or format information 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 clearly states the tool's job: return a sign-up link for a human domain owner to start DMARC/RUA/new-sender/DNS monitoring or a DNS Doctor trial. It also distinguishes this from direct action by explicitly saying nothing is created and no email is sent, which separates it from siblings like add_monitored_domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use conditions: whenever the user requests any listed monitoring type, or at the end of a scan that found issues on a domain the user owns. It stops short of naming alternatives or stating when not to use the tool beyond 'never sign in on their behalf,' so it lacks full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user pastes a DMARC record and asks whether it is valid, correct or safe. Validate a pasted DMARC record: parsed tags, level'd findings, and whether it is valid. No DNS lookup — pass the record string itself. upgrade_record previews a stronger policy and is capped at p=quarantine: a pasted record carries no alignment evidence, and p=reject is unlocked only by aggregate-report evidence over a full reporting window (monitoring), never by a scan. Present any returned record verbatim.
| Name | Required | Description | Default |
|---|---|---|---|
| record | Yes | The DMARC record text to validate, e.g. 'v=DMARC1; p=none; rua=mailto:reports@example.com'. The record value only — not the _dmarc hostname it is published at. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: it does not perform DNS lookup, it returns parsed tags and level'd findings, and it instructs to present any returned record verbatim. It also explains a policy nuance about p=reject being unlocked only by aggregate-report evidence, which is useful for setting expectations. Minor gap: it doesn't explicitly state whether the tool can return errors for malformed input, but the schema and output schema likely cover that.
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 concise and front-loaded with the primary use case. It packs a lot of useful information into a few sentences. The only slight inefficiency is the detailed policy explanation about p=reject and aggregate-report evidence, which is relevant but could be seen as slightly verbose for a tool description. Overall, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a single parameter, a rich output schema, and clear annotations, the description is complete. It covers what the tool does, how to invoke it, what it does not do, and how to handle the returned record. An agent has everything needed to select and call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the `record` parameter well. The description adds extra meaning by clarifying that the record value only should be passed, not the _dmarc hostname, and by giving an example. This goes beyond the schema's description and helps prevent a common mistake.
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 purpose: validate a pasted DMARC record and report parsed tags, level'd findings, and validity. It explicitly distinguishes itself from related tools like `upgrade_record` and `scan_domain` by noting it does not perform DNS lookup and takes the record string 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?
The description provides explicit when-to-use guidance: 'Use this when the user pastes a DMARC record and asks whether it is valid, correct or safe.' It also gives exclusions: 'No DNS lookup — pass the record string itself.' It names an alternative (`upgrade_record`) and explains when that tool is appropriate, which helps an agent choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
add_monitored_domain1 field changedInput schema / properties / domain / descriptionPrevious value: -"One of the token account's VERIFIED monitored domains, e.g. example.com. Any other name — another account's, or one nobody monitors — is refused as not found; ownership is never disclosed."New value: +"The domain, e.g. example.com. For add_monitored_domain: any registrable domain the linked account owns (re-adding one it already monitors returns that row). For check_domain_verification and get_domain_records: a domain this account already monitors, verified or still pending. Any other name — another account's, or one nobody monitors — is refused as not found; ownership is never disclosed."check_domain_verification1 field changedInput schema / properties / domain / descriptionPrevious value: -"One of the token account's VERIFIED monitored domains, e.g. example.com. Any other name — another account's, or one nobody monitors — is refused as not found; ownership is never disclosed."New value: +"The domain, e.g. example.com. For add_monitored_domain: any registrable domain the linked account owns (re-adding one it already monitors returns that row). For check_domain_verification and get_domain_records: a domain this account already monitors, verified or still pending. Any other name — another account's, or one nobody monitors — is refused as not found; ownership is never disclosed."get_domain_records1 field changedInput schema / properties / domain / descriptionPrevious value: -"One of the token account's VERIFIED monitored domains, e.g. example.com. Any other name — another account's, or one nobody monitors — is refused as not found; ownership is never disclosed."New value: +"The domain, e.g. example.com. For add_monitored_domain: any registrable domain the linked account owns (re-adding one it already monitors returns that row). For check_domain_verification and get_domain_records: a domain this account already monitors, verified or still pending. Any other name — another account's, or one nobody monitors — is refused as not found; ownership is never disclosed."add_monitored_domaincheck_domain_verificationget_domain_recordslookup_registrationcheck_propagationget_alertsget_readinessaudit_spf_includesbuild_parked_domain_recordscheck_dkim_selector1 field changedInput schema / properties / selector / descriptionPrevious value: -"The DKIM selector to probe — the single DNS label before ._domainkey, e.g. 'google' or 'selector1'. The sending platform's settings page names it; this is not guessable from the domain."New value: +"The DKIM selector to probe — the name before ._domainkey, e.g. 'google', 'selector1', or a dotted form like 's1.prod'. The sending platform's settings page names it; it is not guessable from the domain."parse_dmarc_report1 field changedInput schema / properties / filename / descriptionPrevious value: -"Optional original attachment filename (e.g. 'google.com!example.com!....xml.gz') — improves format detection and error messages, changes nothing else."New value: +"Optional original attachment filename, recorded in logs only — format detection is content-based, so this changes nothing about parsing."build_dmarc_upgrade1 field changedInput schema / properties / domain / descriptionAdded value: +"The domain to check, e.g. example.com. Bare registrable names and subdomains both work; scheme, path or port do not belong here. Unicode names are accepted and normalized to punycode."check_dkim_selector2 fields changedInput schema / properties / domain / descriptionAdded value: +"The domain to check, e.g. example.com. Bare registrable names and subdomains both work; scheme, path or port do not belong here. Unicode names are accepted and normalized to punycode."Input schema / properties / selector / descriptionAdded value: +"The DKIM selector to probe — the single DNS label before ._domainkey, e.g. 'google' or 'selector1'. The sending platform's settings page names it; this is not guessable from the domain."check_record3 fields changedInput schema / properties / domain / descriptionAdded value: +"The domain to check, e.g. example.com. Bare registrable names and subdomains both work; scheme, path or port do not belong here. Unicode names are accepted and normalized to punycode."Input schema / properties / host / descriptionAdded value: +"Optional label to prepend to the domain (e.g. 'mail' to check mail.<domain>) — honored for txt, cname, a and aaaa only; spf, dmarc and mx derive their own query name."Input schema / properties / kind / descriptionAdded value: +"Which record to read; the right query is derived from it — 'dmarc' reads TXT at _dmarc.<domain> filtered to v=DMARC1, 'spf' reads the apex TXT filtered to v=spf1, so don't prefix the domain yourself."check_reverse_dns1 field changedInput schema / properties / ip / descriptionAdded value: +"The sending IP to check, IPv4 or IPv6. Must be a public address — private, loopback and CGNAT ranges have no meaningful reverse DNS and are refused."count_spf_lookups2 fields changedInput schema / properties / domain / descriptionAdded value: +"Domain whose PUBLISHED SPF record should be resolved and counted recursively (nested includes cost lookups too). Pass exactly one of domain or record, never both."Input schema / properties / record / descriptionAdded value: +"A pasted SPF record to parse instead of resolving one, e.g. 'v=spf1 include:_spf.google.com ~all'. Counts this record's own terms only. Pass exactly one of domain or record, never both."generate_dmarc_record4 fields changedInput schema / properties / policy / descriptionAdded value: +"The requested p= policy: 'none' monitors only, 'quarantine' sends failing mail to spam, 'reject' refuses it outright. Start at 'none' unless the domain's aggregate reports already justify enforcement."Input schema / properties / rua_email / descriptionAdded value: +"Mailbox to receive DMARC aggregate (RUA) reports, as a plain address like dmarc@example.com. Strongly recommended: without it nobody can see who sends as the domain."Input schema / properties / strict_alignment / descriptionAdded value: +"Set true to emit strict alignment (aspf=s adkim=s), requiring an exact domain match instead of the organizational-domain match. Leave false unless you know every sender aligns strictly."Input schema / properties / subdomain_policy / descriptionAdded value: +"Optional sp= policy for subdomains when it should differ from the main p= policy. Omit to let subdomains inherit p=."get_report1 field changedInput schema / properties / domain / descriptionAdded value: +"The domain to check, e.g. example.com. Bare registrable names and subdomains both work; scheme, path or port do not belong here. Unicode names are accepted and normalized to punycode."parse_dmarc_report2 fields changedInput schema / properties / content_base64 / descriptionAdded value: +"One DMARC aggregate (RUA) report file, base64-encoded: the .xml, .xml.gz or .zip attachment exactly as received, up to 2 MiB decoded. Encode the file bytes — do not paste raw XML here."Input schema / properties / filename / descriptionAdded value: +"Optional original attachment filename (e.g. 'google.com!example.com!....xml.gz') — improves format detection and error messages, changes nothing else."scan_domain1 field changedInput schema / properties / domain / descriptionAdded value: +"The domain to check, e.g. example.com. Bare registrable names and subdomains both work; scheme, path or port do not belong here. Unicode names are accepted and normalized to punycode."start_monitoring_signup1 field changedInput schema / properties / domain / descriptionAdded value: +"The domain to check, e.g. example.com. Bare registrable names and subdomains both work; scheme, path or port do not belong here. Unicode names are accepted and normalized to punycode."validate_dmarc_record1 field changedInput schema / properties / record / descriptionAdded value: +"The DMARC record text to validate, e.g. 'v=DMARC1; p=none; rua=mailto:reports@example.com'. The record value only — not the _dmarc hostname it is published at."check_record1 field changedInput schema / properties / kind / enumAdded value: +[
+ "spf",
+ "dmarc",
+ "txt",
+ "mx",
+ "cname",
+ "a",
+ "aaaa"
+]generate_dmarc_record2 fields changedInput schema / properties / policy / enumAdded value: +[
+ "none",
+ "quarantine",
+ "reject"
+]Input schema / properties / subdomain_policy / anyOfPrevious value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "enum": [
+ "none",
+ "quarantine",
+ "reject"
+ ],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]check_dkim_selectorcheck_recordcheck_reverse_dnscount_spf_lookupsgenerate_dmarc_recordparse_dmarc_reportvalidate_dmarc_recordenroll_monitoring_trialstart_monitoring_signupMonitor and manage email authentication (SPF, DKIM, DMARC, MTA-STS, BIMI) for your domains.
Scan and fix a domain's email deliverability (SPF, DKIM, DMARC, MTA-STS, BIMI, DNS blocklists).
Check SPF/DKIM/DMARC/BIMI, blacklists, SMTP/IMAP; DNS lookups; generate email DNS records.
DNS and email security scanner with 80 MCP tools for SPF, DMARC, DNSSEC, SSL, and brand audits.
Add one secure layer between your agents and this server.
