email-deliverability

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, so the description carries minimal burden. It adds value by explaining the return structure ('ours', 'theirs', 'agree', parsed data) and stating no account is needed. However, it omits behavior on invalid input or rate limits, which are minor given the safety 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?

Two sentences delivered in a front-loaded manner: first sentence states the action and return, second explains purpose and no-account note. Every sentence is necessary; no fluff or redundancy. This is model conciseness for a tool 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?

Despite lacking an output schema, the description fully explains what the tool returns (verdict, theirs, agree, parsed headers/ envelope). Parameter descriptions in schema are complemented by the description. For a 4-parameter tool with 1 required and no nested objects, the description covers all necessary context for an agent to use 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 description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema: it explains 'helo' as SMTP HELO/EHLO, 'mailFrom' as envelope MAIL FROM, and 'senderIp' as overrides the IP from headers. The 'message' parameter is elaborated with examples of what to include. This extra context justifies a 4.

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

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

The description uses specific verbs ('re-verify') and a clear resource ('raw RFC 5322 email headers'), covering SPF, DKIM, DMARC, ARC. It distinguishes itself from sibling tools (DNS, blocklists, etc.) by focusing on email header analysis. The return values are explicitly stated, making 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?

The description states the tool is useful for spotting forged or mismatched auth results. While it doesn't explicitly exclude use cases or list alternatives, the context is clear given sibling tools are unrelated. However, some guidance on when not to use (e.g., if message is too short) would improve clarity.

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

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

Beyond annotations (destructiveHint=true), the description details that it creates/updates/deletes records and explains server-side validation to prevent arbitrary ops.

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?

Concise at 4 sentences, front-loads purpose and destructiveness, then workflow and auth – every sentence is essential.

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 preconditions, validation, auth, and follow-up action (re-scan). Lacks output description, but given no output schema, it's adequate.

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%; description adds context about passing ops verbatim and validation, enriching the schema descriptions.

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

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

The description clearly states it applies a DNS fix plan by publishing records, distinguishing it from sibling tools like get_dns_fix_plan that generate the plan.

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 specifies the two-step workflow (call get_dns_fix_plan first), indicates to pass connectionId and ops verbatim, and notes auth requirements.

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

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

The description adds behavioral context beyond annotations by detailing the targets (apex + MX-host IPs) and the methodology (authoritative queries). This complements the readOnlyHint and idempotentHint 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 concise sentence that front-loads the action and includes all necessary details without redundancy.

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

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

Despite no output schema, the description clearly states what is returned (listings, targets checked, issues), and the single parameter is fully described. The tool is self-contained and complete.

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

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

The description adds meaning beyond the schema by explaining that the 'domain' parameter is used to look up both apex and MX hosts, enhancing understanding of how the parameter is utilized.

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 a domain against DNS blocklists, specifying it handles both apex and MX-host IPs. This differentiates it from siblings like 'scan_domain' which may be broader.

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

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

The description explains it uses authoritative-side queries to avoid public-resolver false positives, providing context on when to use it for reliable results. However, it does not explicitly compare to alternatives or state when not to use it.

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

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

Annotations (readOnlyHint=false, destructiveHint=false) already signal a non-destructive write operation. The description adds context by noting the auth requirement (owner/admin API key) and that it enables another test. 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?

Two concise sentences with no wasted words. The first sentence states the primary action and items stored; the second adds enabling effect and prerequisite. Front-loaded with key information.

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

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

Given 3 parameters, no output schema, and existing annotations, the description covers the essential information: action, parameters' meaning, prerequisite, and enabled functionality. Could potentially mention the response type, but not required by rules.

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 parameters. The description adds value by explaining the provider values and that projectId is needed for GlockApps, beyond the schema descriptions.

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

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

The description clearly states it stores the provider and API key, enabling start_inbox_placement_test. It specifies the exact providers ('mailreach' or 'glockapps') and distinguishes from sibling tools like start_inbox_placement_test.

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 indicates when to use (setup for inbox placement testing) and the required scope (owner/admin API key with write/full scope). It does not explicitly exclude when not to use, but the context is clear given sibling tool 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 indicate non-read-only, non-destructive, non-idempotent. The description adds beyond annotations by noting data appears within ~24h after first sync and requiring specific API key scope. 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?

