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

The annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds important context beyond annotations: the POST body is processed in-memory and not stored, no auth is required, and the input is capped at 500KB. It does not cover rate limits or detailed error behavior, so it is strong but not exhaustive.

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

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

The description is front-loaded with the core purpose and is appropriately sized for a complex analysis tool. Some detail repeats schema information, and the first sentence is dense with a long enumeration, but there is little wasted text.

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

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

For a tool with no output schema, the description does mention the 0-100 spam score, fix suggestions, and parsed verdict categories, while also covering input limits, usage routing, auth, and data handling. It still does not fully describe the returned structure, so a small gap remains.

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 rawEmail including its headers/body scope and 500,000-character limit. The description repeats that rawEmail is full headers+body with a max of 500KB but adds no additional syntax or format guidance 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 states a specific verb and resource: read-only analysis of a pasted raw RFC-5322 MIME email source. It enumerates what is parsed and produced, and names a sibling alternative, so an agent can distinguish it from create_email_test and 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?

It explicitly says when to use this tool: debugging a specific failing email when the user can paste the raw source from their MUA. It also names the alternative create_email_test for when the user can resend the email, giving a clear selection rule.

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 real context beyond the annotations: it states the operation is a single HTTPS fetch with nothing changed, which reinforces and elaborates readOnlyHint/idempotentHint, and — with no output schema — it spells out the return shape (HTTPS status, per-header present/missing + value, missing list, recommendation, server snippets). It omits failure modes (unreachable host, non-HTTPS site) and any rate/limit behavior, so it stops short of a 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?

Front-loaded with purpose and safety, then returns, then the sibling routing — a sensible order. The parenthetical explaining each header (HSTS, CSP, X-Frame-Options, etc.) is longer than an agent strictly needs for selection and could be trimmed, though it does define scope.

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

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

For a one-parameter, read-only scan with no output schema, the description covers what is fetched, what is returned, that nothing is mutated, and when to prefer the sibling. An agent has everything needed to invoke it correctly and interpret the result.

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

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

Single parameter with 100% schema description coverage, including the 'domain only, no URL/path/port' constraint, so the schema carries the semantics. The description adds only the framing that the target is a live site; it says nothing about subdomain/wildcard handling or what the tool does with an invalid domain. 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?

