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

The annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond that: the request body is processed in-memory and not stored, no authentication is required, and the analysis includes external checks such as IP reputation. This fully supports and reinforces the annotation hints.

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 tightly written. The opening sentence immediately communicates purpose and scope, the second sentence defines the parameter, and the final sentence gives usage guidance and a safety guarantee. No sentence is wasted.

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

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

There is no output schema, so the description carries the full burden of explaining what the tool returns. It does so clearly: parsed verdicts, reputation checks, spam triggers, a 0-100 score, and AI-assisted suggestions. It also includes relevant caveats like max size, in-memory processing, no auth, and when to prefer the sibling 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 input schema already documents rawEmail thoroughly, including type, required flag, and max length, so the schema coverage is 100%. The description adds mild reinforcement by stating that rawEmail must contain full headers and body and by repeating the 500KB limit, but it does not add substantive 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 specifies a clear verb and resource: read-only analysis of a pasted raw RFC-5322 MIME email source. It enumerates concrete parsed elements and outputs (verdicts, reputation/blacklist status, spam score, fix suggestions). It also distinguishes itself from create_email_test by naming when each should be used.

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: debug a specific failing email when the user can paste raw source. It also names the alternative: use create_email_test when the user can resend the email. This is clear and directly actionable.

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, openWorld, idempotent, and non-destructive; the description adds useful context by stating it 'fetches the page once over HTTPS, nothing is changed' and explaining the read-only network behavior. It also discloses outcome details such as HTTPS verification and the returned report content, going beyond the structured hints.

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 serves a purpose: it defines the security headers, states read-only behavior, enumerates the returned report contents, and provides a direct alternative. The main purpose is front-loaded in the first sentence, and the structure flows logically from what to output to when to use 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?

With no output schema, the description fully compensates by enumerating exactly what is returned: HTTPS status, per-header presence and value, missing headers, recommended best-practice config, and ready-to-paste server snippets. It also covers usage guidance and the single parameter's role, making the tool self-contained for an AI 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?

The schema has 100% coverage for the single `domain` parameter, including the format restriction 'Domain name only, e.g. example.com (no URL, path, or port)'. The description does not add further parameter semantics, so the schema already does the heavy lifting and a baseline 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 opens with a specific verb and resource: 'Scan a live website and report which HTTP security headers it currently sends.' It clearly distinguishes itself from the sibling `generate_security_headers` by focusing on auditing a real site rather than generating a config.

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

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

Explicit guidance is given: 'Use this to audit a real site's header posture; use generate_security_headers when you just want a fresh best-practice config to apply without scanning anything first.' This names the alternative and states exactly when each tool is appropriate.

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 idempotentHint and destructiveHint, and the description adds specific behavior: it is an idempotent DELETE that returns acknowledgement even if the scan never started, and explicitly states no auth and no side effects beyond freeing an upstream job slot. This adds value 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?

Four concise sentences, each providing essential information: purpose, idempotency, requirement, usage scenario, and side effects. No filler or redundant 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?

For a simple one-parameter tool with rich annotations and no output schema, the description covers purpose, usage guidelines, safety (idempotency), and side effects comprehensively. It is complete for the given complexity.

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 the parameter described as 'Deep scan ID returned by start_deep_scan'. The description repeats the same information ('Requires scanId returned by start_deep_scan'), adding no new meaning beyond the schema. 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 clearly states the tool cancels an in-progress Internet.nl deep scan, using a specific verb and resource. It distinguishes from siblings like start_deep_scan and get_deep_scan_status by focusing on canceling the operation.

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 defines when to use the tool ('when the user changes their mind mid-scan or when polling get_deep_scan_status would otherwise time out') and notes it requires scanId from start_deep_scan. It does not name an alternative tool but provides clear context and an idempotency safety net.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful context: it 'safely fetches' the SVG, reads certificate metadata, and explicitly states limits (no certification of SVG compliance, no trust chain validation, etc.). It also confirms 'No auth or destructive actions.' 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?

The description is compact yet comprehensive. It opens with a clear purpose, enumerates capabilities and limitations, and ends with usage guidance. No filler words; every sentence adds value. Front-loaded with the most important 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 the tool's complexity (BIMI involves DNS, HTTPS fetch, certificate parsing) and lack of an output schema, the description fully explains what is returned (record syntax, URL reachability/content type, certificate subject/issuer/validity dates, explicit issues) and what is not covered. It is complete and self-contained.

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 single parameter (`domain`) clearly described as 'Domain name only, e.g. example.com (no URL, path, or port)'. The description does not add extra parameter details beyond that, but the schema is sufficient. 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 starts with 'Read-only BIMI readiness check' which is a specific verb+resource. It then details the exact actions (parse TXT record, fetch SVG, parse certificate metadata) and outputs (record syntax, reachability, certificate info, explicit issues). This clearly distinguishes it from sibling tools like check_spf or check_dmarc.

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 it is for 'technical preflight before a formal BIMI/VMC review.' Also lists what it does NOT do (SVG Tiny PS compliance, trust chain validation, trademark verification, mailbox provider guarantee), providing clear exclusions and implicit guidance on when not to rely on 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?

The description discloses that the tool is read-only, requires no authentication, and handles provider timeout/availability gracefully by reporting unavailable and disabled providers. This complements the annotations (readOnly, idempotent) with concrete behavioral details.

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

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

The description is dense but each sentence provides essential information, including purpose, input constraints, output characteristics, and usage context. It could be slightly more concise, but the structure is logical and front-loaded with the core function.

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 tool's function, input requirements, output details (including severity and removal metadata), and caveats (timeouts not misreported, not a delisting service). It is complete for the given schema and annotations.

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

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

The description explains that the domain parameter resolves MX IPv4 addresses for checking, while the IP parameter allows direct checking. It also clarifies that at least one is required, adding meaningful context beyond the schema's basic field descriptions.

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

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

The description clearly states that this tool performs read-only queries against DNSBL/RBL providers to check blacklists. It also specifies the use case for mail-server reputation triage, distinguishing it from other tools like SPF or DMARC checkers.

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 (mail-server reputation triage) and what it is not for (delisting). It also provides input requirements (either domain or IP, at least one required) and notes that noisy providers are disabled, giving clear usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety traits are covered. The description additionally discloses 'single GET, no auth, no side effects', which reinforces and adds specificity. It also mentions it returns warnings and a policy strength assessment, which is useful behavioral context. No contradiction found.

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, front-loaded with purpose, then usage, and then technical details. Every sentence earns its place without fluff. It is about 70 words for a complex tool, which is efficient.

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

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

Given the tool's moderate complexity (fetching DNS record and parsing) and that no output schema exists, the description essentially provides the output structure (returns parsed tag map, policy strength, warnings). It also covers caveats (multiple records) and authentication requirements (no auth). A slight gap: it doesn't mention what happens if the record is missing, but overall it is thorough.

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 parameter 'domain' is well documented in the schema. The description adds context by emphasizing it is 'domain name only, no URL, path, or port', which prevents misuse. However, it does not deeply expand beyond the schema, so a 4 rather than 5.

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 has a clear verb ('fetch and parse') and resource ('_dmarc TXT record'), with specific scope. It explicitly states what it returns and lists fields (tag map, policy strength, etc.), distinguishing it from sibling tools like check_spf and check_sender_requirements.

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 explains when to use this tool ('for DMARC policy review') and when to use an alternative ('use check_sender_requirements for combined Google/Yahoo SPF+DKIM+DMARC pass/fail verdict'), which is excellent guidance compared to most tool descriptions.

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, so the safety profile is covered. The description adds that it is read-only HTTP with no auth and no destructive actions, reinforcing the annotations and adding the no-auth detail. It also explains the output includes every resolver response plus propagation percentage and inconsistency list, which is useful behavioral context 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?