Three sentences with no redundancy: purpose, source, auth, timing. Front-loaded with main action.

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 all key aspects for a connection tool with no output schema. Could mention update behavior or error handling, but given simplicity it is adequate.

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 covers both parameters with descriptions (100% coverage). The description adds context for the key (source URL) but doesn't significantly enhance understanding 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 stores the SNDS key for daily reputation sync, with a specific verb ('store') and resource ('Microsoft SNDS key'). It distinguishes itself from sibling tools by focusing on connecting SNDS rather than scanning or analysis.

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: use when setting up SNDS sync. It includes prerequisites (owner/admin API key with write/full scope) and where to obtain the key, but does not explicitly state when not to use or compare to alternatives, though no sibling tool overlaps.

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 indicate mutation (readOnlyHint false). The description adds that it returns a channel id and signing secret for webhook, and requires specific API key scope. No annotation 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?

Description is concise (about 40 words), front-loaded with purpose, and every sentence adds value. No fluff.

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 4 parameters and no output schema, the description covers return values, auth requirements, and tool purpose. It could note if creation is synchronous, but overall complete.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant parameter-level details beyond what the schema provides; it mentions return values but not parameter semantics.

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

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

The description clearly states it creates a notification channel for alert delivery, lists supported types (webhook, Slack, etc.), and mentions return values. It distinguishes well from sibling tools, which focus on scanning, DNS, alerts, and domains.

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

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

The description explicitly requires an owner/admin API key with write or full scope, providing clear context on when to use. It does not mention alternatives or exclusions, but no sibling tool duplicates this functionality.

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 indicate a write operation; description confirms creation and adds details about required permissions and plan, going beyond the basic 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?

Two concise sentences; front-loaded with purpose and access, then return info and requirements. No unnecessary 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's simplicity (one parameter, no output schema), the description covers purpose, return values, and requirements well. Lacks error cases but is complete for the scope.

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 for the single parameter 'domain' is 100%, so the description adds minimal value beyond stating that the domain must be tracked and have a latest report.

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?

Clearly states the tool creates a read-only public share link for a tracked domain's latest report. It distinguishes itself from sibling tools, none of which create share links.

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?

Provides explicit requirements: owner/admin API key with write/full scope and a plan that includes public reports. Does not mention when not to use or alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: pdfUrl is an auth-gated endpoint using bearer token, and details the structured output. 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?

Two sentences: first enumerates report contents concisely, second explains pdfUrl and auth. Front-loaded purpose. No redundant information.

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

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

Simple input (1 param), rich annotations, and description fully covers output expectations without needing output schema. Tells agent exactly what to expect in the response.

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

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

Single parameter 'domain' with schema description coverage 100%. Description repeats schema info ('tracked in the account, e.g. example.com') without adding new semantics. 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?

Clearly states verb 'Return' and resource 'deliverability report for a tracked domain', listing specific components (score, grade, checks status, top issues, blocklist count, DMARC policy, pdfUrl). Distinguishes from siblings like get_deliverability_score and get_dmarc_summary by offering a comprehensive report with hand-out capability.

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: 'summarize a domain's posture or hand a client a report.' It mentions pdfUrl and auth requirements. Lacks explicit when-not-to-use alternatives, but the context is clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds the behavioral detail that it 'runs a fresh scan', implying no caching. 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, 14 words, clear and direct. 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?

No output schema, but the description only mentions 'overall deliverability score and letter grade' without specifying range or format. Could be more complete but adequate for a simple tool.

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

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

Schema coverage is 100% with parameter 'domain' described. Description adds no additional parameter meaning 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 returns 'overall deliverability score and letter grade for a domain' and notes it 'runs a fresh scan'. This distinguishes it from sibling tools like get_domain or scan_domain.

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

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

No guidance on when to use this tool vs alternatives. The description mentions it runs a fresh scan but does not provide context for usage or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by listing what the tool returns (volume, pass rate, etc.) and prerequisites, but doesn't disclose further behavioral traits (e.g., rate limits, error cases).

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: first states purpose and output, second gives prerequisites. No wasted words, front-loaded with key information.

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

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

For a simple tool with 2 parameters and no output schema, the description covers what it does, prerequisites, and outputs. It could mention error handling (e.g., if domain not found), but overall it is reasonably complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add new information about parameters beyond what the schema provides, only implied through the summary outputs.

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

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

