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

Annotations already cover readOnly/idempotent/non-destructive/open-world, yet the description adds real value beyond them: the soonest-expiring-first result ordering and the prompt-injection warning that probed site text is untrusted data. The standalone "Read-only." sentence is redundant with readOnlyHint=true but not contradictory.

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, scope, and ordering in the first sentence, followed by the use case and security caveat. Tight overall, though the one-word "Read-only." sentence duplicates the annotation and is mild waste.

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

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

With no output schema, the description does the right work by stating the return ordering and the 10-host batch limit, and it flags untrusted input. It doesn't mention error behavior for unreachable hosts or partial failures, which a batch probe tool could usefully note.

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 are documented in-schema (port defaults, implicit TLS, mail ports, host format). The description only restates the 10-host cap already expressed by maxItems, adding no syntax or semantics the schema lacks.

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 (checks certificate expiry) plus scope (up to 10 hosts) and output ordering (soonest-expiring first). It does not explicitly distinguish itself from the sibling tls_inspect, which plausibly overlaps, so it falls 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?

"Ideal for a quick 'which of my domains need renewal?' sweep" gives a concrete use context. There are no exclusions or named alternatives (e.g. when to prefer tls_inspect), so it stops short of explicit when-not 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 openWorldHint, so the 'Read-only' line is largely redundant. However, the warning that probed-site text (titles, headers, DNS records, file contents) is untrusted data rather than instructions is genuinely valuable prompt-injection context that annotations do not 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?

Three tight sentences: purpose and scope first, then routing guidance, then the trust warning. Every sentence carries information and nothing is buried.

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 could say a bit more about return shape (e.g. per-type record sets, TTLs, resolver errors), but the record-type list and resolver note make the output sufficiently predictable for a 2-parameter read 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 both parameters are already documented in the schema, including the record-type enum and the example name format. The description's enumeration of record types mirrors the schema enum and adds no new syntax or format detail, 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 (looks up) and resource (DNS records), enumerates the supported record types, and specifies the resolver used. It clearly distinguishes itself from mail_auth, the sibling that handles SPF/DKIM/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?

Gives explicit use cases (check propagation, verify records after a change, investigate mail routing) and names the alternative for a related but distinct task: 'For SPF/DKIM/DMARC use mail_auth instead, which interprets them.' This is textbook when-to-use plus when-to-use-something-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 real information beyond the annotations: the response body is not returned, redirect hops are re-validated, and probed-site content (titles, headers, DNS records, file contents) is untrusted data rather than instructions. That prompt-injection caveat is a substantive disclosure no annotation conveys. 'Read-only' merely echoes readOnlyHint but is harmless.

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 the core behavior, followed by the usage framing and the safety caveat in the position an agent will actually read. Nothing is padded; the only near-redundancy is the two-word 'Read-only'.

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 it flags the body-not-returned limitation so an agent does not expect page content. For a four-parameter read tool this is complete.

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

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

Schema coverage is 75%; url, follow_redirects and allow_invalid_cert already carry descriptions. The description supplies meaning for the one undocumented parameter, 'method', by stating the request is GET or HEAD, and clarifies that redirect-chain reporting pairs with follow_redirects. It adds modest but genuine value over 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 and resource ('makes one GET or HEAD request') and enumerates exactly what is reported (status, redirect chain, timings, headers, size, page title, robots meta). The explicit 'response body is NOT returned' line and the tls_inspect pointer let an agent separate this from tls_inspect, redirect_chain, and security_headers 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?

Gives concrete trigger questions ('is this URL up, where does it redirect, how fast is it?') and cross-references tls_inspect for certificate diagnosis. It stops short of naming exclusions against other siblings — notably redirect_chain and security_headers, whose scope overlaps with what this tool reports.

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 openWorld, so safety is largely covered. The description adds real value beyond them: the no-mail-server-connection constraint narrows what 'open world' means here, the 'Returns a score with fixes' statement supplies return-value context despite no output schema, and the untrusted-data/prompt-injection warning is a meaningful operational caveat. Rate limits or failure behavior are not covered.

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 audited surface, then use cases, then behavioral caveats — a logical order with no filler. Each clause (lookup limit, selector probing, no server connection, untrusted data) 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?

For a three-param read-only tool with no output schema, the description covers what is checked, when to invoke it, what it returns at a high level, and the safety/untrusted-input posture. Everything an agent needs to select and call it correctly is present.

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

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

