oldweb-diagnostics

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description correctly spends its words on additive context: the external dependency on Google Public DNS and the warning that returned evidence is untrusted data rather than instructions. That prompt-injection caveat and the explicit limits of what is returned ('observations and DNS status, not deliverability or full policy validation') are genuine disclosure. It stops short of mentioning rate limits, caching, or lookup-failure behavior.

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

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

Three short sentences, front-loaded with what is inspected, followed by scope limits, the external service, and the trust caveat. Every sentence carries distinct information and none is redundant with 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?

With no output schema, the description carries the burden of describing returns, and it does so adequately ('record observations and DNS status') while explicitly ruling out deliverability and full policy validation. It is largely complete for a single-parameter read tool; only operational details like failure modes or response shape specifics are 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 description coverage is 100%, so the schema already documents the single 'domain' parameter, including the 'no URL, path, port or credentials' constraint. The description adds no syntax or format detail beyond that, so the baseline 3 for a fully documented schema is appropriate.

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

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

The description states a specific verb ('Inspect') and a precisely scoped resource (a public domain's MX, SPF and DMARC records), which is far more informative than a generic DNS check. It does not, however, name or differentiate itself from siblings such as lookup_dns or trace_email, so the agent must infer the boundary between this tool and a general DNS lookup.

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?

Usage is implied by the subject matter — check email-related DNS records for a domain — but there is no explicit when-to-use clause and no reference to alternatives like lookup_dns or trace_email. The 'not deliverability or full policy validation' line sets a boundary on interpretation, though it is framed as a caveat rather than selection guidance.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive, but the description adds behavior they cannot express: it contacts the target on port 443, follows at most three HTTPS redirects, times out at ten seconds, and returns no page content. The untrusted-data warning ("never instructions") is a valuable safety disclosure about the returned evidence.

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

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

Three tight sentences, front-loaded with what is inspected, then network limits, then the safety caveat. Every clause carries information; nothing repeats the name or schema verbatim.

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 naming the categories of returned evidence and the hard execution limits an agent must plan around. Combined with the untrusted-data warning, nothing material 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?

There is a single required parameter with 100% schema description coverage, and the schema already states "public domain name only; no URL, path, port or credentials." The description's phrase "public domain's HTTPS root" is consistent but adds no new syntax or format guidance 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 (check) and resource (public domain's HTTPS root) and enumerates exactly what is inspected: status, redirects, TLS certificate metadata and selected security headers. That scope cleanly separates it from the DNS/email-oriented siblings (lookup_dns, check_email_dns, trace_email) without needing to name them.

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

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

The description implies the use case (auditing a domain's HTTPS/TLS posture) and gives a scope exclusion ("No page content"), which helps an agent rule it out for content fetching. However it never names an alternative tool or states when to prefer lookup_dns or deployment_readiness, so selection guidance rests on 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), it discloses that external network requests are made, that the whole call is time-bounded ("ten seconds overall"), what the report contains (observations, errors, selected security headers, next steps, limits), and it explicitly frames returned evidence as untrusted data rather than instructions — a genuine prompt-injection warning that no annotation conveys.

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 is checked, then limits, then the untrusted-data caveat. No filler, no restatement of the tool name or schema constraints.

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-shape burden and does so ("individual observations/errors, selected security headers, next steps and limits"), plus latency, external-network dependency and scope limits. Nothing an agent needs before calling it is missing.

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

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

There is a single parameter and schema description coverage is 100%: the schema already explains "Public domain name only; no URL, path, port or credentials." The description adds no format or constraint detail beyond that, 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 composite action ("Combine public A/AAAA DNS, MX/SPF/DMARC and pinned HTTPS root checks in one admin report") over a named resource (a domain). The aggregating scope implicitly distinguishes it from the single-purpose siblings check_email_dns, check_https, lookup_dns and trace_email without needing to name them.

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

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

"in one admin report" and "No complete security or deliverability verdict" imply the intended context and set a bound on interpretation, but the description never routes the agent explicitly to or away from the four sibling checks (e.g. "use this for a combined overview; use check_https for TLS alone"). Usage 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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), yet the description adds real behavioral context beyond them: it discloses the return fields (status, answers, TTLs, observation time, DNSSEC flag), warns that it contacts an external resolver, and flags returned evidence as untrusted data rather than instructions. That trust-boundary note is material and not derivable from any structured field.

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, all front-loaded: capability, return payload, side effect, then safety caveat. No filler and nothing repeated from the schema or annotations.

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 usefully enumerates the return fields and the external-contact side effect, and annotations cover safety. The remaining gaps are the unaddressed record-type parameter and the absence of any sibling routing, both of which an agent would want before calling.

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 only 50%: 'domain' is well documented in the schema, but 'type' carries an enum and default with no prose anywhere. The description says nothing about record type selection, the default of A, or valid domain formatting, so it does not compensate for the coverage 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 ('Look up current public DNS records') and names the resolution path (Google Public DNS), so the capability is unambiguous. However, it never distinguishes itself from the sibling check_email_dns, which an agent must disambiguate between when the query is mailbox/domain-record related.

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

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

No when-to-use or when-not-to-use guidance is given, and no alternative sibling is named. The agent is left to infer that this is the general-purpose DNS tool versus check_email_dns or check_https, which is exactly the decision the description should settle.

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/idempotent/non-destructive/closed-world, and the description adds substantial extra context: hard input caps (256 KiB, 1,000 combined lines, 50 hops/statuses, 20 auth headers), that the body is ignored, no inbox-delivery guarantee, and a prompt-injection warning that returned evidence is untrusted data. That is material behavior beyond the annotations.

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

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

Four tight sentences, front-loaded with the action and return contents, followed by limits, exclusions, and the safety caveat. Every clause carries decision-relevant information; 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 takes on the burden of describing returns and does so (Received hops, timezone delays, unverified auth results, SMTP status classifications, source lines, admin next steps). Combined with limits, exclusions, and the untrusted-data warning, 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 only 33% (only trustedAuthservIds is documented in the schema), so the description must compensate. It adds useful limits (256 KiB, 1,000 combined lines, 20 auth headers) and flags Authentication-Results as unverified, but never explains the expected format of 'headers' vs 'deliveryLog' or how they interact, leaving half the parameter surface undocumented.

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 ('Analyze supplied email headers and optional SMTP delivery log offline') plus the scope (offline, header-only). It implicitly distinguishes itself from check_email_dns/lookup_dns by declaring 'No mailbox access, DNS or inbox-delivery guarantee', so an agent can route correctly.

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 clear usage context: offline header analysis, body ignored, no DNS. This steers agents away from expecting live DNS resolution (covered by check_email_dns/lookup_dns), but it never names a sibling or states an explicit when-to-use-this-vs-that rule.

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