The description is three sentences, front-loaded with the core function, and every sentence adds value: what it does, what it returns, when to use it, and safety. 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?

For a read-only diagnostic tool with 100% schema coverage and no output schema, the description is complete. It explains the tool's scope, output, usage context, and safety. The sibling tools are numerous but the description clearly differentiates from the most similar one (lookup_dns).

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. The description adds that defaults are A and 'all', which is already in the schema defaults, and mentions the domain format constraint (no URL, path, or port) which is also in the schema. It does not add significant new meaning beyond the schema, 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 the tool compares DNS responses across nine resolvers to detect propagation lag, missing answers, or inconsistent TTL/data values. It specifies the default record type and region, and distinguishes it from lookup_dns, 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?

The description explicitly says to use this tool when records were just changed and staleness is suspected, and directs to lookup_dns for a single DNS-over-HTTPS lookup. This provides clear when-to-use and when-not-to-use guidance with an alternative tool named.

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 'Read-only' and 'No auth, ~3-8s', which complements the annotations (readOnlyHint, idempotentHint) by adding latency and auth context. It doesn't explain the return format or how the aggregated score is computed, but with strong annotations covering safety, this is adequate. The description adds meaningful context 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 a single, well-structured paragraph that front-loads the core purpose, details the components, then provides usage guidance. Every sentence adds value, with no filler or redundancy. It's appropriately sized for the tool's complexity.

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

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

For a single-parameter tool with rich annotations and 100% schema coverage, the description is complete. It covers purpose, components, usage alternatives, and operational details (no auth, ~3-8s). There's no output schema, but the description explains the aggregated output (0-100 score with prioritised issue list), so an agent knows what to expect. This is fully sufficient for the agent to select and 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?

The schema covers the single parameter (domain) with 100% coverage, including format constraints (maxLength 253) and an example description. The description reinforces 'domain' usage by implying a domain input, but the real value is in the schema. Baseline for high coverage is 3, and the description adds a bit more by framing the domain as the input to the combined check, 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 uses a specific verb ('combined email-security check') and clearly lists the resources and scope: SPF parse, DKIM selector discovery, DMARC policy validation, MX IP blacklist status, and an aggregated 0-100 score. It explicitly distinguishes itself from sibling tools by naming check_spf, discover_dkim, check_dmarc, and check_blacklist, which is perfect for an agent deciding between 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 'Use for one-shot email security overview' and provides clear guidance on when to use alternatives: 'use check_sender_requirements specifically for Google/Yahoo bulk-sender compliance, or the individual check_* tools when you need only one signal.' This is excellent usage guidance with named alternatives and specific 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?

The description fully discloses the workflow: 'looks up PTR record, then resolves that PTR's hostname back to A/AAAA records to confirm the round-trip.' It additionally enumerates returned values and common warnings, going far beyond the readOnlyHint annotation and providing actionable expectations.

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 compact yet information-dense: it opens with the core purpose, then explains the resolution flow, then lists return contents and use cases, and closes with a statement on authentication. Every sentence earns its place without 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?

Without an output schema, the description compensates well by listing return fields and warning types, and by explaining when to use the tool. Minor omissions like behavior on missing MX records or response pagination are not critical, but additional details would push completeness to a 5.

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

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

The schema already fully describes the 'domain' parameter with format restrictions (no URL/path/port), so baseline is 3. The description adds context by framing it as 'the domain's MX records,' but it does not introduce new 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 uses a specific verb+resource combination: 'Read-only FCrDNS audit for every IP that backs the domain's MX records.' It distinguishes itself from sibling DNS tools by focusing uniquely on forward-confirmed reverse DNS for MX IPs, making the purpose unmistakable.

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

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

Provides clear usage context: 'Use for mail deliverability audits, SpamExperts-style cluster checks, and debugging rejected mail.' It also names an alternative/complementary tool: 'pair with check_blacklist for reputation signals,' helping the AI decide between 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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: no auth required, ~2-5s expected latency due to UDP handshake timeout, and the live QUIC probe to UDP/443. 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 three sentences, front-loaded with the core purpose, and every sentence adds value: what it checks, how it checks it, what it returns, when to use it, and operational characteristics. No filler or redundancy.

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

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

For a single-parameter read-only check with no output schema, the description is complete: it explains the input, the three signals checked, the aggregate boolean return, use cases, exclusions, auth requirements, and expected latency. Nothing important is missing for an agent to select and invoke 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 coverage is 100% for the single required parameter 'domain', and the schema already explains that it must be a domain name only with no URL, path, or port. The description does not add further parameter-level detail, but the schema fully carries that burden, 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 opens with a specific verb and resource: 'Read-only HTTP/3 + QUIC support check for a domain.' It clearly enumerates the three combined signals and the aggregate result, making it distinct from all 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?

Explicit when-to-use guidance is provided: 'Use when validating CDN/Cloudflare HTTP/3 rollouts or auditing modern transport posture.' It also gives a when-not case: 'not relevant for mail-only domains.' However, it does not name a specific alternative sibling tool.

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 explicitly states it is read-only, mentions that it performs DNS and HTTPS GET requests only, and outlines exactly what it returns (parsed policy, TLS cert validity, consistency warnings). This fully discloses behavior, aligning with readOnlyHint and no side effects. No contradictions noted.

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: two sentences plus a final note. It front-loads the tool's purpose and key actions, provides return details, and ends with a pairing recommendation. Every sentence adds value; no fluff 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?

Given the tool's simplicity (one param, no nested objects), the description sufficiently covers inputs, process, and outputs. It also provides context on when to use it (checking MTA-STS for inbound mail) and how to complement with check_smtp_tls. There is no missing essential information for a user to decide to invoke it.

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

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

