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

With no annotations, the description carries the full behavioral burden and does well: it discloses that TTLs are returned, that the CNAME chain is followed (extra queries/records beyond the literal name), and that NXDOMAIN and NODATA are reported as distinct outcomes. It omits any note on timeouts, retries, or whether lookups are cached, 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 the capability sentence, then one paragraph per non-obvious parameter, with zero filler or repetition. Every clause earns its place — the type list and resolver list exist precisely because the schema declares no enums.

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?

An output schema exists, so return values need not be explained, yet the description still adds the key result discriminator (NXDOMAIN vs NODATA), which is genuinely useful. Minor gaps remain: no mention of name syntax edge cases (trailing dot, wildcards) or failure behavior if a custom resolver IP is unreachable.

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 0%, so the description must compensate, and it does: `types` gets the full valid value list plus comma-separated syntax, and `resolver` gets every accepted value ('system', 'cloudflare', 'google', 'quad9', or a literal IP with optional port). Only the required `name` parameter is left uncharacterized, though its meaning is self-evident.

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 and resource: 'Look up DNS records with TTLs, following the CNAME chain.' The scope (TTL reporting, CNAME chain traversal) is concrete. It does not differentiate itself from the closest sibling, email_dns_check, so it stops short of a 5.

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 supplies one real use case — choosing a non-system resolver 'is how you compare what different resolvers see' — which implies when the parameter matters. However, there is no explicit when-to-use-this-vs-alternative guidance, and email_dns_check (the obvious overlap) is never mentioned or excluded.

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?

With no annotations, the description carries the burden and does real work: it discloses that MX targets must resolve and must not be CNAMEs, that SPF include:/redirect= expansion is performed and lookup/void limits are counted with permerror consequences, and that DMARC policy, pct and rua are extracted. It stops short of stating that the tool is purely read-only or noting query volume/resolver rate considerations.

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 scope and followed by the per-record behavior that matters most. Every clause carries information about what will be checked or what will fail; 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?

An output schema exists, so return-value explanation is not required, and the description covers the diagnostic surface (MX, SPF limits, DMARC fields, DKIM selectors, MTA-STS/TLS-RPT) adequately for an agent to predict results. The only real hole is the undocumented `resolver` parameter and the absence of any note on query cost or timeout behavior.

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

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

Schema description coverage is 0%, so the description must compensate. It does well for `selectors`, explaining the comma-separated format, giving an example ('mail2024,s1'), and justifying why the caller must supply them because selectors are arbitrary. `domain` is self-evident, but `resolver` (defaulting to 'system') is never mentioned, leaving one of three parameters opaque.

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

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

The description opens with a specific verb and resource: 'Audit a domain's email DNS,' then enumerates exactly which records (MX, SPF, DMARC, DKIM, MTA-STS). That enumeration cleanly separates it from the generic dns_lookup and from http_check/tls_check siblings 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?

Usage is only implied by the record scope; there is no explicit statement of when to reach for this over dns_lookup or when a single-record lookup would suffice. The one concrete directive is about supplying DKIM selectors, which is operational guidance rather than tool-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?

With no annotations, the description carries the full burden and does so well: it discloses safety behavior (sends no cookies or credentials), resource limits (1 MiB body, 10 redirects, 30-second timeout), and the exact diagnostics produced. It stops short of saying whether the request is retried or how failures/timeouts are surfaced in the response, which keeps it below 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 structured into per-hop output, final-response judgments, and safety limits. No sentence is filler, and the list of limits is compact enough to scan in one pass.

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

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

The tool is simple (one required parameter, no nesting), an output schema exists so return structure needn't be described, and the description still covers purpose, limits, and the key parameter caveat. Nothing an agent needs in order 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 description coverage is 0% for the single `url` parameter, and the description compensates with a genuinely useful semantic: 'url may omit the scheme (https assumed)'. That is exactly the ambiguity an agent would hit, though nothing is said about query strings, ports, or non-HTTP schemes.

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

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

The description opens with a specific verb and resource ('Follow a URL through its redirects and time every hop') and then names exactly what is measured per hop and on the final response. That scope is distinguishable from siblings like tls_check and dns_lookup, which cover narrower slices of the same request lifecycle.

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 rather than stated: an agent can infer this is for diagnosing redirect chains and end-to-end HTTP behavior, but the description never says when to prefer it over security_headers or tls_check, even though it overlaps both (HSTS, HTTPS downgrade). No explicit exclusions or alternatives are given.

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?