The description clearly states the verb 'Summarize' and the resource 'DMARC aggregate (RUA) reports for a domain', and lists specific outputs (volume, pass rate, top sources, rua inbox). It distinguishes from sibling tools by focusing on DMARC summary, not DNS or deliverability.

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 prerequisites are given: domain must be added and plan must include DMARC ingest. While it doesn't contrast with siblings explicitly, the context of use is clear.

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

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

Beyond annotations (readOnlyHint=true, etc.), the description discloses that the operation is read-only, returns ops and manualReview items requiring human decisions, and requires specific conditions for the domain. This adds significant behavioral context.

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

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

The description is concise and well-structured: it starts with the action, specifies it's read-only, describes the output, and lists prerequisites. Every sentence adds value without redundancy.

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

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

For a single-parameter tool with no output schema, the description provides complete context: purpose, input requirements, output format, and relationship to sibling tools. It adequately covers what an agent needs to invoke it correctly.

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

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

The schema provides a basic description of the 'domain' parameter. The tool description enhances it by clarifying that the domain must be tracked and that the computation uses the latest scan and registrar connection, adding essential context.

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 explicitly states the tool computes DNS-record changes for fixing deliverability, names the inputs (domain, scan, registrar), and distinguishes from the sibling tool apply_dns_fix by noting the output is to be passed verbatim to that tool.

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

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

The description clearly indicates when to use this tool (before applying fixes), lists prerequisites (tracked domain, scan, registrar connection), and implicitly advises against use when prerequisites are unmet. It also explicitly names the alternative apply_dns_fix for the subsequent step.

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 idempotentHint=true. The description adds value by listing returned data, but does not disclose potential behavior (e.g., error handling, rate limits, or side effects). No contradictions with annotations.

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

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

A single sentence concisely lists all included data fields, uses no filler, and front-loads the core purpose. 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?

Given no output schema, the description enumerates key return components (domain record, scan findings, score history, alerts, Postmaster stats). Slight lack of structure or format details, but sufficient for a read-only tool with one parameter.

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 has 100% parameter description coverage for the single 'domain' parameter, so the description adds no additional meaning beyond 'domain name as tracked'. The 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 'Full detail for one tracked domain' and enumerates specific components (domain record, latest scan, per-check findings, score history, alerts, Postmaster stats), distinguishing it from sibling tools like list_domains (listing only) or get_dmarc_summary (specific check).

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

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

The description implies usage when needing comprehensive domain detail, but does not explicitly state when to avoid or prefer alternatives (e.g., check_blocklists, get_dmarc_summary). No prerequisites or contextual cues are provided.

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 provide readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds valuable context about the specific outputs (connected status, provider, test count, supported providers) without contradicting annotations. It does not mention rate limits or authentication but is still informative.

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

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

The description is two sentences long, each sentence adds value without redundancy. It is front-loaded with the main purpose and provides additional detail efficiently.

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 no output schema, the description sufficiently explains what the tool returns (connected status, provider, test count, supported providers). With 26 sibling tools, it distinguishes itself well. Could add more about when to use, but overall adequate.

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 are zero parameters, so the schema coverage is trivially 100%. The description adds meaning beyond the schema by explaining the tool's behavior and outputs. Baseline for 0 parameters is 4, and the description meets that.

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 reports whether a seed-list inbox-placement provider is connected, which provider, and how many tests have run. It also lists supported providers when not connected. This is a specific verb+resource and distinguishes it from siblings like connect_inbox_placement and get_inbox_placement_test.

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 is for checking connection status but does not explicitly state when to use it vs alternatives (e.g., before starting a test or instead of get_inbox_placement_test). No when-not-to-use or explicit context guidance is provided.

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 readOnly, idempotent, non-destructive; description confirms polling behavior and adds details about return values and timing. 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?

Two efficient sentences, front-loaded with action and return values. 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 tool simplicity (1 param, no output schema), description adequately explains purpose, return values, and usage preconditions. Complete for this use case.

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 already documents testId as UUID from start_inbox_placement_test (100% coverage). Description adds no additional parameter info, so baseline 3 applies.

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

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

Description clearly states it polls a test by testId and lists return values. However, it does not distinguish from the sibling get_inbox_placement_status, which may have similar 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?