The only parameter 'domain' already has a detailed description in the schema ('Domain name only, e.g. example.com (no URL, path, or protocol)'), which fully covers its meaning. The tool description repeats part of that (constructs MTA-STS records) but doesn't add new constraints or clarifications. Since schema coverage is 100%, 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 explicitly states what the tool does: checks MTA-STS by reading DNS TXT record and HTTPS policy file, and returns parsed policy, TLS certificate validity, and consistency warnings. It also states the use case:

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 a clear usage scenario (

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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by explaining that TLS, unsubscribe, complaint rate, and From-header checks are informational follow-ups because they require telemetry, preventing false passes. It also notes the readiness summary is 'explicitly limited.' This goes beyond 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 compact, front-loaded with the core purpose, and every sentence adds value. It covers purpose, scope, limitations, and usage guidance in three sentences without redundancy.

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

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

Given the tool's moderate complexity (multiple DNS checks) and no output schema, the description adequately explains what is checked and what is not. It could mention the return format or how results are structured, but the per-requirement pass/fail/warning/info is mentioned. The lack of output schema is partially compensated by the clear description of result types.

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 description for the single 'domain' parameter. The description adds context by emphasizing the domain-only input (no URL/path/port) and the read-only nature, which reinforces the schema. Since there's only one parameter and it's well-documented, the description adds marginal but useful value.

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 performs a read-only domain-side preflight against Google/Yahoo bulk-sender requirements, listing specific checks (SPF, DKIM, DMARC, MX, PTR/FCrDNS). It distinguishes itself from siblings by explicitly noting it is domain-side and that message-level requirements are handled by other 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 'Use before a campaign' and directs to 'use analyze_raw_email or create_email_test to verify message-level requirements.' This provides clear when-to-use guidance and names specific alternatives, which is excellent.

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, openWorld, idempotent, and non-destructive behavior, and the description complements them with concrete operational details: it opens TCP 25, runs EHLO and STARTTLS, connects and quits without sending mail, may take 10-30 seconds, and requires no auth. It also discloses output contents such as per-MX cipher/version, cert SANs, and FCrDNS verdict, going well beyond the structured metadata.

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 compact, front-loaded with the core action, and every sentence contributes new information: scope, methodology, safety, output, use case, performance, and auth requirements. There is no redundancy 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?

For a single-parameter tool with no output schema, the description is remarkably complete. It explains the operational behavior, the network interactions, the return values, latency expectations, authentication, and the intended pairing with a sibling tool. No critical context required for correct selection or 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, domain, and the schema already documents it thoroughly with constraints and an example. The description adds contextual value by explaining the check operates on every MX host, but it does not need to repeat or elaborate on the parameter syntax. With 100% schema description coverage, the 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 starts with a specific verb and resource: 'Live check of every MX host'. It enumerates the exact checks performed (TCP 25, EHLO, STARTTLS, certificate validation, DNS lookups) and clearly distinguishes itself from sibling tools by naming check_mta_sts as the policy-layer counterpart. This is a precise, unambiguous statement of 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 gives an explicit use case: 'Use to verify inbound mail TLS posture' and recommends pairing with check_mta_sts for policy-layer validation. It also warns about slower runtime (10-30s) and notes that it is read-only, helping the agent decide when to invoke it. However, it does not explicitly state when not to use it or name alternative tools beyond check_mta_sts.

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

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

Even though annotations already declare readOnlyHint, idempotentHint, and destructiveHint, the description adds critical behavioral context: it explicitly says 'No auth, no side effects' and describes the recursive walk behavior and the counting against RFC-7208 limit. This goes beyond annotations, providing operational details like the 10-lookup limit and return of flattening guidance when near the limit.

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: two sentences that front-load the purpose, then list outputs and usage guidance. It packs a lot of information without redundancy, and every sentence earns its place. It avoids fluff and is easy to scan, which is ideal for AI parsing.

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

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

Given the tool's moderate complexity (recursive walks, count limits), the description fully covers what the tool does, what it returns, and when to use it. With a single parameter fully defined in the schema, and annotations covering safety, the description is complete. No output schema exists, but the description enumerates key outputs ('parsed mechanisms, lookup graph, total count, qualifier, warnings'), so the agent knows what to expect.

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 for the single parameter 'domain' with a clear description and maxLength. The description reinforces that the input is a domain only, but doesn't add new syntax details beyond the schema. Since schema coverage is high, a score of 4 is appropriate; it doesn't need to repeat parameter details but could add examples or edge cases.

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 performs 'read-only SPF parse and validation for a domain', with specific behaviors like recursively walking include/redirect mechanisms and counting DNS lookups. It explicitly distinguishes itself from sibling tools by mentioning check_email_security for broader overview, and other siblings like flatten_spf for flattening guidance. The verb 'check' plus resource 'SPF' is specific and 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 provides explicit usage context: 'Use for SPF auditing or before adding new include: senders' and explicitly contrasts with 'check_email_security for the broader SPF+DKIM+DMARC overview'. This gives clear when-to-use and when-not-to-use guidance, naming an alternative tool, which is exemplary.

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 readOnly/idempotent safety, but the description adds critical behavior: it does NOT fetch or cryptographically match the live certificate, and it resolves MX hosts when no port is given. This goes beyond annotations and prevents misuse. No contradiction found.

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, dense sentence that packs both behavior and usage guidance without redundancy. It front-loads the core purpose ('Read-only TLSA/DANE DNS record check') and follows with needed details. Though slightly long, it avoids redundancy and adds value with each clause.

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 absence of an output schema, the description explicitly lists the returned data (parsed usage, selector, matching type, certificate data, syntax errors, best-practice advisories). It also covers limitations and pairing context, making the tool's scope complete for an agent without extra missing pieces.

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 descriptions for all three parameters. The description enriches semantics by explaining how 'port' interacts with tuple construction (no port -> MX host resolution; explicit port -> _<port>._<protocol>.<domain>), which is not in the schema's property 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's a read-only TLSA/DANE DNS record check, and elaborates on behavior with/without port. It distinguishes from siblings like check_smtp_tls and lookup_dns by specifying the TLSA/DANE scope and the exact tuple construction.

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 it ('before publishing DANE records or troubleshooting DANE handover'), what it does NOT do (doesn't fetch or match live service certificate), and directs users to pair it with check_smtp_tls for SMTP certificate evidence, providing an alternative tool.

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

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

The description adds substantial behavioral context beyond the annotations: it declares this is a non-idempotent POST, is additive and never modifies prior sessions, has a 60-minute validity, and explicitly states no auth is required. These details enrich the readOnlyHint false and idempotentHint false annotations, going beyond what structured fields 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 efficient and well-structured: a single introductory sentence states the core action and returns, followed by behavioral notes, parameter clarification, usage guidance, and auth status. Every sentence adds value, and the most important information is front-loaded.

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

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

The description is complete for a tool with one optional parameter and no output schema. It explains the return value format, provides lifecycle context (valid 60 minutes, used by get_email_test/poll_email_test), and gives a clear end-to-end workflow. No critical information appears missing 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% (the only param `language` is fully described with enum and default). The description adds minimal extra meaning ('controls result text') which is essentially a rephrase of the schema's 'Result language'. It provides no new syntax or format guidance, so it meets the baseline of 3 but does not exceed it.

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

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

The description clearly states the tool creates a new inbound email-test session, names the returned artifacts (test email address, testId), and explicitly differentiates from sibling tools by referencing get_email_test and poll_email_test as follow-ups. This is a specific verb+resource description with clear scope.

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 ('Use to debug an outbound message's SPF/DKIM/DMARC, headers, and spam triggers') and provides the next step ('after sending, call poll_email_test'). However, it does not mention when not to use it or list alternative tools (e.g., scan_domain) for other scenarios, so it falls short of the full 'when-not/alternatives' criterion.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description adds valuable behavioral details: snapshots are write-once, additive, not idempotent, and resolve to stable evidence over time. It also explains the return payload (snapshot ID, timestamp, hash, URLs), which is not covered by 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 five sentences, each serving a clear purpose: purpose, return values, behavior, usage guidance, and differentiation. It is front-loaded with the main action and contains no filler. 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?

With no output schema, the description fully explains return values, including IDs, timestamps, hashes, and URLs. It also covers the tool's non-idempotent behavior, its relationship to sibling tools, and the reason to use it, providing a complete picture for an 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?

The input schema already has full descriptions for both parameters (100% coverage), so the description does not need to add parameter details. It does mention JSON and Markdown renderings, which aligns with the 'format' parameter, but does not introduce any new information beyond the schema. A 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 uses a specific verb ('Create') and resource ('immutable evidence snapshot of the current Everything Report for a domain'), clearly distinguishing it from reading tools like get_report_snapshot. It also explicitly mentions when to use it instead of get_everything_report, making the 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 provides explicit guidance: 'Use this instead of get_everything_report when the result must remain stable' and 'use get_report_snapshot to read it back.' It also lists concrete use cases (tickets, audit trails, NIS2/ISO compliance, LLM citations), giving clear when-to-use context.

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

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

Annotations already include readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds context beyond these: it explains the heuristic behavior (50 queries), the inconclusive miss result due to no enumeration protocol, and that no auth is needed. It doesn't describe the exact return format, but given the strong annotation coverage, the additional behavioral details are sufficient. 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 dense but well-structured: it opens with the core purpose, then explains the two modes, lists return components, and ends with usage guidance and a safety note. Each sentence adds value, with no filler. It uses bullets and clear active verbs, making it scannable for an agent.

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

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

Given the tool's moderate complexity (two modes, a caveat about inconclusive results), the description is nearly complete. It covers purpose, behavior, parameters, and safety. The only minor gap is that it doesn't specify the exact structure of the returned 'parsed key tags' or 'public-key strength', but since there's no output schema, this could be helpful. Still, the description is sufficiently complete for an agent to decide and 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?

The input schema has 100% coverage: it describes `domain` as 'Domain name only' and `selector` as 'Optional exact DKIM selector.' The description adds meaningful context about selector usage, including examples (selector1 or google) and the distinction between exact and heuristic modes. This adds value by explaining the consequences of omitting the selector, which the schema alone doesn't convey.

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 what the tool does: 'Read-only DKIM check for a domain'. It distinguishes two modes: heuristic with 50 common selectors and exact lookup with a specific selector. This uniquely separates it from sibling tools like check_dmarc or check_spf, as it explicitly mentions DKIM and the selector-based functionality.

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 provides when-to-use guidance: 'Use exact mode whenever the selector is known; use check_email_security for the broader SPF/DKIM/DMARC overview.' It also notes the inconclusiveness of the heuristic miss, which is valuable context for the agent deciding when to rely on results. This directly addresses alternatives 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?

The description reinforces the annotations by stating 'Read-only POST to /ai/explain — never mutates DNS or domain state,' consistent with readOnlyHint and destructiveHint=false. It also discloses that it is an AI service and details the return content (severity, business impact, root cause, fix steps), adding behavioral context beyond the annotations. While it doesn't discuss latency or errors, those are not critical.

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 compact yet comprehensive, delivered in four sentences that sequentially cover purpose, output, safety, parameters, and usage guidelines. There is no redundancy or filler; each 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 no output schema and moderate complexity (3 params, one nested object, enum), the description provides sufficient completeness: it describes what is returned, how to invoke it correctly, when to use it, and how to enhance results with context. It also clarifies the relationship to sibling tools, making it fully actionable for an 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?

The description instructs to 'Provide domain and issue (enum); pass context from prior scan output (e.g. scan_domain result) for higher-quality answers,' which adds usage guidance beyond the schema. Schema descriptions for domain and context are clear, but the description explains how to obtain context and its benefit, enriching 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 the action (ask for a plain-language explanation), the target (one specific issue with examples like spf_missing, no_dnssec), and the output (severity, impact, root cause, fix steps). It also differentiates from generate_dns_fix by noting that tool provides the actual fix snippet, making the 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 explicitly says 'Use after scan_domain when an agent needs to walk a user through *why* a finding matters; use generate_dns_fix for the actual DNS record snippet that resolves it.' This provides clear when-to-use and alternatives, along with the recommendation to pass context from prior scans for better answers.

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 read-only, open-world, idempotent, non-destructive. Description reinforces with 'Read-only' and 'No side effects', and adds 'No auth', providing clarity that no modifications occur. It also explains the output includes a maintenance warning, indicating potential future changes.

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 structured in three sentences, clearly conveying purpose, usage, and output. It is somewhat dense with output details but remains informative without unnecessary 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 no output schema, the description comprehensively lists what the tool returns: flattened SPF record, lookup counts, IP count, record length, split flag, and maintenance warning. Together with usage and behavioral notes, it provides a complete understanding of the tool's functionality.

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 provides full description for the only parameter 'domain' (e.g., example.com, no URL/path). Description does not add further details, but given 100% schema coverage, it is sufficient.

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 performs read-only SPF flattening, resolving include/a/mx/redirect graphs to literal IPs, and returns a flattened record with additional metrics. It distinguishes from siblings by specifying the use case of exceeding DNS lookup limits.

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 instructs when to use: when a domain hits 'too many DNS lookups' (PermError) and removing unused includes isn't enough. Also directs to run check_spf first, positioning flatten_spf as a last resort.

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 and destructiveHint:false, and the description reinforces this with 'Nothing is looked up or stored.' It further discloses the return of warnings about common mistakes that break mail, providing transparency beyond annotations. No contradictions found.

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 long but every sentence contributes: purpose, policy risks, key recommendations, return details, and a note on side effects. It is front-loaded with the essential purpose. Slightly dense but no filler; might be slightly overlong for rapid scanning, but structure is logical.

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 the return values (record, host, warnings) and explains key pitfalls. All 9 parameters are documented in schema, and the description adds the critical risk context and rollout strategy, making it complete for a generation tool with both safety and usability considerations.

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 descriptions for all 9 parameters, yet the description adds substantial semantic value beyond the schema by explaining policy meanings (none vs quarantine vs reject), the necessity of rua, the effect of percentage, and alignment pitfalls. This exceeds the baseline for full 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 'Build a DMARC record — the _dmarc TXT record' which clearly specifies the verb (build) and resource (DMARC TXT record). It distinguishes itself from sibling checking tools like check_dmarc by focusing on generation and policy guidance, 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?

Provides explicit practical guidance: 'Always publish a rua address', 'Use percentage to apply an enforcing policy', and explains the progression from p=none to p=quarantine/reject. However, it does not explicitly contrast with alternative tools (e.g., when to use check_dmarc instead), only implicitly through purpose, so it lacks explicit exclusion criteria.

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?

Although annotations already include readOnlyHint and destructiveHint=false, the description adds crucial context: 'Read-only POST to /ai/fix — the API only suggests; it never modifies the user's zone.' It also discloses the return payload (records, TTL recommendations, provider notes), going beyond what annotations provide. 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?

The description is four sentences with no filler. It front-loads the core purpose, then follows with output details, safety, parameter guidance, and workflow in a compact, well-ordered structure.

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

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

With no output schema, the description fully explains what the tool returns. It covers usage prerequisites (after scan_domain/explain_issue), parameter semantics, safety, and the next verification step (lookup_dns), making it self-sufficient for an 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?

The schema documents `domain` format and `context` origin, but `issue` is only an enum without a description. The description compensates by explaining 'fix one specific issue' and giving a concrete example (`spf_missing` → suggested SPF record), and it clarifies that `context` should be from 'prior scan output for tailored output', adding 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 opens with a specific verb and resource: 'Generate copy-pasteable DNS record snippets that fix one specific issue', immediately clarifying the tool's function. It further distinguishes itself from siblings by specifying the output ('proposed records, TTL recommendations, and provider-specific notes') and the /ai/fix endpoint.

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 workflow guidance: 'Use after explain_issue or scan_domain identifies a problem; use lookup_dns afterwards to verify the user has applied the suggested record.' It explains when to call the tool and what inputs to provide, but it does not explicitly contrast with sibling generators like generate_spf or generate_dmarc.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, and the description reinforces this with "no scan needed, nothing about your live site is read." It further discloses behavioral details: returns headers as name/value pairs, ready-to-paste output for multiple server formats, and warnings, plus default behavior when neither preset nor config is supplied.

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 information-dense but well-structured: it opens with the core purpose, then explains presets, advanced config, return format, and finally the sibling-tool alternative. Every sentence contributes essential guidance, with no filler or repetition of schema details.

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 two optional parameters, one nested config object, no output schema, and strong annotations, the description covers all essential context: preset options, advanced config usage, default behavior, output formats, warnings, and when to use the sibling analysis tool. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, but the description adds meaningful context beyond the schema: it explains the practical effect of each preset, notes that config overrides preset, and states the default when neither is passed: "if you pass neither, it defaults to 'recommended'." This goes beyond the schema's per-parameter 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?

Description uses a specific verb+resource: "Generate a complete, best-practice set of HTTP security headers ... as copy-paste configuration." It explicitly contrasts with the sibling analyze_security_headers, saying to use this for setting up headers on a new or unscanned site, which clearly distinguishes it from similar 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?

Provides explicit when-to-use guidance: "Use this to set up headers on a new or unscanned site; use analyze_security_headers first when you want to see what an existing site is already missing." It also explains preset selection and gives a clear alternative for existing-site analysis.

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, idempotentHint), the description states 'Nothing is looked up or stored — this is computation only,' which is a strong behavioral disclosure. It also details the output: 'Returns the record, the lookup count, whether either the lookup or 255-character limit is exceeded, warnings in plain language, and the DNS entry to publish.' This fully informs the agent of behavior and 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 information-dense but not verbose. It starts with a clear purpose, then explains parameters with examples, rationale for using the tool (lookup limits), alternatives, and ends with side-effect note. Every sentence adds value; no fluff. It is well-structured 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?

The description covers all necessary context for a complex tool: what it does, how to use it, why it's helpful (lookup limits), return values, alternatives, and that it's computation-only. Even without an output schema, it describes outputs clearly. It also addresses common pitfalls (pass policy, lookup limits) making it 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?

Although schema coverage is 100%, the description adds domain-specific meaning: concrete examples for include values (Google Workspace, Microsoft 365, SendGrid), explanation of policy values with their SPF syntax (-all, ~all), and the lookup cost of each mechanism type (not in schema). It also explains the semantics of useMx/useA in practical terms. This goes well beyond the baseline.

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 begins with 'Build an SPF (Sender Policy Framework) record' which specifies the verb and resource clearly. It then distinguishes this tool from siblings by explicitly stating 'Use check_spf instead to read and validate... and flatten_spf when... use this to build a new record from scratch.' This clearly establishes unique 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?

Provides explicit guidance on when to use this tool vs alternatives: 'The reason to call this rather than write the string yourself' explains the value proposition, and it names check_spf and flatten_spf as alternatives with distinct use cases. It also clarifies when not to use it (existing records).

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 this as read-only, idempotent, and safe, but the description adds critical behavior: it refuses private keys, the hash is computed server-side, it warns about DNSSEC conditions, explains what happens with imperfect records, and lists return content. It provides substantial non-obvious 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 long but purposeful and front-loaded with the core purpose. Every major statement contributes essential operational or security information. The prose is one substantial paragraph, which is acceptable, though it could be tightened slightly without losing important details.

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 input (PEM, host, port, profile), validation criteria, rejection behavior, DNSSEC prerequisites, DNS propagation issues, and the output format. Since there is no output schema, it adequately explains what to expect in return. For a technical generation utility, this is a complete and self-sufficient definition.

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

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

Even though the schema covers 100% of the parameter descriptions, the description enhances meaning considerably: it explains the hash computation, the meaning of usage/selector/matching values, recommends the 3-1-1 profile specifically for SMTP lifecycle, and clarifies why private keys are not accepted. This goes far beyond the schema fields.

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 begins with the specific verb 'Build' and names the exact resource ('a DANE TLSA record from a certificate or public key'). It clarifies the security purpose. It also gives enough specificity to distinguish it from sibling tools like generate_dns_fix or generate_dmarc.

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 operational guidance: paste a PEM, never send a private key, use 3 1 1 for SMTP, and set host to the MX record hostname. It does indicate when to use the tool (when the generation of TLSA record is needed). It does not explicitly name alternatives or say when not to use it, so it falls short of a perfect 5.

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

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

Beyond annotations, the description discloses that no scan is triggered, no network call is made, and no auth is required. It also specifies the exact return shape (JSON with badgeUrl). This adds substantial behavioral context that annotations alone do not provide.

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

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

The description is four sentences, front-loaded with purpose, then details, then usage distinction. Every sentence adds value, with no fluff or repetition of schema fields beyond necessary clarification.

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

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

With no output schema, the description fully explains the return format. It covers purpose, usage, side effects, and parameter semantics, making it self-contained for an agent to confidently invoke the tool.

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

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

Schema description coverage is 50%, and the description compensates by listing style options with the default, which clarifies the style parameter. The domain parameter already has a clear schema description, so the description adds minimal extra meaning but still contributes useful guidance for style.

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 builds an SVG badge URL for a domain's security score, explicitly noting it is pure URL construction with no scan or network call. It also distinguishes itself from get_pdf_report_link, making the 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?

Explicit guidance is provided: use for embeddable status badges, and use get_pdf_report_link for downloadable full reports. The description also clarifies scenarios where this tool is appropriate (README, GitHub, status pages), meeting the when/when-not criteria.

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, so the safety profile is covered. The description adds that it is 'Pure data, no I/O, no auth,' which reinforces the non-mutating, side-effect-free nature. It doesn't describe return format, but given the annotations, this is sufficient.

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

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

The description is a single, dense paragraph that front-loads the core purpose, lists the topics, and ends with usage guidance. Every sentence adds value with no fluff 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 simple data-lookup tool with one parameter and no output schema, the description covers purpose, usage, and safety. It could be more complete by describing the return structure (e.g., 'returns a JSON object with host, do-not-use list, and URLs'), but the current level is adequate 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?

The schema has 0% description coverage, but the description enumerates all 11 valid topics in parentheses, which adds meaning beyond the bare enum. However, it doesn't explain what each topic returns or how to choose among them, so the description only partially compensates for the schema's lack of 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 the tool returns canonical citation guidance for IntoDNS.ai, distinguishing it from legacy domains. It lists the specific topics it covers and explicitly contrasts with read_llm_discovery, 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?

The description explicitly says 'Use whenever generating an answer that references DNS or email scanning evidence' and provides a clear alternative: 'use read_llm_discovery for raw machine-readable discovery files.' This gives the agent precise when-to-use and 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.

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces these by stating 'Read-only' and 'No auth, no side effects.' It adds context on the polling behavior and return contents (progress, scores, per-test results, failures) which is beyond the annotations but not extensive; a 4 is appropriate since it adds some value without contradicting.

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, with only three sentences. It is front-loaded with the core purpose ('Read-only status poll'), then details return contents, then provides usage and alternatives. Every sentence adds value, with no filler or redundancy.

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

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

Given the tool is a read-only status poll with one parameter and no output schema, the description adequately covers key aspects: purpose, return contents, usage, and alternatives. It lacks some detail on return format (e.g., JSON structure) but that's not required when no output schema exists; it is sufficiently complete for the tool's complexity. A 4 is justified.

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 parameter 'scanId' with description 'Deep scan ID returned by start_deep_scan'. The tool description repeats this information, but since the schema already provides clear semantics, the description does not add significant extra value. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: to poll the status of a long-running deep scan, mentioning the resource (scan) and the specific action (get status). It explicitly mentions the tool name 'get_deep_scan_status' and distinguishes it from sibling tools like 'get_email_test' and 'scan_domain' by focusing on deep scan status polling.

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 usage guidance: it states when to use this tool (after start_deep_scan, poll every 10-30s until finished) and when not to (for fast single-vantage scans, prefer scan_domain). It also gives the prerequisite: requires a scanId from start_deep_scan. This is a model example of usage guidelines.

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

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

Beyond the annotations, it explains the pending-to-results state transition, the kinds of results returned, the requirement for a prior create_email_test step, and that no auth is needed. 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?

Every sentence earns its place: purpose, lifecycle, dependency, when-to-use, and alternative tool. Dense but not bloated, and the text front-loads the essential purpose before adding usage nuance.

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 having no output schema, the description adequately covers what to expect ('pending' vs full authentication/spam results), the required input, when to call, the safe read-only nature, and no-auth requirement. The tool is fully operational from the description alone.

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

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

The schema already covers testId with 100% clarity ("Email test ID returned by create_email_test"). The description reinforces this requirement but does not add meaningful new parameter-level details beyond usage 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 clearly identifies a read-only status tool for email-test sessions, explaining the pending/complete lifecycle. It distinguishes itself from poll_email_test by describing status polling vs explicit processing.

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 direct guidance: use after sending a message to the test address, and explicitly names poll_email_test as the alternative for processing just-arrived mail. Also states the dependency on testId from create_email_test.

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=false, but the description adds valuable context: '~5-15s latency depending on backend cache state', 'Read-only, no domain mutation', 'No auth, no side effects.' This goes beyond annotations by warning about latency and reaffirming the non-mutating, side-effect-free behavior. There is 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 three sentences, each earning its place: the first states purpose and scope, the second covers latency and safety, and the third gives usage guidance with alternatives. It is well-organized, front-loaded, and free of filler or redundancy.

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

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

Despite the lack of an output schema, the description is remarkably complete: it enumerates the covered domains (DNS, email, web/HTTPS, blacklist, sender requirements, citation URLs), states the latency, declares no auth/side effects, and directs users to alternatives based on their needs. For a complex report generator, this gives an AI agent sufficient context to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add new parameter semantics beyond what the schema already provides; it mentions 'no URL, path, or port' implicitly but that is detailed in the schema. The format parameter is also fully described in the schema. The description adds little value here beyond serving as an overview.

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+resource: 'Generate the complete live IntoDNS.ai report covering DNS, email authentication, web/HTTPS, blacklist reputation, sender requirements, and canonical citation URLs in a single call.' This clearly distinguishes it from sibling tools like scan_domain and get_email_test by emphasizing the comprehensive, all-in-one scope.

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

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

Explicit usage guidance is provided: 'Use when the user asks for everything, the full picture, or a deep current-state summary; use scan_domain for a faster default scan, or create_report_snapshot when the result must remain immutable for audit/ticket use.' This names alternative tools and the conditions for choosing them, making the decision 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?

Adds meaningful context beyond annotations: no rank calculation, boolean membership result, stored score/timestamp, potential staleness, and no auth requirement. This complements the readOnly/openWorld/idempotent hints 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?

Three tight sentences front-load the core purpose, then cover mode-specific behavior, usage guidance, and safety in an efficient, scannable format. Every 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?

For a simple two-parameter read-only tool with no output schema, the description fully covers return shapes, staleness caveat, alternative tool, and auth/destructive-action safety. No important operational context 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 already documents both parameters well, and the description adds behavioral meaning: omitting domain lists entries with limit/default/max, while providing domain returns a boolean membership result. This goes beyond schema descriptions by explaining conditional behavior.

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 identifies a read-only fetch of the Hall of Fame and specifies both invocation modes (list vs. membership check). It distinguishes itself from scan_domain by noting the data may be older, which separates it from siblings.

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: showing examples of strong DNS/email posture or checking membership. It also names scan_domain as the alternative for current evidence, giving clear when-to-use and 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.

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable context: the public endpoint redacts internal details, it is unauthenticated, and it performs a single GET with no destructive actions. This fully discloses behavior 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?

The description is compact and front-loaded, with every sentence adding value: purpose, scope, return values, redaction behavior, usage guidance, alternative tool, and safety/auth notes. No filler or redundancy.

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

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

For a zero-parameter health probe with rich annotations, the description is fully self-sufficient. It covers purpose, expected outputs, safe-call context, when to use it, and when not to, leaving no meaningful 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?

The tool has zero parameters, so the baseline is 4. There is nothing to explain beyond what the empty schema already communicates; no additional parameter guidance is 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?

The description clearly states the tool is a read-only health probe for the IntoDNS.ai backend itself, immediately distinguishing it from tools that probe target domains. It specifies exact outputs (service status and observation timestamp) and differentiates from get_stats.

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

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

Explicit usage guidance is provided: use as a pre-flight check before batch jobs or to distinguish service incidents from DNS findings. It also names an alternative tool (get_stats) for public usage counters, making the boundary 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 the annotations (readOnlyHint, idempotentHint), the description adds key behavioral details: 'Pure URL construction — no scan triggered, no network call from this tool.' It also explains the return value and the behavior of fetching the returned URL, which is not captured in 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 four sentences, each providing distinct value: purpose, side-effect negation, return behavior, and usage alternatives. It is front-loaded with the core function and contains no redundant 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 the tool's simplicity (one parameter, no output schema), the description fully covers what the tool does, what it returns, how to use the result, and when to choose alternatives. It also explicitly states auth requirements and side effects, making it complete for an 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 description coverage is 100% (the only parameter 'domain' is fully described in the schema). The description adds no additional parameter semantics beyond referring to 'for a domain,' so the 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 tool's function: 'Build the direct PDF report endpoint URL for a domain.' It uses a specific verb ('build') and resource ('PDF report endpoint URL'), and explicitly distinguishes from siblings by naming get_badge_link and create_report_snapshot as alternatives.

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

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

The description provides explicit when-to-use guidance: 'Use for downloadable shareable reports; use get_badge_link for an embeddable SVG status badge instead, or create_report_snapshot for an immutable hashed evidence URL.' It also states 'No auth,' covering prerequisites.

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

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

Adds details beyond annotations: immutable JSON, original SHA-256 hash, timestamp, no auth, fully idempotent. Annotations already declare read-only and idempotent, so some redundancy, but the immutable/hash detail adds value.

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

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

Two clear sentences, front-loaded with purpose, then details. No fluff, each sentence adds distinct info. Slightly longer than minimal, but concise.

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

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

Given simple read operation with good annotations and full schema coverage, description covers behavioral details, usage context, and alternative. Fully complete for this 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 covers both parameters well (snapshotId, format with enum). Description references snapshotId source but adds little beyond schema; no format details beyond what schema provides. Coverage is 100%, so 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?

Purpose is crystal clear: 'Read a previously created IntoDNS.ai Everything Report snapshot by snapshot ID.' It distinguishes from get_everything_report (live data vs snapshot) and specifies the resource (snapshot) and action (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 states when to use (verify/re-read audit trail) and when not to (use get_everything_report for current live data), plus the prerequisite of obtaining snapshotId from create_report_snapshot.

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

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

The description goes beyond annotations by specifying it is read-only, returns no personal data or per-domain breakdown, and is a single unauthenticated GET with no destructive actions, fully disclosing behavior.

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 yet comprehensive, using a few sentences to convey purpose, usage, and limitations without redundancy.

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

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

Given the absence of an output schema, the description sufficiently describes the returned counters (domains scanned, security checks performed, cache timestamp) and explicitly lists what is not included, making it 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 tool has no parameters, so the schema is trivially covered. The description appropriately omits parameter details, adding no unnecessary ambiguity.

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 fetches aggregate counters from the public /api/stats endpoint, and explicitly distinguishes it from get_hall_of_fame, making the 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?

It explicitly states when to use it ('for a lightweight public usage snapshot or status display') and contrasts with get_hall_of_fame for top-scoring domains, providing clear usage guidance.

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

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

The description aligns with the annotations (read-only, idempotent, non-destructive) and adds context about the return format and the default behavior (returns A records if types omitted). No negative side effects are mentioned, and the tool is transparent about its operation.

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, with no redundant information. It manages to convey the purpose, usage, output, and alternatives in just a few sentences, making it efficient for an agent to parse.

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

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

The description is complete for a lookup tool: it covers what the tool does, the input parameters (with defaults), the output format, and how to choose between this and related tools. It also mentions operational details like the use of DoH and lack of rate limits, providing sufficient context for an 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?

The schema already provides clear descriptions for each parameter, and the description adds the default behavior (A records when both type and types are omitted) and clarifies the distinction between single and multiple types. This fully covers 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 is a read-only DNS record lookup via DNS-over-HTTPS, specifies the output (parsed answers with TTL, rdata, AD bit), and distinguishes it from related tools like validate_dnssec and check_dns_propagation.

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 'Use for arbitrary record queries' and contrasts with alternatives: 'use validate_dnssec for full DNSSEC chain validation, or check_dns_propagation for multi-resolver consensus.' It also notes there is no auth or rate limits.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful context on the limitation to the DNS/email layer and the full set of return values (weighted total, per-measure status, evidence, gaps, fixes). It does not contradict 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 three sentences, front-loaded with the core action and return value. Each sentence provides essential information: what it does, what it returns, and when to use it. There is no redundancy 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?

There is no output schema, so the description appropriately details what the tool returns: '0-100 weighted total, per-measure status (Article 21.2 a-j), evidence rows, critical gaps, and concrete fix suggestions.' It also mentions the language parameter's effect (caveat text) and the scope limitations, covering the necessary context for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema fully documents both 'domain' and 'lang'. The description does not add any parameter-level meaning beyond what the schema provides, making a baseline score of 3 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 starts with a specific verb and resource: 'Compute a NIS2 Article 21.2 readiness score for a domain.' It clearly differentiates from siblings by focusing on NIS2, a unique topic among the listed tools. The scope is explicit, mentioning the DNS and email layer.

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

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

The description explicitly states when to use the tool: 'Use when the user asks about NIS2 compliance, NIS2 readiness, NIS2 Article 21.2, cyber-hygiene compliance, or related EU-NIS regulation checks for a domain.' It also provides a clear exclusion: 'full NIS2 compliance also requires audit of web applications, supply chain, organisational processes, and training,' telling the agent what this tool does NOT cover.

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

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

The description goes beyond annotations by explaining that reports are parsed in-memory and not stored, and that no auth is needed. It details the output structure (metadata, policy, per-source rows) which is valuable for understanding behavior.

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 yet comprehensive, covering purpose, output, input, and use case in a logical flow. 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?

Given the absence of an output schema, the description provides sufficient detail about the output structure. It also covers input options, side-effect profile, and use case, making it complete for an agent to decide when and how to use the 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?

Both parameters are fully described in the schema, and the description clarifies that they are alternative ways to provide the report (raw XML vs. base64 gzip). It adds practical guidance on usage and limits, making the parameters unambiguous.

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 that the tool parses DMARC aggregate XML reports into structured JSON. It distinguishes itself from sibling tools that perform scans or tests by explicitly focusing on reading and parsing reports.

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: to programmatically read DMARC reports fetched from the rua@ mailbox. It also provides practical notes like parsing in-memory, no authentication required, and no side effects, giving clear guidance on context and constraints.

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 ('if no message has arrived yet, returns pending'), processing behavior, and explicitly states 'No auth, no destructive side effects.' Annotations already include idempotentHint and destructiveHint false, but description adds what happens on pending and the processing action, matching 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?

Description is compact (three sentences) with no fluff; every sentence provides essential information: purpose, idempotency behavior, usage, and alternative. Front-loaded with action, immediately useful to the agent.

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 a single parameter and high schema coverage, the description fully covers what the agent needs: how to invoke, what to expect ('pending' or parsed result), and caveats (no auth, no destructive side effects). No output schema, but description implies return content adequately for selection.

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% for the single parameter testId, and the schema already describes it well. The description adds value by explaining its origin (from create_email_test) and its role in the tool's operation, which is helpful 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?

Clearly states it processes the latest received message in an email-test session, which distinguishes it from get_email_test and other scanning tools. Uses specific verb 'process' with resource 'latest received message' and includes idempotency details.

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 instructs when to use it ('after the user reports sending the test mail') and contrasts with get_email_test for passive polling. Mentions requirements (requires testId from create_email_test), covering when/when-not and alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, which cover the non-mutating and side-effect-free nature. The description adds concrete behavior: 'Pure HTTPS GET, no auth, no side effects,' which reinforces but also goes beyond annotations by specifying the HTTP method and lack of authentication. It does not mention rate limits or response format, but given strong annotations, the description adds sufficient 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 a single paragraph but well-structured: it starts with the core purpose, then lists the file options with brief parenthetical explanations, and ends with usage guidance and a final sentence on behavior. Every sentence provides useful information; it is slightly long but justified by the number of file options.

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 one-parameter tool with no output schema, the description covers the essential aspects: what files are available, when to use the tool, and its trivial behavior. It could mention response format or status codes, but given the tool's simplicity and the strong annotations, it is adequately complete. The lack of output schema means the description doesn't need to explain return values.

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

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

Schema description coverage is 0%, but the schema itself contains a comprehensive enum for the 'file' parameter. The description explains what each file option represents (e.g., 'llms.txt (canonical agent index)', 'llms.json (structured prompt routing)'), adding meaning beyond the enum labels. It also states the default value. The description compensates well for the lack of 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 the tool reads specific IntoDNS.ai discovery files (llms.txt, llms-full.txt, etc.), providing an explicit list of file names and their purposes. It distinguishes itself from get_citation_guidance by noting the difference between machine-readable API surfaces vs. topic-narrowed citations, making it unique among siblings.

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

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

The description explicitly states when to use this tool: 'Use when an agent needs canonical citation URLs, machine-readable API surface, or prompt-routing hints for IntoDNS.ai itself.' It also provides a clear exclusion: 'use get_citation_guidance for a topic-narrowed citation list,' naming the alternative tool directly.

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, and the description reinforces this with 'Read-only — nothing on the site is changed.' It adds substantial context beyond annotations: crawls up to 20 pages, is rate-limited to 3 scans per 10 minutes, caches results for 10 minutes, and takes 30-45 seconds. These are behavioral traits an agent must know before calling.

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 (~200 words) but well-structured: it starts with the core purpose and CSP explanation, then details the scan process, returns, usage guidance, and limitations. Each sentence adds value, but it could be tightened—the explanation of what CSP is might be considered background that the agent already knows, and the list of return items is verbose. Still, it is front-loaded and logically ordered.

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 complex tool with no output schema, the description thoroughly covers what returns (detected policy, issues, origin inventory, generated CSP, plain-language notes), performance (30-45s), rate limits (3/10min), caching behavior, and read-only nature. It also gives explicit usage context. It is complete enough for an agent to decide correctly and set expectations with the user.

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 both parameters (url and strict) with inline descriptions. The tool description does not add additional meaning beyond the schema—it mentions the generated CSP forms but not how 'strict' affects the output. Since schema coverage is high, a baseline of 3 is appropriate, and the description neither enhances nor harms parameter understanding.

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 crawls a website and builds a CSP, and explicitly distinguishes itself from the sibling tool generate_security_headers by mentioning alternative usage. The verb (crawl), resource (website), and outcome (CSP) are all specific and 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?

Provides explicit when-to-use guidance: 'Use this when the user asks to audit, analyze, or create a Content-Security-Policy for a real site, fix CSP console errors, or harden a site against XSS' and names the alternative (generate_security_headers) with its key difference (no crawling). This is exactly what a usage guideline should do.

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 false. The description reinforces this with 'Read-only — no domain mutation, no destructive side effects' and adds practical behavioral context: scan duration (~3-8s), no authentication required, and the scope of returned data. This goes beyond the annotations by informing the agent about speed and authentication expectations.

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 information-dense but every sentence contributes value: the first sentence states the core function, the second details the return payload, the third asserts safety, the fourth provides usage guidance and alternatives, and the fifth gives follow-up actions and auth status. It is well-structured, front-loaded with the action, and free of 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?

The description provides a comprehensive overview of what the tool returns (grade, score, issue list, recommendations, result sections, citation URLs) and its operational characteristics. Even without an output schema, the agent knows exactly what to expect. The guidance on follow-up tools and the explicit mention of no auth round out the context. For a tool with one parameter and rich annotations, this is 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 schema covers 100% of the single parameter (domain) with a precise description including example and restrictions. The tool description does not add any additional parameter-specific semantics beyond implying the domain is the subject of the scan. With high schema coverage, a baseline score of 3 is appropriate, as the description confirms but does not augment 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 runs a DNS and email security scan with a specific verb ('Run'), identifies the resource (IntoDNS.ai), and enumerates the expected outputs (grade, score, issues, recommendations, sections, citations). It also distinguishes itself from sibling tools by calling itself 'The default tool for agent-visible scan evidence' and explicitly contrasts with get_everything_report and start_deep_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 gives explicit guidance: it names alternatives (get_everything_report for deeper reports, start_deep_scan for slower analysis) and explains when each is preferable. It also suggests follow-up actions (explain_issue, generate_dns_fix) and notes the read-only nature, which implies it's safe for initial scanning.

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 'Read-only — no domain mutation' but annotations set readOnlyHint: false, implying the tool is not read-only. This is a direct contradiction. While the description adds useful behavior like returning scanId and polling instructions, the contradiction invalidates the behavioral transparency score.

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 well-structured and each sentence adds real value: what it does, return behavior, read-only claim, use cases, alternatives, and abort mechanism. No filler or redundancy, and it is front-loaded with the core purpose.

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 (long-running, asynchronous), the description explains the immediate return of scanId, polling via get_deep_scan_status, cancellation, and no-auth requirement. It also covers domain constraints implicitly through schema. For a tool with no output schema, this is complete and self-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 description coverage is 100%, and the tool description adds no additional parameter semantics beyond the schema. It does not elaborate on domain, scanType, or name beyond what the schema already provides. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly states the action: 'Start a long-running Internet.nl deep scan' with resource scope. It explicitly differentiates from sibling tools by naming scan_domain and cancel_deep_scan, explaining when to prefer this tool. The purpose is specific and 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?

Provides explicit when-to-use guidance: 'Use when scan_domain output is not strict enough for compliance reporting, or when the user asks for an Internet.nl-grade audit' and 'For sub-10s answers, use scan_domain.' It also names cancel_deep_scan for aborting. This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description reinforces 'Read-only' and states 'Single HTTP GET, no auth, no destructive actions,' which aligns with annotations. It adds context about the specific behavior (chain walking, result types) beyond annotations, but since annotations are comprehensive, a 4 is appropriate rather than 5.

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, front-loaded with the key purpose, and every sentence adds value: says what it does, what it returns, when to use it, and alternatives. No redundant 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?

The tool is simple with one parameter, comprehensive annotations, and no output schema. The description fully covers the tool's purpose, behavior, usage, and alternatives. It does not explain exact return format but that is not required given no output schema and a simple boolean output. A 4 is appropriate because it covers the key aspects without any significant gaps; a 5 might be overkill given no output details, but this is a high-quality description.

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 only parameter 'domain' has a clear schema description. The tool description adds a bit of context ('Domain name only') but that is shared with schema. The description implies the parameter is a domain name but does not add much beyond schema, so baseline 3 is correct.

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

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

The description starts with 'Read-only DNSSEC chain validation' which is a specific verb and resource. It goes beyond mere names to explain exactly what the tool does: walks DS/DNSKEY chain, checks signatures, algorithm strength, key rollover state, and mentions outputs. This clearly distinguishes it from siblings like lookup_dns and check_tlsa_dane.

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 provides explicit usage guidance: 'Use when a domain claims DNSSEC; use lookup_dns(type='DNSKEY') for raw key data only.' This directly tells the agent when to use this tool and points to an alternative for a different purpose, making the distinction explicit.

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

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

Beyond the annotations, the description adds valuable behavioral context: data is sourced live from IANA RDAP bootstrap with rdap.org fallback, and GDPR redaction of registrant data is normal rather than an error. It also explicitly states there is no auth and no side effects, reinforcing the read-only annotation.

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 information-dense but well-structured: it fronts the core function, then return data, data source, a key caveat, use cases, and an alternative tool. Every sentence earns its place and there is no superfluous 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?

For a single-parameter tool with no output schema, the description is remarkably complete. It explains what is returned for both domains and IPs, notes live data sourcing and fallback behavior, clarifies a common confusion (GDPR redaction), and provides usage guidance and tool alternatives.

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 comprehensively documents the single parameter with 100% coverage, so the description adds little beyond restating that query is a domain name or IP address. Baseline of 3 applies because the schema carries the semantic load.

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 read-only WHOIS/RDAP lookup tool for domains or IP addresses, specifying exactly what data is returned for each input type. It distinguishes itself from sibling tools by explicitly naming lookup_dns as the alternative for 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 provides explicit use cases: check domain ownership, age, expiry, vet suspicious domains, or find an abuse contact. It also gives a direct exclusion: 'for DNS records use lookup_dns instead.'

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