Schema description coverage is 100%, so the baseline is 3. The description references 'any you give' for DKIM selectors and mentions MTA-STS record/policy file, loosely mapping to the optional params, but adds no syntax, format, or default details beyond what the schema already documents.

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 ('Audits a domain's email authentication from public DNS') and enumerates the exact checks performed (MX, SPF with 10-lookup limit, DKIM selectors, DMARC, MTA-STS, TLS-RPT). This cleanly separates it from sibling tools like dns_lookup, tls_inspect, and security_headers, which each cover only a fragment of this surface.

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 triggering scenarios: 'mail goes to spam', spoofing concerns, and after mail-server migrations. It also states what it does NOT do ('It never connects to a mail server'), which implicitly distinguishes it from a mail-server-side check. It stops short of naming an explicit alternative tool for narrower checks, so it is clear context rather than full when/when-not routing.

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. The description adds genuinely new context: the untrusted-data warning about site-derived text (titles, headers, DNS, file contents) not being instructions, which is a security-relevant behavior annotations cannot express. It omits request volume/rate considerations, keeping 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 tight sentences, front-loaded with the action, followed by usage triggers and then the safety note. Every sentence earns its place with no redundancy.

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

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

No output schema exists, and the description conveys the analysis performed, the trigger context, and the trust boundary for returned data. It does not describe the response shape (e.g., hop list or final canonical URL), which is a minor gap for a diagnostic 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 baseline is 3, but the description adds meaning by framing the variant checks as a core outcome ('all converge on one canonical URL'), which explains why check_variants defaults to true. It does not restate syntax, which the schema already handles.

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 ('Follows the redirect chain of a URL hop by hop') plus the exact checks performed (http→https upgrade, www/non-www convergence). This is clearly distinguishable from siblings like http_probe or 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?

Gives concrete trigger conditions: 'after a migration' and 'when pages redirect too many times'. It does not name an alternative sibling tool or explicitly exclude cases, but the usage context 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 cover read-only and safe behavior, but the description adds substantial context: redirects are followed, the exact audit scope is listed, cookie flags are names only (never values), a score/grade with fixes is returned, and probed site content is flagged as untrusted data. This is rich behavioral disclosure beyond the annotations.

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

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

The description is front-loaded with the core action and scope, and every sentence earns its place. A minor redundancy is the 'Read-only' sentence, which repeats the readOnlyHint annotation, but overall it remains efficient and well-structured.

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

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

For a read-only single-parameter audit tool with no output schema, the description is complete: it explains what is fetched, what is audited, what is returned (score, grade, fixes), and the safety profile is covered by annotations. Nothing needed to call it correctly appears 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% for the single url parameter, so the schema already fully documents the parameter. The description adds no syntax or format details beyond saying it fetches a URL, which is baseline behavior 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?

The description states a specific verb (fetches/audits) and resource (security headers), lists the exact header types checked, and distinguishes itself from a penetration test. It does not explicitly name or differentiate from any sibling tool, so it falls just 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?

Usage is implied by the tool's scope ('audits security headers') and the boundary 'not a penetration test', but there is no explicit guidance on when to choose this over siblings like http_probe or tls_inspect. No alternatives or exclusions are named.

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

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

Beyond the readOnly/idempotent annotations it discloses real operational behavior: only same-host URLs are requested, the sample is capped by the server, and probed-site text is explicitly flagged as untrusted data rather than instructions. The untrusted-data warning is a genuinely valuable safety disclosure that 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-loaded with the core action and tightly written; the enumerated checks and the safety note each pull weight. The long middle clause enumerating failure types makes it slightly dense, but nothing reads as 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 does list the classes of findings an agent can expect (HTTP errors, redirects, noindex, missing titles, canonical mismatches, robots-blocked URLs), which largely substitutes for a return-value spec. It omits the shape of the report and any pagination or aggregation details, a minor 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?

Schema coverage is 100%, so both parameters are already documented, including that 'url' accepts a site root or a sitemap URL and that 'sample' is evenly spread. The description reinforces the host-scoping behavior of the request set and mentions server-side capping, adding modest value over the structured fields.

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

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

The description states a specific verb and resource (finds a site's sitemap, then audits a sample of its URLs) and enumerates exactly what is checked. It is clearly distinguishable from siblings like http_probe or redirect_chain, which operate on individual URLs rather than a sitemap corpus.

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 triggering contexts: 'Ideal after a migration or when Search Console reports submitted URL errors.' That is a clear when-to-use signal, though it never names an alternative tool or an explicit when-not-to-use condition, so it stops short of full 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 cover the safety profile (read-only, idempotent, non-destructive), so the description goes beyond them by disclosing exactly what protocol work is performed, that no application data is sent, and by surfacing the untrusted-data/instruction-injection caution for probed site content, which no annotation expresses.

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 action and return payload, then use cases, then boundaries, then a security caveat. Four compact sentences with no filler; every clause carries operational 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, yet the description enumerates the returned fields (chain, expiry, host-name match, trust, key strength, negotiated protocol, accepted TLS versions), covers the scope boundary, and includes the prompt-injection warning. For a 3-parameter read tool this is complete.

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

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

Schema coverage is 100%, with host/port/check_protocols fully documented in the schema itself. The description adds only a light gloss: the handshake context and that protocol probing is optional, which is already implied by the schema default of false. 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 (performs a TLS handshake) against a specific resource (host:port) and enumerates exactly what is reported: chain, expiry, host-name match, trust, key strength, negotiated protocol. An agent can distinguish it from siblings like cert_expiry and http_probe 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?

Explicitly names the triggering scenarios: expired or soon-to-expire certificates, 'certificate not trusted' errors, incomplete chains, and legacy protocol audits. It also draws the boundary against application-level probes with 'Only the handshake happens; no application data is sent,' which routes the agent away from http_probe when only TLS metadata is wanted.

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