Explicitly says to call after starting the test with start_inbox_placement_test. Provides clear context but no mention of alternatives or when not to use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and side effects. The description adds details about return content but does not introduce new behavioral traits beyond 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?

Two concise, informative sentences with no wasted words. The purpose is front-loaded, and each sentence adds 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?

The description enumerates all included elements (score, grade, distribution, alerts, attention domains, client breakdown), making the tool's output clear despite lacking an output schema. This is complete for a simple parameterless tool.

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

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

The tool has no parameters, and schema coverage is 100% (trivially). With 0 parameters, the description does not need to explain them; baseline 4 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 retrieves an org-wide deliverability rollup across monitored domains, listing specific included data (average score, grade distribution, alerts, etc.). This distinguishes it from sibling tools like get_domain or get_deliverability_report.

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 recommends use for 'at-a-glance portfolio health summary across an agency or multi-domain account.' While it doesn't list alternatives or exclusions, the context from sibling tools makes the usage intent clear.

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

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

Annotations already declare readOnly and idempotent. Description adds that the tool returns status (queued/running) and results as they finish, indicating polling behavior and incremental data availability.

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 front-loads purpose and lists returned data efficiently. Every phrase earns its place; 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?

Covers purpose, triggering tool, possible statuses, and result fields. Lacks explicit mention of pagination or default empty state, but for a polling tool with 1 param and no output schema, the description is fairly complete.

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

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

Only one parameter (jobId) with schema coverage 100%. Description repeats the schema's description ('returned by scan_domains_batch') but adds no additional semantic detail beyond what the schema already provides.

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?

Clearly states it polls an async batch scan started with scan_domains_batch and lists the data returned (status, completed count, per-domain results). Differentiates from siblings by specifying its use case and linking to the batch scan tool.

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

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

Explicitly says to use after scan_domains_batch, implying it is for polling progress. Does not mention alternatives or when not to use, but the context is clear enough for the intended workflow.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety profile is clear. The description adds value by listing the specific reputation fields returned, but does not contradict 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?

Two efficient sentences with no wasted words. Returns data fields are listed concisely.

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?

Although no output schema, the description enumerates the return fields. The tool is simple with no parameters, and the description covers its purpose, prerequisite, and data fields 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?

No parameters. Description adds no parameter info, but none is needed. Baseline 4 for zero-parameter tool.

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 returns per-IP reputation from Microsoft SNDS and lists specific data fields (GREEN/YELLOW/RED filter, complaint-rate band, spam-trap hits, message volume, block status). This distinguishes it from siblings like get_snds_status.

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

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

Explicitly states the prerequisite that SNDS must be connected and points to connect_snds / get_snds_status for setup. Provides clear when-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by detailing the returned information (sync time, status, IP counts) without contradicting 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?

A single sentence that efficiently communicates the purpose, scope, and usage order. No extraneous 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?

For a parameterless tool with good annotations, the description covers all necessary context: what it reports, when to use it, and its role relative to siblings. No gaps.

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 has zero parameters, so schema coverage is 100%. Per guidelines, baseline is 4. No parameter description is needed, and the description does not add parameter info beyond the schema.

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

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

The description uses specific verbs ('Report') and identifies the exact resource ('Microsoft SNDS status'). It lists concrete data points (connection status, sync time, IPs tracked, blocked count) and distinguishes from sibling tool 'get_snds_ip_stats' by recommending usage order.

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 this tool ('Use before get_snds_ip_stats to confirm the integration is live'), providing clear context for invocation and avoiding unnecessary calls to related tools.

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, destructiveHint=false, and idempotentHint=true, so the description's additional context (like alert types and defaults) is useful but not exhaustive. It does not disclose ordering, pagination behavior, or rate limits.

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 concise sentence that front-loads the purpose and includes examples in parentheses. No unnecessary 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?

While the tool is simple and annotations are helpful, the description does not indicate the output format or structure. It mentions defaults for resolved but not for limit or severity. For a tool without output schema, this leaves some gaps.

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 parameter descriptions. The description adds minimal extra meaning beyond schema, mainly noting the default for resolved parameters. With high coverage, this score 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 uses a specific verb ('List') and clearly identifies the resource ('deliverability alerts') with examples. It distinguishes itself from sibling tools by focusing on listing alerts rather than performing actions like check_blocklists or resolve_alert.

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 states defaults to open alerts, providing clear context for when to use it without parameters. However, it does not explicitly mention when not to use it or suggest alternatives, leaving some room for improvement.

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

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