Specific verb (scan) plus resource (a live site's HTTP security headers), and it enumerates the headers in scope so the agent knows the exact output domain. It also names the sibling it is not (generate_security_headers), so it is distinguishable without opening any schema.

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

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

Explicit routing: '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.' That is an explicit when-to-use plus the condition that selects the alternative, not merely implied 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?

Goes well beyond the annotations: describes the mechanism (marks cancelled, polling loop withdraws the upstream batch in ~10s), the non-destructiveness in concrete terms (nothing deleted, finished results preserved), idempotency rationale ('calling this twice is safe'), error behavior (404 for unknown/expired scanId), and 'No auth'. All consistent with readOnlyHint=false, idempotentHint=true, destructiveHint=false.

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

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

Front-loaded with purpose and effect, then mechanics, then safety, then error behavior, then usage triggers. Dense and efficient, though the usage guidance lands last when it could be nearer the top, and the semicolon-chained first two sentences are slightly heavy.

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

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

No output schema exists, yet the description covers what happens on success, on repeat calls, on already-finished scans, and on unknown IDs. For a single-parameter cancel tool with annotations already covering safety flags, nothing an agent needs is missing.

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

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

Schema coverage is 100% and the scanId description already points at start_deep_scan, so baseline is 3. The description adds meaningful value by explaining the failure mode for a bad ID (404) and that the ID must come from a live scan, not an arbitrary string.

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

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

States a specific verb and resource ('Cancel an in-progress Internet.nl deep scan') and immediately distinguishes its scope from the sibling pair start_deep_scan / get_deep_scan_status. An agent knows exactly which phase of the scan lifecycle this tool occupies.

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

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

Gives explicit when-to-use conditions ('user changes their mind mid-scan' or 'polling get_deep_scan_status would otherwise time out') and an implicit when-not via 'a scan that already finished keeps its results and is left alone'. Names the sibling it complements and the parameter source from start_deep_scan.

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 annotations already establish read-only, idempotent, open-world, and non-destructive behavior. The description adds useful context: it performs an external HTTPS fetch, returns reachability and certificate metadata, and explicitly discloses important non-guarantees around SVG profile compliance, trust-chain validation, trademark ownership, and mailbox display. Minor gaps remain around fetch timeouts/retry behavior, but the behavioral disclosure is well above baseline.

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 definition is front-loaded with the core purpose and then layers in scope, return information, and limitations. Most sentences earn their place, though 'No auth or destructive actions' largely repeats annotation information and the five-sentence length is slightly heavier than necessary.

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 present, the description usefully explains what the tool returns: record syntax, URL reachability/content type, certificate subject/issuer/validity dates, and explicit issues. It also sets clear technical boundaries, making the definition complete enough for an agent to invoke it correctly for a BIMI preflight.

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

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

There is only one parameter, and the input schema describes it fully with format guidance ('Domain name only, e.g. example.com'). The description does not add further parameter-level meaning beyond implying that a domain is being checked, so the high schema coverage makes 3 the appropriate 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 states a specific verb and resource ('BIMI readiness check') and immediately identifies the concrete checks performed: parsing `default._bimi`, fetching the HTTPS SVG, and parsing VMC/CMC metadata. This clearly distinguishes it from sibling checks such as `check_dmarc`, `check_spf`, and `check_mta_sts`.

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

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

It gives a clear use case: 'Use for a technical preflight before a formal BIMI/VMC review,' and defines the boundary by listing what the tool does not certify or validate. It stops short of naming alternative tools or explicitly stating when another sibling should be used instead, so it is strong but not fully exhaustive.

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/no-destructive, and the description goes well beyond them: it explains that unavailableProviders means status unknown rather than clean, cites Spamhaus 127.255.255.x, timeouts, and RFC 5782 test-entry failures, and lists exclusion rules (DBL zones, SenderScore). This is exactly the added context the annotations cannot 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?

Dense and front-loaded: capability, then input modes, then return/unavailable semantics, then scope. A single long paragraph, but nearly every sentence carries new information; only the provider-exclusion detail is slightly heavy for the description length.

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 carries the return-value burden (listed/clean, severity, removal metadata, unavailable and disabled evidence) and explains the key semantic trap that 'unavailable' is not 'clean'. Nothing an agent needs to call and interpret this correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, and the description adds real meaning: domain triggers MX IPv4 resolution rather than a direct domain check, and at least one of the two must be supplied (resolving the ambiguity from required: 0).

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?

Opens with a specific verb+resource: a read-only query against configured public DNSBL/RBL providers, and states what the response lists. Clearly separable from the DNS/email-security siblings, none of which are blacklist lookups.

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

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

Gives explicit selection logic between the two input modes (domain -> resolve and inspect MX IPv4s, or an IPv4 ip for a direct check) and names the use case as mail-server reputation triage while excluding delisting. It does not name a sibling alternative, but the exclusions and mode guidance are strong.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description still adds value by enumerating what is returned (parsed tag map, policy strength assessment, alignment mode, warnings like missing rua or multiple records) and confirming 'single GET, no auth, no side effects' — useful operational context beyond the 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?

Three dense, front-loaded sentences: operation, return payload, routing alternative, and operational constraints. No filler and the highest-value scoping information comes first.

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

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

With no output schema and only one parameter, the description compensates by spelling out the returned structure and warning conditions, plus the no-auth/no-side-effect nature. An agent has everything needed to select and call it correctly.

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

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

Schema coverage is 100% and the single 'domain' parameter is documented with a good example and format constraint (no URL/path/port). The description adds no parameter-level detail beyond the schema, so the baseline 3 applies — the schema does the work.

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

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

States a specific verb ('fetch and parse') and resource ('_dmarc TXT record') with a clear read-only scope. It is clearly distinguishable from siblings like generate_dmarc (writes records) and parse_dmarc_report (consumes RUA reports) because it names what it returns and which sibling handles the adjacent job.

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 routes the agent: 'Use for DMARC policy review; use check_sender_requirements for combined Google/Yahoo SPF+DKIM+DMARC pass/fail verdict.' That is a concrete alternative with a selecting condition. It does not explicitly exclude generate_dmarc or parse_dmarc_report, but the primary routing decision is covered.

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

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

Annotations already cover read-only/idempotent/no-destructive, but the description adds substantial non-obvious context: the exact comparison model (whole RRset, case/trailing dots ignored, TXT case kept, TTLs ignored), the meaning of `percentage` as agreement rather than coverage, and the caveat that failed resolvers were not measured. That last point is a genuine behavioral caveat an agent could otherwise misread.

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

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

Dense but front-loaded: purpose and detection targets come first, then comparison semantics, then the return summary, then routing to lookup_dns. The `percentage` explanation is a long clause, but given there is no output schema it carries real weight. Minor redundancy in restating defaults.

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 describing what is returned (every resolver response, queried/answered/failed counts, `percentage`) and flagging the interpretive trap. Nothing an agent needs to call it correctly or interpret results is missing.

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

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

Schema coverage is 100%, so both enums and the domain format are already documented. The description restates the defaults (type A, region 'all'), which the schema already declares, and adds no new format or constraint detail beyond it. Baseline 3 is appropriate when 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?

States a specific verb (compare) and resource (DNS responses across nine public and authoritative resolvers) with the outcome it detects (propagation lag, missing answers, differing RRsets). It also names the sibling it is not (lookup_dns for a single DoH lookup), so an agent can route confidently.

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

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

Explicit trigger — 'Use when records were just changed and you suspect staleness' — paired with a named alternative and its selecting condition ('for a single DNS-over-HTTPS lookup use lookup_dns instead'). Nothing is left to inference.

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

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

Annotations already cover read-only, idempotent, non-destructive and open-world, so the safety profile is pre-declared. The description goes beyond that with operational context the annotations cannot carry: 'No auth, ~3-8s' and the fact that it returns an aggregated 0-100 score with a prioritised issue list. It stops short of failure modes or partial-check behaviour, keeping it at 4 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?

Four dense sentences, front-loaded with the composite scope, then the sibling-routing rules, then latency/auth. Every clause carries information the agent needs; nothing is padded or repeated from the schema.

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

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

No output schema exists, but the description still tells the agent what comes back (aggregated 0-100 score, prioritised issue list) in addition to what is checked, how long it takes, and that no auth is required. For a one-parameter read-only aggregate tool, nothing material is missing.

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

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

Schema description coverage is 100% and there is a single required 'domain' parameter with a clear format note (no URL/path/port). The description adds no parameter-level detail beyond what the schema already provides, so the baseline 3 applies.

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

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

Opens with a specific verb+resource ('Read-only combined email-security check') and then enumerates exactly what is covered: SPF parse, DKIM selector discovery, DMARC policy validation, MX blacklist status, and an aggregated score. This is unmistakably distinct from the granular check_spf / discover_dkim / check_dmarc siblings named in the same sentence.

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 both when to use it ('one-shot email security overview', 'replaces sequential check_spf + discover_dkim + check_dmarc + check_blacklist for the typical case') and when not to ('use check_sender_requirements specifically for Google/Yahoo bulk-sender compliance, or the individual check_* tools when you need only one signal'). The routing decision is fully resolved for the agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so 'Read-only' in the text mostly restates structured data. The description still adds real value by disclosing the per-IP resolution sequence, the four return fields, the specific warning categories (missing PTR, mismatched forward, generic ISP reverse), and the 'No auth' note. It stops short of mentioning rate limits or timeout behavior for the live DNS lookups.

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

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

The operation is front-loaded in the first clause, followed by the mechanism, then return shape, then usage. Each sentence carries distinct information with no filler, despite the description being fairly dense.

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

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

With no output schema, the description compensates by enumerating what the result contains (PTR value, forward-resolution result, match verdict, warnings) and by specifying the resolution procedure. An agent has everything needed to decide to call it and to interpret the response shape.

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

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

Schema description coverage is 100%, and the single 'domain' parameter is fully documented in the schema with format constraints (no URL, path, or port). The description adds no further parameter-level detail beyond implying MX records are derived from the domain, so the baseline of 3 for schema-covered parameters is right.

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

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

The description states a specific operation (FCrDNS round-trip check) on a specific resource (IPs behind the domain's MX records), and names the exact mechanism: PTR lookup followed by forward A/AAAA resolution. This is clearly separable from siblings such as check_blacklist, check_spf, or lookup_dns, which do different jobs.

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

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

It gives concrete usage contexts (mail deliverability audits, cluster checks, 'why is our mail being rejected' debugging) and names a companion tool (check_blacklist) for reputation signals, which routes the agent appropriately. The only minor omission is an explicit 'do not use for X', but the positive guidance is strong enough to select correctly.

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

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

Annotations already establish read-only, idempotent, open-world and non-destructive; the description adds material beyond that — no auth required, ~2-5s runtime driven by the UDP handshake timeout, and the exact composition of the check (Alt-Svc header, HTTPS/SVCB DNS records, live QUIC probe). This is precisely the latency and mechanism context an agent needs to budget calls.

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?

Front-loaded with purpose and mechanism, then return shape, then usage, then operational cost — a sensible ordering. It is dense with semicolon-joined clauses and runs slightly long for one tool, but no sentence is filler.

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

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

With no output schema, the description still explains the return contract: per-signal verdict plus an aggregate 'http3_ready' boolean. Combined with one fully-documented parameter and complete annotations, nothing essential is missing.

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

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

Schema coverage is 100% and the single `domain` parameter is already documented as 'Domain name only, e.g. example.com (no URL, path, or port)'. The description only reiterates 'for a domain', adding no format or constraint details the schema lacks, so baseline 3 applies.

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

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

Names a specific verb and resource ('Read-only HTTP/3 + QUIC support check for a domain') and immediately decomposes it into three concrete signals. An agent can distinguish this from scan_domain or analyze_security_headers without opening either schema, since neither sibling is described as probing UDP/443 QUIC handshakes.

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 scopes use: 'validating CDN/Cloudflare HTTP/3 rollouts or auditing modern transport posture' with a concrete exclusion ('not relevant for mail-only domains'). It falls short of naming a specific alternative sibling to pick instead, but the when/when-not framing is clear.

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

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

Annotations already declare readOnly/idempotent/openWorld, but the description adds real context: no authentication needed, DNS + HTTPS GET only, and the exact return payload (mode, mx allowlist, max_age, TLS cert validity, DNS/HTTPS consistency warnings). That tells the agent what network effects and outputs to expect beyond the safety 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?

Three dense sentences ordered purpose → return shape → usage pairing, with no filler. Every clause carries an actionable detail.

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

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

With one parameter, full schema coverage, no output schema, and rich annotations, the description supplies the missing piece: what the check actually returns and how it relates to sibling tools. Nothing needed to invoke it correctly is absent.

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

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

Schema coverage is 100% and the single 'domain' parameter is fully documented in the schema, including the 'no URL, path, or port' constraint. The description adds no parameter-level detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific action and resource ('Read-only check of MTA-STS') and enumerates exactly what is inspected: the _mta-sts TXT record and the HTTPS policy file. It is clearly distinguishable from neighboring tools like check_smtp_tls or check_bimi.

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

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

Names the use case ('verify enforced TLS for inbound mail') and the complementary sibling ('pair with check_smtp_tls for live STARTTLS validation'), giving the agent a routing rule rather than leaving it to infer.

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/non-destructive, and the description adds substantial context beyond them: it discloses which requirements are actively checked versus which need a real sent message and are returned as informational, explicitly refusing false passes. 'Single GET, no auth' adds access and cost detail not present in 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?

Front-loaded with the core purpose, then the check list, then the limitation and alternative routing. Dense but nearly every clause carries information; 'Returns per-requirement pass/fail/warning/info plus an explicitly limited readiness summary' is doing real work given there is no output schema.

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

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

No output schema exists, and the description compensates by describing the return shape (per-requirement pass/fail/warning/info plus a limited readiness summary) and by scoping what the tool cannot verify. An agent has everything needed to call it and interpret results 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?

Only one parameter and schema description coverage is 100%, with the schema already stating 'Domain name only, e.g. example.com (no URL, path, or port).' The description's 'domain-side' framing is consistent but adds no syntax or format detail beyond the schema, so baseline applies.

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

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

States a specific verb and resource: a read-only domain-side preflight against Google/Yahoo bulk-sender requirements, then enumerates exactly which checks it runs (SPF, DKIM, DMARC, MX, PTR/FCrDNS). It also distinguishes itself from message-level siblings by naming analyze_raw_email and create_email_test.

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

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

Explicitly says 'Use before a campaign' and routes message-level verification to analyze_raw_email or create_email_test. It also names the conditions it cannot cover (TLS use, one-click unsubscribe, complaint rate, From-header) so the agent knows when this tool is insufficient.

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 cover the safety profile (readOnly, idempotent, non-destructive, open-world), and the description adds genuinely non-obvious behavior: live TCP 25 handshakes, 10-30s latency, connections quit without sending mail, measurement is from the IntoDNS.ai vantage point, and a non-responding host yields null rather than false. The null-vs-false warning is exactly the kind of interpretation guidance annotations cannot 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 most decision-relevant constraint (first 4 MX, priority order, hosts beyond 4 untested) is front-loaded, and each subsequent sentence adds a distinct fact: operations performed, return shape, pairing guidance, latency, null semantics. Nothing repeats structured fields and nothing is padded.

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

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

With no output schema, the description fully specifies the return payload (per-MX protocol version, cert subject/issuer/SANs/validity/SHA-256 fingerprint, expiry days, FCrDNS). It also discloses the measurement vantage point and latency, which are the two things most likely to cause an agent to misreport results.

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

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

The single `domain` parameter is fully documented in the schema (domain only, no URL/path/port) at 100% coverage, so the schema carries the load. The description implies the domain drives MX lookup but adds no syntax, normalization, or edge-case detail beyond what the schema already states — 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?

States a specific verb and resource — a live STARTTLS/TLS check against the first 4 MX hosts in priority order — and enumerates exactly what is validated (cert trust chain, hostname match, expiry, EHLO capabilities, PTR/FCrDNS). It also distinguishes itself from the policy-layer sibling by naming check_mta_sts, so an agent can separate the two without opening either schema.

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

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

Explicitly says 'Use to verify inbound mail TLS posture' and points to check_mta_sts for the complementary policy layer, plus a clear scope limit (hosts beyond 4 are not tested). It stops short of naming when to prefer adjacent siblings like check_tlsa_dane or check_fcrdns, which overlap on the DANE and reverse-DNS angles, so the routing guidance is strong but not exhaustive.

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

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

Annotations already cover readOnly/openWorld/idempotent/non-destructive, and the description goes further: it discloses that the tool performs a recursive DNS walk, that it evaluates the RFC-7208 10-lookup budget, and that it emits flattening guidance near/over the limit — behavior an agent needs to anticipate latency and interpret results. 'No auth, no side effects' reinforces the annotation profile without contradicting it.

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?

Front-loaded with purpose, then behavior, then usage routing — good ordering. Slight redundancy between the description of the lookup graph/count in the second sentence and the return-value enumeration in the third, but with no output schema the return list still 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?

No output schema exists, and the description compensates by naming the returned artifacts (parsed mechanisms, lookup graph, count, qualifier, warnings). Combined with the stated RFC-7208 limit semantics, an agent knows both what it will get back and how to interpret the lookup count.

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

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

Only one parameter and schema coverage is 100%, so the schema already documents 'domain' fully (including the no-URL/path/port constraint). The description adds nothing about the domain argument beyond what the schema states, which is the baseline expectation here.

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

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

Specific verb+resource: 'Read-only SPF parse and validation for a domain', plus the scope of work (recursive include/redirect walk, lookup counting against RFC-7208). It explicitly separates itself from check_email_security, so an agent can distinguish it from the sibling without inspecting schemas.

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

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

States concrete use cases ('SPF auditing or before adding new include: senders') and names the alternative tool with its selecting condition ('use check_email_security for the broader SPF+DKIM+DMARC overview'). The choice between the two is unambiguous.

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, non-destructive behavior, but the description adds substantial context beyond them: default behavior resolves MX hosts and validates `_25._tcp` tuples, explicit ports switch query construction, and the tool returns parsed fields plus advisories. The limitation about not fetching or matching live certificates is exactly the kind of behavioral caveat an agent needs.

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 front-loaded and wastes no sentences. Each sentence contributes either scope, mode behavior, return fields, a limitation, or a routing recommendation.

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 still names the returned data (usage, selector, matching type, certificate data, syntax errors, advisories). Combined with annotations covering safety and the schema covering parameters, the definition gives an agent enough to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description still adds operational meaning for `port` by explaining the no-port MX-host behavior versus explicit `_<port>._<protocol>.<domain>` querying, though it says less about `protocol` beyond the schema enum.

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

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

States a specific verb and resource (read-only TLSA/DANE DNS record check) and immediately explains the two operating modes: default MX-host `_25._tcp` validation versus explicit-port queries. An agent can distinguish this from generation or SMTP TLS checks without inspecting the schema.

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

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

Explicitly names use cases (before publishing DANE records, troubleshooting DANE handover) and an alternative/complementary tool (`check_smtp_tls`) for live SMTP certificate evidence. It also clarifies the important limitation that this tool does not fetch or cryptographically match the live service certificate.

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?

Goes well beyond the annotations: describes the returned single-use email address with a 60-minute validity, the returned testId, the additive non-idempotent behavior (fresh session, prior sessions untouched), and that no auth is required. It reinforces idempotentHint=false without merely restating it, and adds lifecycle details absent from structured fields.

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?

Front-loads the core purpose and return values, then covers behavior, parameter meaning, use case, and next step in a compact sequence. Every sentence adds information an agent needs; nothing is padding.

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 supplies the critical return contract: a unique single-use test address valid for 60 minutes and a testId for later retrieval. It also gives the follow-up call, auth expectation, and non-destructive mutation behavior, which is complete for a one-parameter session-creation tool.

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

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

Schema coverage is 100% and the enum/default are already documented in the schema. The description adds a little meaning by saying `language` controls result text, but largely repeats the schema's enum and default rather than compensating for any gap.

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

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

States a specific verb and resource: creates a new IntoDNS.ai inbound email-test session. It explicitly distinguishes the creation step from the sibling tools get_email_test and poll_email_test by naming the returned testId as the key they consume.

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?

Clearly says when to use it: debug an outbound message's SPF/DKIM/DMARC, headers, and spam triggers, and then call poll_email_test after sending. It names the follow-up path but does not explicitly contrast create_email_test with get_email_test or state when not to use it.

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

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

Annotations only declare readOnly/idempotent/destructive booleans; the description adds the semantics behind them — write-once immutability, one snapshot per call, additive and not idempotent, and that snapshots remain resolvable months/years later. It also discloses the return payload (snapshot ID, ISO timestamp, SHA-256 hash, JSON/Markdown URLs), which annotations cannot convey. No contradictions with the 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?

Front-loaded with the action and the return contract, then the durability rationale, then the sibling routing — a sensible order. It is slightly long and the parenthetical '(additive and not idempotent)' plus 'A canonical POST' phrasing is redundant with the annotations, but no sentence is pure 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?

No output schema exists, yet the description fully specifies the return shape (ID, timestamp, content hash, stable URLs) and the immutability contract. Combined with the routing to get_report_snapshot for reads, an agent has everything needed to invoke and consume the result 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% and both parameters already document their constraints (domain format restriction, format enum), so the description cannot add much. It only gestures at the two renderings by mentioning 'JSON and Markdown renderings,' which roughly mirrors the format enum rather than extending it. 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?

Specific verb ('Create') plus specific resource ('immutable evidence snapshot of the current Everything Report for a domain'), and it enumerates what is returned. It explicitly distinguishes itself from both siblings it could be confused with: get_everything_report (live read) and get_report_snapshot (read-back).

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

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

Gives an explicit selection rule: 'Use this instead of get_everything_report when the result must remain stable,' and names the follow-up read path via get_report_snapshot. It also names concrete use cases (tickets, audit trails, NIS2/ISO evidence, LLM citations) so the agent knows the triggering context.

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

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

Annotations already declare readOnlyHint/idempotentHint, so safety is covered; the description adds the non-obvious semantics an agent could not infer: heuristic mode probes 50 common selectors and a miss is documented as inconclusive because DKIM lacks enumeration, while exact mode is one authoritative lookup. It also previews return contents (discovery method, coverage note, key tags, key strength, warnings).

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?

Front-loaded with the operation and mode split, and each sentence carries information the agent needs (mode behavior, caveat, return shape, alternative). It is dense to the point of being near the upper limit for a two-parameter tool, but no sentence is filler.

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

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

With no output schema, the description still tells the agent what comes back (discovery method, coverage note, parsed key tags, key strength, warnings). Combined with the inconclusive-miss caveat and mode selection rule, nothing needed to invoke or interpret the tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining where a selector value comes from (DKIM-Signature header or mail provider) and how supplying it changes behavior from heuristic to authoritative. It does not add format constraints, but the schema already carries those.

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

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

States a specific verb and resource ('Read-only DKIM check for a domain') and immediately splits it into two clearly named modes keyed on the `selector` parameter. An agent can distinguish this from check_dmarc or check_email_security without opening any schema.

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

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

Gives an explicit routing rule ('use exact mode whenever the selector is known') and names the alternative tool for the broader job ('use check_email_security for the broader SPF/DKIM/DMARC overview'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds the concrete endpoint ('POST to /ai/explain') and the reassertion that it 'never mutates DNS or domain state', which resolves the POST-looks-like-a-write ambiguity. It also describes the shape of the returned structured text, which annotations cannot 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?

Front-loads what the tool does, then returns, then safety, then parameter advice, then sibling routing. Four sentences, each carrying distinct information with no restatement of the name or schema.

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

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

No output schema exists, so the description's enumeration of return fields (severity, business impact, root cause, fix steps) fills that gap. Prerequisites (a prior scan's context), safety profile, and sibling routing are all covered for a 3-parameter tool.

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

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

Schema coverage is 100%, so the enum and domain format are already documented; the description still adds real value by saying to pass `context` from prior scan output (e.g. scan_domain result) to get 'higher-quality answers', which explains why the optional object parameter exists rather than just what it is.

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

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

States a concrete verb and resource ('Ask the IntoDNS.ai AI service for a plain-language explanation of one specific issue'), names example issue identifiers, and enumerates what comes back (severity, business impact, root cause, fix steps). An agent can separate it from generate_dns_fix purely from the text.

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

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

Gives an explicit sequencing rule ('Use after scan_domain when an agent needs to walk a user through *why* a finding matters') and names the alternative with its selecting condition ('use generate_dns_fix for the actual DNS record snippet'). No inference required.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description goes beyond them by disclosing what comes back (lookup counts before/after, IP count, record length, split requirement, maintenance warning) and a real durability caveat — flattened records break when a provider rotates IPs. Minor redundancy in restating 'no auth, no side effects' keeps it from a 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?

Front-loaded with the core action, then progressively adds output contents, usage trigger, and the maintenance caveat. The long enumeration of return fields in one sentence is dense but each item carries real information; nothing is 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?

No output schema exists, so the description must carry return-value burden and does: it lists the fields returned and their meaning. With the single parameter fully documented in schema and annotations covering safety, an agent has everything needed to decide and call correctly.

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

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

There is a single parameter with 100% schema description coverage, so the schema already defines the accepted domain format and constraints. The description adds no additional semantics about the domain argument (e.g., whether the apex vs. an SPF subdomain should be passed), so baseline 3 applies.

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

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

States a specific verb and resource ('Read-only SPF flattening for a domain') and then spells out the mechanism: resolving the include/a/mx/redirect graph into literal ip4/ip6 addresses. It is clearly separable from siblings like check_spf (diagnostic) and generate_spf (authoring) without opening any schema.

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

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

Explicit when: a domain hits 'too many DNS lookups' (PermError) and removing unused includes is not enough. Explicit prerequisite/alternative: run check_spf first to see the lookup graph and whether flattening is even needed. Explicit caution: treat output as a last resort. Nothing is left to inference.

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

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

Adds substantial context beyond the annotations: nothing is looked up or stored, the return payload includes the record, the `_dmarc` host, and warnings for the specific misconfigurations that break mail. It also discloses input validation behavior (rua not a mailbox, pct outside 1-100 refused with an error).

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?

Front-loads what the tool produces and the central risk (policy, not syntax) before the parameter narrative. It is dense but long; the warnings enumeration is close to restating what the return payload section already implies.

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

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

No output schema exists, yet the description covers the return shape (record, host, warnings), the non-storage behavior, and error conditions. An agent has everything needed to call it and interpret the result.

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 already 100%, so the baseline is 3; the description earns extra credit by explaining the policy trade-offs (none/quarantine/reject), why rua is mandatory in practice, and that percentage is inert at p=none, which the schema only states tersely.

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

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

States a specific verb and resource ('Build a DMARC record') and defines what the record is in DMARC terms. It implicitly distinguishes itself from the inspection siblings (check_dmarc, parse_dmarc_report) by being generative, but never names them explicitly.

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

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

Gives concrete operational guidance: start at p=none, always publish rua, use percentage for phased rollout, and warns that reject at full coverage destroys legitimate mail. It doesn't route the agent to a sibling for auditing an existing record, which keeps it just short of a 5.

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

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

The description adds important behavior beyond the annotations: it is a read-only POST to /ai/fix, the API only suggests records, and it never modifies the user's zone. It also describes the returned content: proposed records, TTL recommendations, and provider-specific notes.

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

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

The description is front-loaded with the core purpose, then covers safety, parameters, and workflow in a compact sequence. Every clause contributes useful information without unnecessary 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 tool without an output schema, the description explains what is returned and clearly frames the read-only safety model. It also covers required inputs, context usage, and the intended workflow with adjacent tools.

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 baseline is 3. The description adds useful meaning by explaining that context should come from prior scan output for tailored output, and it reinforces the required domain and issue enum.

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

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

The description states a specific verb and resource: generate copy-pasteable DNS record snippets that fix one specific issue, with an example mapping. It is clear what the tool does, but it does not explicitly differentiate itself from specialized siblings such as generate_spf 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?

It gives clear workflow context: use after explain_issue or scan_domain identifies a problem, and use lookup_dns afterwards to verify application. It does not state when not to use it or explicitly route away from sibling generators, so it falls short of the highest level.

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 real context beyond the annotations: no network read of the live site, the default-to-'recommended' fallback when neither parameter is passed, that warnings may be returned, and that config overrides preset. The only friction is a mild tension with openWorldHint=true, since the description emphasizes that nothing external is touched; that is not a direct contradiction but leaves the boundary slightly ambiguous.

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?

Front-loads the core purpose and the no-scan constraint, then preset choice, then return shape, then sibling routing — a sensible order. It is delivered as one dense paragraph of roughly 120 words, so the returns and 'use this instead' clauses are harder to scan than they would be as separate lines, but no sentence is 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 two-parameter, annotation-covered generator with no output schema, the description covers inputs (preset vs config, mutual precedence, default), what is returned (name/value pairs, config snippets for nginx/Apache/Caddy/Cloudflare/_headers/raw, plus warnings), and cost/side-effect expectations. An agent has everything needed to call it correctly in one shot.

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

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

Schema coverage is 100% and the enum already lists the three presets, but the description supplies the decision rationale for each (safe baseline, nonce-based hardened CSP, report-only rollout) and clarifies precedence ('Overrides preset when provided') plus the no-argument default. That is meaningful guidance beyond the terse schema descriptions, though it stops short of showing config object structure.

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

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

States a specific verb and resource ('Generate a complete, best-practice set of HTTP security headers') and immediately scopes what it does not do ('no scan needed, nothing about your live site is read'). It explicitly separates itself from the sibling analyze_security_headers, so an agent can pick between generating and auditing without opening either schema.

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

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

Gives explicit routing: '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 which preset applies to which situation (baseline, hardened, safe rollout) and when to prefer config over preset, covering both the when and the alternative.

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 it readOnly, idempotent, non-destructive, and openWorld, and the description adds substantial context beyond them: no DNS lookups or storage occur, invalid inputs are refused with an error, the direct lookup count is returned, and nested include/redirect lookups may not be captured. It also discloses the 255-character limit and the ten-term SPF restriction.

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 definition is front-loaded with the core purpose and is generally dense with useful detail rather than filler. It is somewhat long, but almost every sentence carries operational value: mechanism semantics, policy implications, lookup limits, return values, alternatives, and validation behavior.

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

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

For a computation-only tool with no output schema, the description covers what is returned (record, direct lookup count, limit flags, warnings, publishable DNS entry), what is not done (no lookups or storage), how invalid input is handled, and how validation should follow. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents the parameters, making 3 the baseline. The description nevertheless adds useful meaning: provider include values such as _spf.google.com, spf.protection.outlook.com, and sendgrid.net; the lookup cost of useMx/useA; and the operational implications of each policy 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 states a specific verb and resource: build an SPF DNS TXT record that lists authorized sending servers for a domain. It clearly distinguishes itself from the sibling tools check_spf and flatten_spf by naming when those are used instead. An agent can identify exactly what this tool produces without opening the schema.

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

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

It explicitly routes validation to check_spf, limits flatten_spf to existing records over the lookup limit, and explains when to use 'fail' versus 'softfail' policy. It also warns that 'pass' should never be published. Alternatives and conditions are stated 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?

Goes well beyond the annotations: the hash is computed server-side, private keys are refused by design, and it flags the two DANE failure modes (records in non-DNSSEC zones prove nothing; DANE fails closed so a new cert before propagation breaks mail). Annotations already declare readOnly/idempotent/non-destructive, and nothing here conflicts with that — the tool computes rather than publishes.

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?

Purpose is front-loaded in the first clause and every subsequent sentence carries real information (PEM handling, the three parameters, pitfalls). It is a single dense paragraph with no paragraphing or bullets, which makes it slightly harder to scan, but there is no filler to cut.

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 6-parameter generation tool with no output schema, the description covers the input contract, safety constraints, default profile rationale, failure modes, and even what the response contains (record, hash, per-number meaning, DNS entry). Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds rationale the schema lacks — why usage=3 needs no CA, why selector=1 hashes SubjectPublicKeyInfo, and why matching=1/SHA-256 survives renewal when the key is reused. It also reinforces the private-key exclusion and the host-is-not-the-domain constraint beyond the schema wording.

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

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

States a specific verb and resource — 'Build a DANE TLSA record from a certificate or public key' — and immediately frames the artifact as the DNS record that pins which certificate a mail server presents. This cleanly separates it from the sibling check_tlsa_dane (which validates existing records) without the agent needing to open either schema.

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

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

Gives strong context for when this applies: SMTP use, the 3 1 1 profile recommended because it survives renewal, and that `host` must be the MX target rather than the domain. It stops short of explicitly naming the alternative sibling (check_tlsa_dane) as the path for verifying an already-published record, so routing is implied rather than stated.

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

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

Annotations already mark it read-only, idempotent and non-destructive, but openWorldHint=true could wrongly suggest an external call in a scanning toolset. The description pre-empts that by declaring 'no scan triggered, no network call from this tool, no auth' — a genuine behavioral clarification — and names the returned field badgeUrl.

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 tight sentences, front-loaded with the core action, then behavioral guarantees, then style options, then the sibling routing. Nothing redundant and every sentence carries distinct information.

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

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

With no output schema, the description correctly states the return shape ('JSON object with badgeUrl'). For a two-parameter, side-effect-free URL builder, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description's list of style values (flat, flat-square, plastic, large) plus the default largely restates the enum. Baseline 3 applies since the schema does the semantic 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?

States a specific verb and resource — 'Build the direct SVG badge URL for a domain's security score' — and immediately scopes it as URL construction rather than a scan. It also names the sibling get_pdf_report_link, so the agent can distinguish the two link-building tools without opening either schema.

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

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

Explicitly says when to use it ('embed in README.md, GitHub, status pages, or wikis') and names the alternative with the selecting condition ('use get_pdf_report_link for a downloadable full report URL instead'). No inference required.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world, so the safety profile is covered. The description still adds real value beyond that: 'Pure data, no I/O, no auth' tells the agent there is no network call or credential requirement, and it enumerates the returned fields (canonical host, do-not-use list, citation URLs). It doesn't note caching or response size, which keeps it short of a 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?

Three sentences, front-loaded with purpose before usage routing, and every clause carries information. The one waste is the inline re-listing of all eleven enum values, which duplicates the schema and is the longest single element in an otherwise tight description.

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

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

There is no output schema, and the description compensates by naming the three things the caller receives (canonical host, do-not-use list, preferred citation URLs). Combined with the no-I/O/no-auth note and the sibling routing, an agent has everything needed to call this correctly on the first try.

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

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

Schema coverage is 100% and the single parameter has a full enum plus a default, so the schema already does the heavy lifting. The description restates the enum values verbatim ('scan_results, public_api, mxtoolbox_alternative, ...') but never explains what any topic means or how the output differs per topic, so it adds no semantic meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Return canonical IntoDNS.ai citation guidance') plus the exact payload (canonical host, do-not-use list, preferred citation URLs), and explicitly distinguishes itself from the legacy domains it is meant to displace. An agent can tell immediately this is a static data lookup, not a DNS check.

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

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

Gives an explicit trigger ('use whenever generating an answer that references DNS or email scanning evidence') and names the alternative sibling with its selection condition ('use read_llm_discovery for raw machine-readable discovery files'). No inference required to choose between the two.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered structurally. The description still adds valuable context beyond annotations: the full status lifecycle, polling cadence, no-auth, no side effects, and what becomes available once done (scores, per-test results, failures).

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 compact sentences, front-loaded with the operation, then returns, then prerequisite/polling, then alternative. Every sentence carries useful information with no filler.

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

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

With no output schema, the description supplies return content (status values, scores, per-test results, failures). It also covers prerequisites, polling behavior, alternatives, and auth/side-effect expectations, leaving nothing essential for correct invocation.

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

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

Schema coverage is 100%, so the single scanId parameter is already documented in the schema as 'Deep scan ID returned by start_deep_scan'. The description reinforces the prerequisite relationship but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('read-only status poll for a long-running Internet.nl deep scan') and immediately distinguishes scope from siblings by naming start_deep_scan and scan_domain. An agent can identify the tool without opening the schema.

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

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

Gives explicit trigger ('after start_deep_scan'), polling cadence ('every 10-30s'), termination conditions ('until done, error or cancelled'), and an alternative ('for fast single-vantage scans, prefer scan_domain'). This is close to ideal routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description still adds real value by disclosing the lifecycle behavior: 'pending' is returned until mail arrives, then a full SPF/DKIM/DMARC/headers/spam-score result appears, plus 'no auth'. The closing 'Idempotent GET' partly restates annotations, which keeps it from a 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?

Front-loaded with purpose, then return-state behavior, then dependency, then the alternative — a logical order with no filler. Minor redundancy in the trailing 'Idempotent GET, no auth', which repeats annotation hints.

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 present, the description steps in to explain the return states (pending vs. processed result fields), and it covers the prerequisite and the sibling routing. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the single parameter's description already says it comes from create_email_test, so the description only echoes that provenance. Baseline 3 is appropriate when the schema carries the parameter documentation.

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

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

States a specific verb and resource ('Read-only status read for an email-test session') and immediately distinguishes itself from both create_email_test (source of the ID) and poll_email_test (explicit processing). An agent can classify it without opening the schema.

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

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

Gives the trigger condition ('use after sending a test message to that address') and names the alternative with its selecting condition ('for explicit processing of just-arrived mail use poll_email_test'). Explicit when and when-else.

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 genuinely new operational context beyond annotations: ~5-15s latency that varies with backend cache state, and no auth requirement. The 'Read-only, no domain mutation' and 'no side effects' clauses partly restate readOnlyHint/destructiveHint, but the latency and cache-variance warning is material for an agent deciding whether to call a broad report tool.

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

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

Front-loaded and dense: purpose first, then mutation profile, latency, and alternative routing in a logical order. Slight redundancy in stating 'Read-only, no domain mutation' and then 'No auth, no side effects' at the tail, which repeats the safety message already delivered up front.

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 broad aggregate-report tool with no output schema, the description still tells the agent what sections the result contains (including canonical citation URLs), how long it takes, and which sibling to pick for speed or immutability. Nothing an agent needs to select or invoke it correctly is missing.

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

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

Schema coverage is 100% and both parameters (domain, format enum) are fully documented in the schema, so the schema carries the load. The description adds no extra detail about domain formatting or when markdown output is preferable, which is the baseline 3 case.

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

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

States a specific verb (generate) and a precisely scoped resource (complete live IntoDNS.ai report), then enumerates the covered surfaces: DNS, email auth, HTTPS, blacklist, sender requirements, citations. This makes it unmistakable versus siblings like check_spf or scan_domain which cover single facets.

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 routing guidance: use when the user asks for 'everything' or a 'deep current-state summary', with two named alternatives and the condition that selects each (scan_domain for a faster default, create_report_snapshot when the result must be immutable for audit/ticket use). No inference required.

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/non-destructive, and the description reinforces safety while adding genuinely new behavior: default 10 / max 50, the boolean-membership mode, and a disclosed endpoint limitation ('does not currently calculate rank'). It stops short of describing ordering or pagination of the list, which would complete the behavioral picture.

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

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

Four sentences, front-loaded with what the tool is, then the two modes, then the alternative. No filler or restatement of the name; every clause carries information an agent would otherwise have to infer.

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

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

No output schema exists, so the description must carry the return contract and does: a list of entries with stored score and timestamp, or a boolean membership result. Combined with the staleness caveat and the rank limitation, an agent has everything needed to call and interpret 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 coverage is 100% and already documents both parameters, so the baseline is 3; the description earns above that by explaining the consequence of supplying `domain` (switches to a boolean membership result) and restating the default/max for `limit`. It does not specify what `limit` does when `domain` is set (presumably ignored), a small 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?

Specific verb+resource (read-only fetch of the IntoDNS.ai Hall of Fame) with the scope spelled out: top-scoring public domains. It also distinguishes its two modes (list vs. membership check) and names the sibling scan_domain as the contrasting tool, so an agent can separate it from the other ~40 DNS tools without opening a schema.

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

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

States both use cases (show examples of strong DNS/email posture, or check membership) and explicitly routes the agent to scan_domain when current evidence is needed, with the reason given (Hall of Fame data may be older). It also states no auth is required, removing a common precondition question.

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, so the safety profile is covered. The description adds valuable context beyond annotations: it notes internal Redis/AI-provider/process details are redacted on the public endpoint and that it is a 'single unauthenticated GET.' It doesn't describe the exact status values or response shape, but that's minor.

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?

Front-loaded with the core identity in the first clause. Every sentence adds distinct value: scope, return values, redaction, usage, alternative, and transport/auth details. No filler or repetition.

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

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

No output schema exists, but the description explains what is returned (overall service status and observation timestamp) and what is intentionally redacted. With no parameters and clear usage guidance, the description is fully adequate for an agent to call this tool correctly.

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

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

The tool takes zero parameters, so the baseline is 4. There are no parameters to describe, and the schema coverage is 100% by default. No additional parameter semantics are 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?

States a specific verb and resource: 'Read-only public health probe for the IntoDNS.ai backend itself, not a target domain.' Clearly distinguishes from all DNS-domain tools in the sibling list and names what it returns (overall status and timestamp).

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

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

Explicitly says when to use: 'pre-flight check before batch jobs' and 'distinguish a service incident from a real DNS finding.' It also names an alternative for a related need: 'use get_stats for public usage counters instead.' No ambiguity.

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?

Goes well beyond annotations: clarifies that no scan is triggered, no network call occurs, the return value is JSON with `pdfUrl`, the fetched URL serves `application/pdf` of the latest scan, and no auth is needed. This disambiguates the openWorldHint annotation rather than contradicting it.

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?

Front-loaded with the core behavior, then scope caveat, then return value, then alternatives and auth. Dense but every clause carries decision-relevant information.

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

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

No output schema exists, and the description fully compensates by describing the returned JSON (`pdfUrl`) and what fetching it yields. Nothing an agent needs to call this correctly is missing.

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

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

Single required `domain` parameter with 100% schema description coverage, so the schema already documents the name-only format. The description adds no extra input meaning, matching the baseline for fully documented schemas.

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

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

Specific verb+resource ("Build the direct PDF report endpoint URL for a domain") with an explicit scope statement ("Pure URL construction — no scan triggered"). It names the sibling alternatives get_badge_link and create_report_snapshot, so an agent can route correctly without opening schemas.

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 ("Use for downloadable shareable reports") and names the alternatives with their distinguishing conditions (get_badge_link for embeddable SVG, create_report_snapshot for immutable hashed evidence URL).

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?

It discloses traits beyond the annotations: the report is immutable, carries its original SHA-256 content hash and timestamp, and needs no auth. It repeats the idempotency annotation, but the immutability and evidence-integrity details meaningfully extend the read-only/idempotent contract.

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 dense sentences that front-load the action and resource, then usage guidance. Every sentence earns its place, with no filler or repetition.

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

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

For a two-parameter read tool with full annotations and complete schema coverage, the description covers purpose, prerequisite, return shape, and alternatives. The only omission is the format option, which the schema already handles.

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

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

Schema coverage is 100%, with both parameters documented, including the snapshotId source and the format enum. The description reinforces where snapshotId comes from but never mentions the markdown format option, so it does not go beyond what the schema already provides.

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

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

States a specific verb (read) and resource (a previously created IntoDNS.ai Everything Report evidence snapshot), keyed by snapshot ID, and specifies what it returns: the immutable JSON report as it was at creation. It is clearly distinguishable from create_report_snapshot and get_everything_report.

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

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

Explicitly says when to use it (verify or re-read an audit-trail evidence record without re-running a live scan) and names the alternative for the opposite case (get_everything_report for current live data). It also states the prerequisite that snapshotId comes 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?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, yet the description still adds substantive context: unauthenticated, single GET, no personal data, no per-domain breakdown, no daily/weekly series, cache timestamp. What it does not do is describe the response shape or field names, which keeps it just short of a 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?

Three tightly packed sentences, front-loaded with the capability and followed immediately by the negative scope and the sibling alternative. A little of the phrasing ('read-only', 'no destructive actions') restates annotation content, but it costs only a few 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?

With no parameters and no output schema, the description carries the burden of telling the agent what comes back, and it does so by naming the counters and the cache timestamp plus the notable omissions. A brief note on response format or size would close the remaining gap.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. It correctly avoids inventing filter semantics that the empty schema does not support.

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

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

States a specific verb and resource ('read-only fetch of the public IntoDNS.ai aggregate counters') and names the exact endpoint, then enumerates the three returned values. It also distinguishes itself from get_hall_of_fame, so an agent can tell the two public-data tools apart without opening a schema.

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

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

Explicitly gives the use case ('lightweight public usage snapshot or status display') and a named alternative with its selecting condition ('use get_hall_of_fame for top-scoring public domains'). The exclusion list of what it does not return further sharpens the routing decision.

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 readOnly/idempotent/openWorld annotations, it discloses the DoH transport, the default-to-A behavior when type and types are both omitted, the exact return shape (parsed answers with TTL, raw rdata, DNSSEC AD bit), and the absence of auth and rate limits except upstream resolver limits. That is meaningful operational context an agent can't get from the annotations.

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

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

Three dense sentences, front-loaded with what the tool is, then parameter behavior, then return contract, then sibling routing. Every clause carries information; no filler.

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

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

With no output schema present, the description compensates by naming the returned fields (TTL, raw rdata, AD bit). Combined with the defaulting rule, auth/rate-limit statement, and sibling alternatives, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: the mutual-exclusivity framing of type vs types and the default of A records when both are omitted. The 'no URL, path, or port' hint for domain is also enforced in the schema, so only the defaulting rule is genuinely new.

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

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

States a specific verb and resource ('DNS record lookup') plus the transport ('via DNS-over-HTTPS'), which immediately separates it from siblings like validate_dnssec and check_dns_propagation. An agent knows exactly what the tool does without opening the schema.

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

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

Explicitly routes to alternatives with conditions: 'use validate_dnssec for full DNSSEC chain validation, or check_dns_propagation for multi-resolver consensus', and declares the generic case ('Use for arbitrary record queries'). Nothing is left to inference about when this is the right pick.

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

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

Annotations already declare this as a read-only, idempotent, open-world, non-destructive operation, and the description goes well beyond that by disclosing the return shape (0-100 weighted total, per-measure a-j status, evidence rows, gaps, fixes) and a significant limitation: it covers only the DNS and email layer of NIS2.

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

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

Three sentences, each carrying distinct payload: what it does, what it returns, and what its limitations/triggers are. The capability statement is front-loaded and no sentence is filler.

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

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

With no output schema, the description compensates by enumerating the returned fields and the per-measure status range. Combined with the explicit scope caveat and clear trigger conditions, an agent has everything needed to call it and to set user expectations correctly.

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

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

Schema coverage is 100%, so both parameters (domain, lang) are already documented in the schema, including the enum and default for lang. The description adds only that the score is computed 'for a domain' and says nothing about domain format or language handling 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?

States a specific verb (compute) and resource (NIS2 Article 21.2 readiness score) plus the mechanism (mapping IntoDNS quickscan onto the ten measures). No sibling tool covers NIS2 scoring, and the scope boundary to the DNS/email layer makes its niche 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?

Explicitly lists trigger phrases: NIS2 compliance, NIS2 readiness, Article 21.2, cyber-hygiene compliance, and EU-NIS regulation checks for a domain. The added caveat that full NIS2 compliance needs other audits effectively tells the agent when this tool alone is insufficient.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real value beyond them: parsing is in-memory, nothing is stored, and no auth is required. Since there is no output schema, spelling out the returned JSON shape (metadata, policy, per-source rows) is genuinely useful disclosure.

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 first clause establishes purpose and the input contract follows immediately; every sentence carries information. The long field enumeration in the middle is dense but justified given the absence of an output schema.

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 two-input, zero-required-parameter parser with no output schema, the description covers input formats, size limits' context, side-effect profile, and the structure of the returned JSON. An agent has everything needed to invoke it correctly without opening the schema.

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

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

Schema coverage is 100% and both parameters already carry descriptions including the 5 MB limit and the 'used when xml is omitted' condition. The description only restates that the report can be supplied as raw XML or base64 gzip, adding no syntax or precedence detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read-only parser for a DMARC aggregate (RUA) XML report (RFC 7489)') and enumerates exactly what it produces. It is clearly distinguishable from siblings like check_dmarc or generate_dmarc, which act on DNS records rather than parsing an already-fetched report.

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

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

Gives a concrete usage context ('read DMARC reports an agent fetched from the rua@ mailbox') and clarifies the two alternative input forms. It stops short of explicitly naming when not to use it (e.g. 'use check_dmarc to validate the published record instead'), so no exclusions are stated.

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

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

Adds real context beyond the annotations: idempotent POST semantics, the 'pending' branch when no message has arrived, what a successful call returns (authentication + content analysis), and the no-auth/no-destructive caveats. It doesn't fully clarify what processing does to stored state (e.g., whether a message is consumed once parsed), which is the remaining gap for a readOnlyHint=false tool.

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

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

Four tight sentences, front-loaded with the action and outcome branches, then prerequisites, then sibling routing, then safety caveats. No filler.

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

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

With no output schema, the description still covers both return branches ('pending' vs parsed authentication + content analysis), the required input's origin, and the alternative tool. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100% and the schema already documents testId as 'returned by create_email_test', so the description's 'Requires testId from create_email_test' merely restates it. No format or validation detail is added 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?

States a specific verb+resource ('Process the latest received message in an email-test session') and scopes it to the latest message only. It is immediately distinguishable from get_email_test, which is named explicitly as the passive alternative.

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

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

Gives explicit when-to-use ('after the user reports sending the test mail'), an explicit alternative with its condition ('use get_email_test for passive status polling without processing'), and a prerequisite ('Requires testId from create_email_test'). Nothing is left to inference.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered; the description still adds the auth and transport facts ('pure HTTPS GET, no auth') that annotations cannot express. It stops short of warning that llms-full.txt/llms.json may be large or verbose, which is the one behavioral risk for an agent pulling full context into a prompt.

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

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

Two sentences, front-loaded with the verb and resource, then the file enumeration, then the usage routing. The long parenthetical list in sentence one is dense but every gloss earns its place because the filenames are otherwise uninformative.

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

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

With one optional parameter, rich annotations and no output schema, the definition covers everything needed to invoke it correctly. The remaining gap is payload-scale guidance for the full-context variants, a minor omission given 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?

Schema coverage is 100% and the single enum already carries the default, so the baseline is 3. The description goes beyond it by glossing four of the six opaque filename values ('llms-full.txt (full prompt-ready context)', 'llms.json (structured prompt routing)'), which the enum names alone do not 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?

States a specific verb and resource ('Read-only fetch of an IntoDNS.ai LLM/agent discovery file') and enumerates exactly which artifacts it returns. It explicitly draws the boundary against the sibling get_citation_guidance, so an agent can separate the two without opening either schema.

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

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

Gives concrete selection criteria ('when an agent needs canonical citation URLs, machine-readable API surface, or prompt-routing hints') and names the alternative for a different need ('use get_citation_guidance for a topic-narrowed citation list'). Both when-to-use and when-to-use-something-else are present.

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

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

Annotations already declare readOnly/idempotent/openWorld, but the description adds what annotations cannot: crawl depth (up to 20 same-origin pages), 30-45s duration, a 3-per-10-minute per-IP rate limit with 10-minute cached repeats, and that nothing on the site changes. It also enumerates what the crawl detects and returns, which is real behavioral context beyond the safety 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?

Purpose is front-loaded in the first sentence and the usage/limits routing comes near the end, which is correct ordering. The explanatory sentence about what a CSP is ('the HTTP header that tells the browser...') is somewhat pedagogical for an agent audience, but it is a single sentence and the rest 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 carries the return contract fully: detected policy with issues, per-directive origin inventory, generated policy in report-only and enforce forms, plus plain-language notes. Combined with crawl limits, latency, and caching, an agent has everything needed to call it and set expectations.

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

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

Schema description coverage is 100%, so both url and strict are already documented in the schema. The description implies date-scope-like constraints (same-origin crawling) that inform the url parameter but never mentions the strict flag or how it changes output, so it adds little beyond the schema 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?

Opens with a specific verb+resource ('Crawl a live website ... build a Content-Security-Policy') plus the scope limit of 20 same-origin pages. It explicitly names the sibling it is not, generate_security_headers, and contrasts crawling vs. a generic header set, so the agent can separate the two without opening schemas.

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

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

Gives explicit triggers ('audit, analyze, or create a CSP for a real site, fix CSP console errors, harden against XSS') and an explicit alternative with its own condition ('use generate_security_headers for a generic best-practice header set without crawling'). Timing and rate-limit caveats further guide the call decision.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is largely covered; the description reinforces it ('no domain mutation, no destructive side effects') and adds non-schema facts: the ~3-8s runtime, 'No auth', and the shape of the response. It does not discuss rate limits or failure modes, so it stops short of a 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?

Front-loads the core action, timing, and return payload, then moves to routing and follow-ups. It is dense but every clause carries information; the return-payload enumeration is slightly list-heavy but still earns its place given no output schema.

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

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

With no output schema and only one parameter, the description carries the burden well: it enumerates return contents (letter grade, numeric score, issue list, recommendations, result sections, citation URLs), notes the runtime and auth requirements, and points to alternatives and follow-up tools.

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

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

Single parameter with 100% schema description coverage, so the schema already explains 'domain name only, no URL, path, or port'. The description adds no further parameter syntax or format guidance, making the baseline 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?

States a specific verb and resource ('Run the fast IntoDNS.ai DNS and email security scan'), gives the runtime, and enumerates the deliverables (grade, score, issues, recommendations, citation URLs). It explicitly contrasts itself with get_everything_report and start_deep_scan, so the agent can distinguish it from siblings without opening schemas.

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

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

States it is 'the default tool for agent-visible scan evidence' and names the conditions selecting alternatives: get_everything_report for deeper single-shot reporting, start_deep_scan for slower Internet.nl-grade analysis. It also routes post-scan follow-up to explain_issue and generate_dns_fix.

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 behavior beyond the annotations: scans queue and can take minutes, the server times out after 30 minutes, a scanId is returned immediately, and every call starts a new scan despite non-idempotent annotations. It also clarifies that the domain itself is not modified, which helps reconcile the non-read-only server state with the read-only effect on the target domain.

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

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

The description is front-loaded with the core action and timing behavior, then proceeds to polling, idempotency, side effects, and alternatives. Every sentence provides useful operational or routing information 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?

Although there is no output schema, the description explains the immediate return value (scanId) and the required polling flow with terminal statuses. It also covers timeout behavior, non-idempotency, side effects, and alternatives, which is complete for this long-running scan 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 100%, so the domain, name, and scanType parameters are already documented in the input schema. The description does not add meaningful semantics about the parameters beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description states a specific verb and resource: start a long-running Internet.nl deep scan. It clearly distinguishes this from the sibling scan_domain by naming both and explaining the compliance-audit depth difference.

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

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

It gives explicit when-to-use guidance: scan_domain output is insufficient for compliance reporting or the user requests an Internet.nl-grade audit. It also names alternatives for fast answers (scan_domain) and abortion (cancel_deep_scan), and explains polling via get_deep_scan_status.

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 real context beyond annotations: what the walk covers (root-to-leaf DS/DNSKEY), what is reported (chain steps, algorithm grades, boolean valid), and that it costs a single HTTP GET with no auth. The 'no destructive actions' phrase partly restates destructiveHint=false, which keeps it just short of 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?

Front-loaded with the core operation, then scope, then output, then routing advice; every sentence is informative. The trailing 'no auth, no destructive actions' clause is mildly redundant with the annotations, costing a point.

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 present, the description compensates by naming the returned fields (chain steps, algorithm grades, valid) and the failure modes it surfaces (broken links, unsigned zones). An agent has everything needed to call and interpret it.

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

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

The single domain parameter is already fully documented in the schema (coverage 100%), including the no-URL/path/port constraint. The description adds no format or edge-case detail beyond that, so the schema does all the work.

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

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

States a specific verb and resource ('Read-only DNSSEC chain validation') plus the concrete scope: walks DS/DNSKEY chain from root, checks signatures, algorithm strength, key rollover, broken links. It is clearly distinguishable from lookup_dns, which is named explicitly as the raw-key alternative.

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

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

Gives an explicit trigger ('Use when a domain claims DNSSEC') and an explicit alternative with the selecting condition ('use lookup_dns(type=\'DNSKEY\') for raw key data only'). No inference required.

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 far beyond the hints by explaining the operational behavior: the specific data sources (IANA RDAP, rdap.org fallback), the safety profile (No auth, no side effects), and a critical policy detail (GDPR redaction), which is vital behavioral context.

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

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

The text is dense but highly efficient, front-loading the core function and separating the functional description from the operational details (GDPR, data sources) and the routing advice, ensuring high information density without 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 the complexity of integrating with external data sources and adhering to privacy standards (GDPR), the description provides every piece of necessary information. It covers use cases, output contents, safety, and alternative tools.

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 significant semantic value by explicitly defining that the `query` parameter accepts *either* a domain name *or* an IPv4/IPv6 address. This clarifies expected input formats beyond the generic string type in the schema.

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

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

The purpose is stated immediately as a 'Read-only WHOIS/RDAP lookup' and clearly delineates the scope: domains vs. IP addresses. It explicitly directs the user to a sibling tool, `lookup_dns`, if their goal is DNS record checking, making the differentiation perfect.

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 a robust 'when-to-use' section (check ownership, age, vet suspicious domains) and a definitive 'when-not-to-use' clause (direct users to `lookup_dns` for DNS records). This eliminates ambiguity for the agent.

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