No annotations exist, yet the description discloses a lot: banner collection is passive, nothing is sent, and filtered means no answer (usually a firewall). It also warns about databases/RDP/telnet exposed to the internet. Not covered are rate limiting or whether the tool needs any authorization, which leaves a small gap for a zero-annotation 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?

Dense, front-loaded prose: the core capability comes first, followed by the port syntax constraint, then the interpretation of states and the safety model. Every clause adds operational information; none 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 an output schema present, return-shape explanation is not required, and the description covers the semantics an agent needs for interpretation (open/closed/filtered, banners, risk warnings). The unexplained `timeout_s` is the only meaningful omission 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 description coverage is 0%, so the description must carry the parameters. It fully specifies the `ports` syntax and its 20-port ceiling, and implies `host` is a single host, but `timeout_s` is never mentioned, so one of three parameters is undocumented in both schema and description.

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?

Uses a specific verb-plus-resource formulation: checks TCP port reachability on one host and captures banners. It also implicitly separates itself from http_check/tls_check by framing the job as raw port state (open/closed/filtered) rather than protocol-level checks.

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

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

Gives explicit scope limits: max 20 ports per call, health check rather than scanner, CIDR ranges refused. That tells the agent when this tool is inappropriate, but it never names a sibling (e.g. http_check or tls_check) as the alternative when a protocol-level probe is wanted.

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?

Without annotations the description carries the full burden and does real work: it discloses that redirects are followed and only the final page is graded, which materially affects results. It also enumerates the specific checks (unsafe-inline/unsafe-eval/wildcard flagging, cookie flags, version-disclosing headers, cross-origin isolation), though it omits how the site is fetched, timeouts, or failure modes.

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 lead sentence front-loads the action, the scale, and the payoff, which is exactly what an agent needs first. The second sentence is a long but load-bearing enumeration; each clause maps to a distinct check, though the run-on parenthetical could be tightened.

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

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

With an output schema present the description needn't explain return values, and the single-parameter surface keeps the scope simple. The one real gap is URL input format and what happens on unreachable or non-HTML targets, which matters for a tool that performs live network fetches.

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 0% for the single url parameter, so the description would need to compensate by clarifying whether a bare domain or a scheme-qualified URL is expected. 'Follows redirects and grades the final page' adds meaningful behavior about how the URL is processed, partially filling the gap, but the accepted URL format is never stated.

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 ('Grade a site's security headers') plus the output scale (A+ to F) and what remediation content comes back ('the exact header line to add for each gap'). Enumerating the header families covered lets an agent distinguish this from siblings like http_check and tls_check 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?

Usage is strongly implied by the coverage list (use this when you care about response headers, not transport certificates), but the description never states when to reach for this versus http_check or tls_check, and offers no exclusions or prerequisites. The agent must infer sibling routing from the tool name and subject matter alone.

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?

With no annotations supplied, the description carries the full burden and does so well: it enumerates exactly what is inspected (leaf cert fields, served chain, name match, trust-store validation), distinguishes failure modes (expired, self-signed, incomplete chain, untrusted root), discloses the grading policy (WARN under 30 days, FAIL under 14), and honestly reports a capability limit (OCSP stapling not observable, only the responder URL).

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 verdict and purpose are front-loaded in the first clause, followed by the detail list and the parameter notes. The long multi-clause sentence itemizing certificate fields is dense and could be trimmed into a list, but every element it names corresponds to a distinct check the tool performs.

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 network inspection tool with an output schema and no annotations, this is complete: it explains what is tested, how results are graded, how to target non-standard TLS ports, and one known limitation. Nothing an agent needs in order to call it correctly or interpret a verdict 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 0%, so the description must compensate for both parameters, and it does: `host` is 'a name or IP (no scheme)' and `port` is for non-443 TLS services with real examples (465, 993). The only gap is that the default of 443 is left to the schema rather than restated alongside the non-443 guidance.

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 ('Check a host's TLS setup') plus the output judgement ('judge it PASS/WARN/FAIL with fixes'), which differentiates it from siblings like port_check and security_headers that inspect connectivity or HTTP headers rather than the TLS handshake and chain.

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 invocation context: 'use port for non-443 TLS services (e.g. 465, 993)' and constrains `host` to a name or IP with no scheme. It never explicitly names which sibling to use instead for raw connectivity (port_check) or HTTP-level checks (http_check), so the 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.