scan.mx Email Diagnostics

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

Annotations already mark readOnlyHint and openWorldHint. Description adds behavioral details: enumerates specific blocklists and clarifies it checks both the domain and its mail server IPs. No contradictions.

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?

Single sentence immediately conveys core purpose and lists all addressed blocklists. No redundant words.

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

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

Given an output schema exists, description covers what the tool does and which blocklists. It could optionally mention how results are returned, but likely sufficient.

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

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

Schema coverage is 100% with a clear domain description. The description adds context by linking the parameter to the tool's function (check domain and its mail server IPs on specific lists), adding value beyond 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 checks domain and mail server IPs against specific blocklists (Spamhaus, SpamCop, GBUdb, PSBL). It distinguishes from sibling tools that check other DNS records (DKIM, DMARC, etc.).

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?

No explicit when-to-use or when-not-to-use guidance is given. The differentiation from siblings is implicit based on the domain check context but lacks direct recommendations.

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

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

Annotations declare readOnlyHint and openWorldHint. Description adds meaningful behavior: probing common selectors by default and exact lookup with explicit selector. This goes beyond annotations, though could detail probed selectors.

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

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

Two sentences with efficient, front-loaded information. Every word adds value, no redundancy.

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

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

With output schema present, description covers the tool's purpose and parameter behavior comprehensively. Annotations and sibling context complete the picture.

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?

Description adds significant value beyond schema descriptions: it explains the default probing behavior when selector is omitted and the exact lookup when provided. This clarifies parameter interplay.

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 clearly states it checks DKIM signing keys for a domain, and explains two modes: probing common selectors or using an explicit selector. This distinguishes it from sibling tools like check_spf, check_dmarc, etc.

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?

Description indicates when to use the tool (to check DKIM keys) and how to customize with the selector parameter. It could explicitly mention alternatives but is clear enough for selection among siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds context by specifying what is checked (presence, policy strength, reporting). It does not contradict annotations and provides useful behavioral details 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 a single sentence of 14 words, front-loaded with the action and key details. It is concise with no wasted words.

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

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

Given the tool has an output schema (not shown) and is simple (1 parameter, read-only), the description covers the essential aspects: presence, policy strength, and reporting. It is complete enough for an agent to understand usage.

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

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

Schema coverage is 100% with a clear parameter description for 'domain' including an example and constraints. The tool description does not add significant new information about the parameter beyond what is in the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the action (check), the resource (domain DMARC policy at _dmarc), and the specifics (presence, policy strength, reporting). It distinguishes from sibling tools like check_spf or check_dkim by focusing on DMARC specifically.

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

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

The description implies the tool should be used to check DMARC policy but does not explicitly state when to use it over alternatives like check_spf or check_dkim. No exclusions or prerequisites are mentioned.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description's job is lighter. The description adds value by explaining the non-blocking SMTP probe behavior (states smtp_status values like 'pending', 'running', 'complete'), the capping logic for the letter grade, and that results appear in checks. 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 a single paragraph of moderate length, packed with utility. Every sentence contributes essential details (scope, output format, polling behavior). It is front-loaded with the core purpose. Could be slightly more structured (e.g., bullet points for checks), but no redundant or irrelevant 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 only 2 parameters, full schema coverage, an output schema (which explains return values), and read-only/open-world annotations, the description is complete: it covers what the tool does, what the output contains, how to handle the SMTP probe, and differentiates from siblings. Missing prerequisites (e.g., DNS access) are implied by the nature of the check.

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%, providing a baseline of 3. The description adds meaning beyond the schema by explaining the purpose of include_smtp (live probe, non-blocking, polling behavior) and the implications of the poll loop, which the schema's 'Non-blocking' note only hints at.

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 ('Run') and enumerates the resources checked (MX, SPF, DKIM, DMARC, DNS health, provider detection, blacklists). It clearly distinguishes from the sibling tools like check_mx or check_spf by naming this a comprehensive 'full email and DNS deliverability check' that aggregates all those checks.

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 clear context for when to use this tool—for a full deliverability check—and gives specific guidance on polling via the include_smtp parameter ('call this tool again...poll_after_seconds hints how long to wait'). While it doesn't explicitly exclude any siblings (e.g., 'use check_dkim if you only need DKIM'), the sibling differentiation is implicit in the comprehensive vs. single-check names.

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

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

Annotations already mark the tool as read-only and open-world. The description adds value by detailing what specific checks are performed (presence, hostnames, resolution, null-MX, misconfigurations), providing behavioral context 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 a single sentence that is front-loaded with the main action and then lists specific checks. No wasted words; concise and clear.

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 simplicity (one parameter, full schema coverage, output schema present, annotations clear), the description adequately covers the checks performed. Slightly lacking in detail about the output format, but overall complete for the context.

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

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

With 100% schema description coverage, the schema already documents the domain parameter. The description rephrases but does not add new semantic details about the parameter, so baseline score of 3 is appropriate.

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

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

The description clearly states it checks MX records of a domain, listing specific aspects: presence, hostnames, resolution, null-MX, and common misconfigurations. This distinguishes it from sibling tools that check other DNS 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?

The description implies usage when assessing email server configuration via MX records, but does not explicitly state when to use this tool versus alternatives, nor does it provide when-not or exclude conditions.

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

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

Annotations already indicate read-only and open-world hints. The description adds behavioral specifics by naming the four checks performed (presence, syntax, all qualifier, 10-lookup limit), which is useful context 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?

Single sentence with no redundancy. Front-loads the main action and lists specific checks efficiently. Every word 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?

With an output schema present, the description need not detail return values. It covers the core functionality (SPF policy checks) but could mention behavior on invalid domains or vague outcomes.

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

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

Schema coverage is 100% with a clear parameter description. The tool description does not add additional parameter-level meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states it checks the domain SPF policy, listing specific aspects (presence, syntax, all qualifier, 10-lookup limit). This distinguishes it from sibling tools like check_dkim or check_dmarc which target different DNS 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?

No explicit guidance on when to use this tool versus alternatives. The usage is implied by the tool name and description but lacks clear directives like 'use this when checking SPF validity' or mention of alternatives.

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