Annotations already declare readOnly, non-destructive, idempotent. Description adds behavioral context by specifying returned fields (scan score, time, alert count), which is useful beyond 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, clear sentence that front-loads the purpose and key details. No unnecessary 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 no parameters and no output schema, description adequately covers basic functionality. Could mention ordering or that it returns all domains without filtering, but not critical.

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?

No parameters; baseline 4. Description does not need to add parameter info since schema is empty and 100% covered.

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 lists tracked domains with specific fields (scan score, last scan time, alert count). Distinct from siblings like get_domain (single domain) and list_alerts.

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?

Implicitly suggests use when needing an overview of all tracked domains, but no explicit guidance on when not to use or alternatives (e.g., get_domain for details).

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, destructiveHint=false, and idempotentHint=true, so the description's addition of ordering (most recent first) and content (status and scores) provides useful behavioral context beyond annotations. 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?

The description is a single sentence that is front-loaded with the action and result. It is concise and clearly structured, though it could be slightly more broken down.

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 no parameters, no output schema, and simple functionality, the description fully explains what the tool returns and in what order. No missing information.

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 zero parameters, schema description coverage is 100%. The description does not need to add parameter semantics, and the baseline for 0 params is 4.

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

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

The description clearly states the tool lists recent seed-list inbox-placement tests for the org, sorted most recent first, with status and scores. It uses a specific verb 'list' and resource 'inbox-placement tests', distinguishing it from siblings like get_inbox_placement_test (single test) and start_inbox_placement_test (create test).

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 for getting a list of tests, but does not explicitly state when to use this tool versus siblings like get_inbox_placement_test. However, the context of 'list' vs 'get' is clear enough for an agent to choose correctly.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds context about output fields and link to sibling tools, but does not substantially expand on behavioral traits 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?

Two sentences, each serving a clear purpose: first states what it lists, second gives usage guidance. Efficient and front-loaded.

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

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

With no output schema and no parameters, the description adequately covers purpose and usage. Could provide more detail on return structure but mentions fields. Sufficient for the tool's simplicity.

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?

No parameters exist; schema coverage is 100%. Baseline of 4 is appropriate as description adds no parameter details needed.

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?

Describes listing registrar connections with specific fields (provider, verification, last-used time) and mentions supported providers. Distinguishes from siblings by linking to detect-and-fix loop.

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: 'check whether the detect-and-fix loop is available before attempting it.' Mentions related tools get_dns_fix_plan and apply_dns_fix. Lacks explicit when-not-to-use but positive guidance is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's role is to add behavioral context. It does so by stating that scans are 'recent' and that the output includes specific fields, which is beyond the annotation information.

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 and contains no filler. Every word earns its place, efficiently conveying the tool's purpose and scope.

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 low complexity (2 simple, optional parameters; no output schema), the description is complete. It lists the returned fields in parentheses, compensating for the lack of output schema, and covers both use cases (all domains vs. one domain).

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 fully describes both parameters with high coverage. The description adds value by framing 'recent' (implied ordering) and by explaining the effect of the 'domain' parameter (narrowing to one domain). This goes beyond the schema's technical details.

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

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

The description clearly states it lists recent scans with specific fields (id, domain, run time, score) and distinguishes between listing all tracked domains or filtering by one domain. This distinguishes it from sibling tools like list_alerts or list_domains.

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

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

The description explicitly says when to use the tool—to list recent scans across all domains or for one domain. It provides clear context but does not explicitly mention when not to use it or contrast with alternatives like scan_domain.

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 set destructiveHint=true. The description adds context: 'DESTRUCTIVE and not reversible', explains deletion includes scan history, and specifies required API scope. This adds value 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?

Three sentences, front-loaded with the main action. No redundant words. Every sentence adds information (action, destructiveness, required scope, alternative).

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 1-parameter destructive tool with no output schema, the description covers the necessary context: what it does, that it's irreversible, required auth scope, and an alternative for the opposite operation. Complete.

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

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

Schema coverage is 100% (single parameter). The description provides an example ('e.g. example.com') which mirrors the schema description. No additional semantic meaning beyond what the schema already offers.

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

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

The description clearly states the action: 'Stop monitoring a domain and delete it (and its scan history) from the account.' It uses a specific verb+resource structure and distinguishes from siblings like scan_domain (add) and list_domains (read).

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

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

Explicitly says when to use this tool: when needing to stop monitoring and delete. Provides when-not-to-use: 'To ADD a domain, run scan_domain'. Also specifies required credentials: 'Requires an owner/admin API key with write or full scope.'

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?

Discloses idempotency (no-op on already-resolved) and auth requirements beyond annotations. No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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 concise sentences. Every word adds value, no repetition or 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?

Given no output schema, the description covers required info: mutation, idempotency, scope, and parameter behavior. Complete for a simple mutation tool.

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

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

Schema coverage is 100%, but description adds value by clarifying the default behavior of 'resolved' (true marks resolved, false reopens) and that the parameter is optional.

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 ('Mark an alert resolved or reopen') and resource ('alert'). It distinguishes from sibling tools like list_alerts and get_domain by specifying the mutation behavior.

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 mentions required API scope ('write/full scope') and idempotency ('no-op when already resolved'). Lacks explicit when-not-to-use but the scope requirement serves as a guideline.

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

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

The description states 'saves the scan to the domain history in your account' which is a side-effect write operation. However, annotations declare readOnlyHint=true, indicating no modifications. This is a direct 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?

Two sentences, front-loaded with the tool's purpose and key details. The first sentence is somewhat long but informative. Minimal waste.

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

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

Given no output schema, the description covers the essential return values (0-100 score and per-check findings) and the side-effect of saving history. Lacks details on scan duration or potential asynchronicity but sufficient for a simple tool with 2 parameters.

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

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

Schema coverage is 100% with both parameters described adequately. The description adds no additional detail beyond the schema, 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 lists all the checks performed (SPF, DKIM, DMARC, etc.) and states the output (0-100 score with per-check findings). It distinguishes from siblings like check_blocklists (only blocklists) and get_deliverability_score (likely just returns score without running scan).

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

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

The description mentions plan tier limitations ('full blocklist set on paid plans') but does not explicitly state when to use this tool versus alternatives like check_blocklists or get_dmarc_summary. Usage context is only implied.

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

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

The description adds significant behavioral context beyond annotations: async operation, immediate return, polling process, required API write scope, and that scans are not monitored/historical. No contradictions with annotations.

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

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

Four sentences, each adding value. Front-loaded with core purpose. No unnecessary words. Efficient and well-structured.

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 good annotations and a clear purpose, the description covers the main aspects. Minor omissions (e.g., what happens on partial failure) but overall sufficient for effective agent use.

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 describes the 'domains' parameter well. The description adds minor clarifications (up to 50 domains, example format). Since schema already does the heavy lifting, this merits a baseline 3.

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

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

The description clearly states the function: queue an asynchronous batch scan of up to 50 domains and get a jobId. It distinguishes from sibling tools like scan_domain and get_scan_job by highlighting the async batch nature and the avoidance of the synchronous 30s limit.

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 when to use this tool (async batch to avoid per-call limit) and how to follow up (poll get_scan_job). It mentions it's not saved to history, implying one-off use. It lacks explicit when-not-to-use, but the context is clear enough.

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

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

The description adds behavioral context beyond annotations: it explains the return values (testId, seeds, header) and the follow-up polling step. However, annotations already indicate non-read behavior, and description doesn't cover idempotency or side effects.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence adds value (purpose, return info, prerequisites). No unnecessary 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 simplicity (1 optional param, no output schema), the description adequately covers what the tool does, what it returns, and next steps. Missing minor detail about the header insertion, but overall complete.

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

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

The input schema has 100% coverage for the single optional parameter 'subject', so baseline is 3. The description does not add any further detail about this parameter 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 starts a seed-list inbox-placement test and distinguishes it from siblings like get_inbox_placement_test and list_inbox_placement_tests by mentioning polling for results.

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 prerequisites (connected inbox placement, API key scope) and indicates the post-action (poll get_inbox_placement_test). It does not explicitly state when not to use or list alternatives, but context is clear.

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