Cognita

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

No annotations are provided, so the description carries the full burden; it does disclose 'Read-only', which is the key safety trait for an agent. However it says nothing about rate limits, lookup failures (e.g. no abuse contact found), or what is returned when a host resolves to multiple IPs.

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?

One tightly front-loaded sentence covering purpose, source, use case, and safety trait with zero filler. The key action is stated 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?

For a single-parameter lookup with no output schema and no annotations, the description supplies source, scope, motivation, and read-only status. Minor gap: it doesn't say what happens on a host with no resolvable IP or no listed abuse contact.

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 is fully documented with examples in the schema. The description adds only the host-resolution nuance, which the schema's 'host name' example already implies, so baseline 3 is appropriate.

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

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

States a specific verb ('Find'), the exact resource (abuse-reporting e-mail(s) for an IP or resolved host IP), and names the backing service (RIPEstat's abuse-contact-finder). It also implicitly distinguishes itself from sibling 'disclosure_contacts' by scoping to IP-based abuse reporting.

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 context ('where to report a scanner or attacker surfaced by ip_reputation'), explicitly pointing to the upstream sibling that generates the need. No explicit when-not or alternative tool named, so it falls 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?

With no annotations, the description carries the full behavioral burden. It does add two useful facts beyond the schema: the operation is read-only and it depends on a configured GeoIP database (a real failure mode). It says nothing about rate limits, accuracy caveats, or what happens when the database is missing, so coverage is partial rather than rich.

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 short sentences, front-loaded with the core action and its outputs, then the prerequisite and read-only status. Every clause earns its place with no restatement of the tool name or filler.

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

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

For a single-parameter, no-output-schema read tool this is close to sufficient: it names the returned fields, the input flexibility, the read-only nature, and the database prerequisite. Only minor gaps remain, such as error behavior when no GeoIP database is configured, which keeps it from a 5.

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

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

One parameter with 100% schema description coverage, so the schema already documents target as 'IP address or host name'. The description adds only the mild clarification that a host name is resolved before lookup, which is a small increment over the schema's own example. 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 (geolocate) plus resource (IP/host) and an enumeration of what is returned: ASN, network organisation, city/country. An agent can immediately tell this is a geolocation lookup. However, it does not distinguish itself from siblings with overlapping scope such as geo_route, asn_prefixes, or ip_reputation, 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?

Usage is implied by the purpose (use when you need ASN/geo data for an IP), and one prerequisite is stated: a configured GeoIP database must exist. There is no explicit when-to-use versus alternatives, e.g. geo_route for routing paths or asn_prefixes for CIDR blocks, leaving the agent to infer routing between adjacent tools.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the safety profile ('Read-only') and the upstream source (RIPEstat), which is useful, but says nothing about rate limits, cache freshness, pagination, or failure modes for a network lookup that can return many prefixes.

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?

A single front-loaded sentence that names the action, the resource, the data source, and the safety profile with no filler. The em-dash appositive is mildly redundant with the opening clause but still earns its place by defining 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 lookup with no output schema, the description covers purpose, source, and read-only status adequately, and gestures at the return content ('with the network holder'). It could say more about the shape or volume of results, but nothing essential to calling 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 schema already documents the single parameter with format examples ('13335 or AS13335'). The description adds no syntax, accepted-format, or interpretation 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 verb and resource ('List the IP prefixes an autonomous system announces') and even clarifies the notion with 'the routed footprint of an ASN', which separates it in spirit from siblings like asn_geoip or asn_relations. It never names an alternative explicitly, so it falls just short of full sibling differentiation.

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?

There is no statement of when to use this tool, when not to, or which sibling to prefer (asn_geoip, asn_relations, rpki_validation all operate on ASNs). The usage is only inferable from the phrase 'routed footprint', which is descriptive rather than prescriptive.

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 provided, the description carries the full behavioral burden and does well: it discloses the data source (RIPEstat), that it is keyless (no API key required), that it is read-only, that results come from observed AS paths, and that neighbours are ordered by observation frequency. It does not cover rate limits or error behavior, but the core operational traits are present.

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 verb and resource, followed by two terse supporting fragments ('complementing asn_prefixes...' and 'Read-only.'). The first sentence is a bit long and nested with parentheticals, but every clause adds useful information and there is 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?

For a simple one-parameter tool with no output schema, the description is complete: it covers purpose, data source, read-only nature, return ordering, and the sibling relationship. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100% for the single 'asn' parameter, and the schema already provides the example '13335 or AS13335'. The description adds no additional syntax, format, or validation details beyond what the schema supplies, 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 ('Report') and resource ('autonomous system's BGP relationships'), then enumerates exactly what is returned: upstreams, downstreams, and peers. It explicitly names the sibling asn_prefixes as complementary, letting an agent distinguish 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?

The phrase 'complementing asn_prefixes (its routed footprint)' gives clear context for when to use this tool versus that sibling: this one for connectivity, asn_prefixes for routed prefixes. However, it does not state explicit exclusions or when-not to use it relative to other ASN-related siblings like asn_geoip or geo_route.

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. It usefully discloses that queries are read-only DNS lookups and explains the MX-then-A resolution ordering, but it does not state which blocklists are consulted, whether results are aggregated, or anything about rate limits 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?

Three tight sentences with the core purpose front-loaded and the resolution rules following in priority order. Slightly dense with em-dashes, but no sentence 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?

For a single-parameter, no-annotation, no-output-schema tool, the description covers resolution behavior and read-only safety adequately. It stops short of describing what a positive/negative result looks like or the edge case of a domain with neither MX nor A record.

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 slightly beyond the schema by spelling out the fallback chain (MX IPs, then A record when no MX, literal IP checked directly), which helps an agent predict what the single `target` parameter will actually resolve to.

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 gives a specific verb and resource ('Check whether a mail server is listed on common email DNS blocklists'), making the email-reputation focus clear. However, it never names or differentiates itself from the sibling ip_blocklist_check, so an agent must infer the distinction on its own.

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 — the DNSBL/email-reputation framing hints at when this tool applies, and the MX-vs-A logic clarifies scope. There is no explicit when-to-use, when-not-to-use, or routing to the obvious alternative (ip_blocklist_check).

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 well: it declares 'Read-only' and, importantly, bounds its own claim by stating the DNSSEC signal is 'DNSKEY presence + Authenticated-Data flag — not a full chain validation'. That prevents an agent from over-trusting the result. It stops short of mentioning rate limits, auth, or query 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?

One tightly packed sentence with the primary resource (CAA) front-loaded, followed by the secondary signal and its caveat. No filler; every clause carries 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?

There is no output schema and no annotations, so the description must convey return content, and it does — it names the two result categories and their interpretation. It is nearly complete, missing only error/no-record behavior and pagination or output-shape detail.

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 'domain' parameter, so the schema already documents the field and its example. The description adds no extra syntax, format, or edge-case detail (e.g. subdomain handling) beyond what is already structured, 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?

Specific verb+resource: reports a domain's CAA records, and explicitly parenthesizes what CAA means ('which CAs may issue its certificates'). It also names the second output (DNSSEC signal) precisely, so an agent can distinguish it from generic 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 (checking which CAs are authorized to issue certs), but there is no explicit when-to-use guidance, no prerequisites, and no routing to or away from siblings such as dns_lookup, cert_transparency, or cert_revocation.

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 provided, the description carries the full burden and does so well: it discloses that data comes straight from the leaf certificate, that no live lookup occurs, that only a benign TLS handshake with no HTTP request is made, and that it is guarded against internal targets. These are exactly the behavioral traits an agent needs before invoking.

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 written sentences: purpose first, then the crucial negative scope clarification, then behavioral/safety notes. No sentence is filler and the most important distinctions are front-loaded.

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

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

No output schema exists, and the description still names the returned information (OCSP responders, CRL distribution points, must-staple flag) plus the safety posture. 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% and both parameters (host, port) are fully described in the schema. The description adds no syntax or format detail beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('Report the revocation posture of the certificate a host serves') and enumerates exactly what is reported: OCSP responders, CRL distribution points, and must-staple status. It explicitly names its sibling tls_certificate as a complement, so an agent can distinguish 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 a clear when/when-not: it 'does NOT perform a live OCSP/CRL lookup' and answers 'can revocation be checked, and how?' rather than 'is it revoked now?'. This is an explicit boundary that routes the agent correctly, and it points to tls_certificate as the complementary tool.

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

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

With no annotations, the description carries the burden and does well: it discloses that the tool reads public logs only ('never touches the target'), that results are historical and may belong to a previous owner, and how to mitigate with `since`. It does not mention rate limits or latency for crt.sh, which would complete the 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?

Three sentences, front-loaded with what the tool does and what it returns, followed by the key usage caveat. No filler; slightly dense but every sentence earns its place.

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

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

For a two-parameter read-only enumeration tool with no output schema, the description is nearly complete: it explains data source, return contents, safety profile, and the historical caveat. Remaining gaps are minor operational details like result limits or rate 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 coverage is 100%, so the schema already documents both parameters, including `since` with format and semantics. The description reinforces the rationale for `since` (registration date to exclude prior owners) but adds no syntax beyond what the schema 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: enumerates subdomains and certificate-issuance history from CT logs (crt.sh), naming exactly what is returned (names, issuing CAs, issuance span). It is clearly distinguishable from siblings like tls_certificate or ct_org_search by its per-domain historical scope.

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

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

The description gives strong context: use it to reveal names even behind a CDN without touching the target, and warns that CT is historical, advising use of `since` (registration date) to exclude a previous owner's names. It lacks an explicit named alternative or exclusion against siblings like ct_org_search, so it falls short of 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?

With no annotations, the description carries the full disclosure burden and does state 'Passive OSINT, read-only' plus the data source (crt.sh), which are valuable behavioral cues. However, it omits rate limits, auth/quota behavior, and how empty results are handled — meaningful gaps for a tool with zero annotation coverage.

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 output, followed by the sibling differentiation and a short read-only tag. It is dense but every clause earns its place; the trailing 'Passive OSINT, read-only.' is a slightly abrupt fragment rather than integrated prose.

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 does note what comes back (the certificates and their distinct registrable domains), covering the return-value gap. A single fully-documented parameter rounds it out, though operational details like result limits remain unaddressed.

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

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

Schema coverage is 100% for the single required parameter, so the baseline is 3. The description reinforces that the organization name must match how it appears on certificates, but adds no format details beyond the schema's own example ('GitHub, Inc.').

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: finds certificates naming an organisation in Certificate Transparency and the distinct registrable domains on them. It explicitly differentiates from the sibling cert_transparency by characterizing itself as an org-to-domain-footprint link versus cert_transparency's per-domain view.

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 frames the tool as 'complementing cert_transparency's per-domain view', which signals when this org-based search is the right choice over the domain-based sibling. It stops short of explicit when-not conditions or other alternatives (e.g. related_domains), so it is clear context rather than 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?

With no annotations, the description carries the full burden and does well: it discloses that access is keyless, that NVD is rate-limited without a key, and that the operation is read-only. It does not state failure behavior for unknown/malformed CVE IDs, 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?

Two tight sentences that are front-loaded with the action and resource, then pack return fields, input provenance, auth/rate-limit, and safety into the remainder. 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?

There is no output schema or annotation coverage, so the description must stand alone — and it does, enumerating the return payload, the input expectation, provenance, and operational constraints. An agent has everything needed to invoke 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?

Only one parameter, and schema description coverage is 100% with the example 'CVE-2021-44228' already embedded in the schema. The description adds the notion of a 'bare CVE ID' but no format rules, accepted forms, or normalization behavior beyond what the schema 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?

The description names a precise verb and resource ('Look up a CVE in the NVD') and enumerates exactly what is returned (description, CVSS base score/severity/vector, CWE IDs, dates, references), so the agent knows precisely what this does. It does not, however, differentiate itself from closely related siblings such as cve_triage, kev_check, or epss_score, which a 5 would require.

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?

'Turns a bare CVE ID (e.g. one from host_exposure) into meaning' gives a clear triggering condition and ties the tool to an upstream sibling, so the agent knows when to reach for it. It stops short of saying when NOT to use it or naming the alternative enrichment tools (cve_triage, kev_check, epss_score).

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 well: it discloses 'keyless, read-only,' tells the agent the first resolved IP is used for a host name, and describes the fetch behavior (one cached KEV fetch, one batched EPSS request). It omits error/edge behavior for unresolvable hosts, but the safety and network profile is well 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 action and method, then ranking logic, then the resolution caveat and behavioral notes. Dense but each sentence carries information; mildly packed rather than wasteful.

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-param, no-annotation, no-output-schema tool, the description covers input handling, processing, output priority tiers, and read-only/keyless behavior. Sufficient for correct invocation; only granular return shape is left implicit, which is minor given no output 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% for the single 'target' param, so baseline is 3; the description adds real meaning beyond the schema by stating the host-name-to-first-resolved-IP resolution rule, which the schema does not mention.

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 ('prioritise a host's internet-exposed CVEs') and explains the exact enrichment pipeline (Shodan InternetDB CVEs -> CISA KEV + FIRST EPSS). This clearly distinguishes it from siblings like cve_lookup, kev_check, and epss_score, which it composes rather than duplicates.

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 makes clear when this applies (you have a host and want patch ordering) and names its data source, host_exposure. It does not explicitly state when NOT to use it or name the single-CVE alternatives, but the 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?

With no annotations present, the description carries the full disclosure burden and does well: it declares the operation is keyless (no API auth needed) and read-only, and it explains the return shape (both contact sets plus a yes/no on channel existence). It omits details like rate limits or what happens when no channel exists, but the safety and auth profile is solidly 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?

Three sentences, front-loaded with the core purpose, zero redundant filler. Each clause adds information: the two sources, the return contents, and the operational profile (keyless, 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?

For a single-parameter aggregation tool with no output schema, the description covers everything an agent needs: what it returns (both contact sets and a channel-exists flag), where the data comes from, and the read-only/keyless operating constraints.

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, so the baseline is 3. The description clarifies the domain is the subject being investigated for reporting contacts but adds no syntax or format detail beyond what the schema already carries.

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 (Consolidate) and resource (reporting contacts for a domain), and explicitly names the two underlying sources it merges: security_txt (RFC 9116) and the operator's abuse mailbox via abuse_contact/RIPEstat. This lets an agent distinguish it from the sibling security_txt and abuse_contact tools 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?

The 'Consolidate' framing plus naming of both source tools clearly signals when this is the right call: the agent wants both the owner's channel and the operator's mailbox in one shot. However, it never explicitly states when NOT to use it or that calling security_txt/abuse_contact separately is the alternative — the routing is implied rather than spelled out.

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 are provided, so the description carries the burden. 'Read-only' is a useful safety disclosure and the DNS name pattern clarifies what is queried, but there is no mention of behavior for a missing/invalid selector, error handling, or return format for what is a network lookup.

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 tight sentences with zero filler; the operation and its scope are front-loaded, and the selector-sourcing hint follows logically.

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

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

For a simple two-parameter read-only DNS query with no output schema, the description covers purpose, input sourcing, and safety. It is nearly complete, with only error/empty-result behavior left unstated.

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 genuine meaning: it explains that selector originates from the DKIM-Signature s= tag and shows how both parameters combine into the queried record name. That is beyond what the schema states.

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: 'Fetch a domain's DKIM public-key record' with the exact DNS name pattern (<selector>._domainkey.<domain>) spelled out, which cleanly separates it from spf_check/dmarc_check siblings. It does not name an alternative explicitly, 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?

Adds real context on where the selector comes from (an email's DKIM-Signature s= tag or a known default), which tells the agent how to obtain the input. However it gives no when-to-use vs. alternatives guidance relative to dmarc_check, spf_check, or email_posture.

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 itself: it explicitly declares the operation is read-only and discloses what the analysis surfaces (policy value plus warnings for weak or missing policies). It doesn't mention rate limits, auth requirements, or behavior on malformed domains, so it stops short of a full 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?

A single sentence with a colon-delimited payload, front-loading the action and the _dmarc TXT target, then the returned content, and closing with the read-only trait. No sentence is wasted.

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

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

For a one-parameter read-only lookup with no output schema, the description covers the query target, the meaningful output (policy + warnings), and the safety profile. Only the absence of any note on error/empty-result behavior keeps it from being fully 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% and there is exactly one parameter, so the schema already fully documents the `domain` input. The description adds the useful notion that the lookup targets the _dmarc TXT record, but gives no additional syntax or format detail beyond the schema's example.

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/analyse) and resource (DMARC record via _dmarc TXT), plus the exact payoff: the policy value and warnings. This distinguishes it cleanly from siblings like spf_check, dkim_lookup, and email_posture 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?

There is no when-to-use guidance, no mention of when this tool is preferable to spf_check or email_posture, and no stated prerequisites or limits. The usage context is only loosely implied by the subject matter (email authentication posture).

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 state 'Read-only' plus the default record set returned, which is genuine behavioral context. It says nothing about failure modes (NXDOMAIN, timeout), rate limits, or whether the lookup hits authoritative or resolver caches.

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 clauses, front-loaded with the action, then the default return set, then the narrowing option and safety note. Every sentence earns its place 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?

For a two-parameter read tool with no output schema, the description covers what is returned and how to narrow it, which is the key missing piece an agent needs. It stops short of describing error output or response shape, but is otherwise adequate.

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 both parameters are documented with examples and a default, so the schema does the heavy lifting. The description only restates the 'types' narrowing behavior and the default set, adding no syntax or format detail 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?

Names a specific verb (Resolve) and resource (DNS records for a host name) and enumerates the default record set, so the agent knows exactly what it gets back. It does not explicitly distinguish itself from close siblings such as mx_lookup, reverse_dns or dns_propagation, which keeps it 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 only implied: it is the general-purpose DNS resolver, and 'pass types to narrow' hints at the narrowing workflow but never says when to prefer mx_lookup or another sibling instead. No when-not conditions or prerequisites 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?

With no annotations, the description carries the full burden and does so: it declares read-only, states it reads resolvers' views and never queries the target host, and previews the return shape (per-resolver record set and DNS status, an agreement flag, and a note). This is unusually rich behavioral disclosure for a no-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?

Front-loaded with the core action, then the interpretation rules. The geoBalanced/anycast explanation is a long clause, but it earns its place by preventing a false divergence alarm; overall it is dense rather than 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?

There is no output schema, so the description must and does describe the return payload. Combined with the read-only statement, the never-queries-host constraint, and the interpretation guidance, nothing essential for correct invocation is missing.

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

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

Schema coverage is 100% with only two params, so the schema already documents both. The listed record types and the default of A merely mirror the schema, adding no new syntax or format detail; baseline 3 applies 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 and resource — querying several named public resolvers over DNS-over-HTTPS and comparing their answers. The multi-resolver comparison scope inherently differentiates it from single-resolver siblings like dns_lookup and reverse_dns, so an agent can route correctly 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?

Explains what a result means in practice: agreement is normal, divergence signals propagation/stale cache/split-horizon, and the geoBalanced shared-ASN case is expected CDN behavior. That gives clear diagnostic context for when to reach for this tool, but it never names an alternative tool or an explicit when-not condition.

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 provided, so the description carries the burden; it discloses keyless access, read-only nature, hostname-to-IP resolution behavior (first resolved IP), the observation window concept, and how to interpret counts (high = scanning/attacking). Lacks rate-limit or failure-mode details.

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

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

Three tight sentences, front-loaded with the source and returned fields, then interpretation, then edge-case handling, then safety. No 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?

For a single-parameter read tool with no output schema and no annotations, the description is largely complete: source, output dimensions, interpretation, and hostname behavior. Could note response shape or data freshness windows more explicitly.

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 baseline 3 applies. The description adds the hostname-resolution nuance (first IP used) beyond the schema, but does not elaborate further on the single target parameter.

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 (look up) and resource (IP reputation in SANS DShield), plus concrete data returned: attack report counts, target sensor spread, network/AS, and ISC threat feed membership. Clearly distinct from generic siblings like ip_reputation or ip_reputation_aggregate by naming the data source.

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?

Implies usage (reputation lookup, scanning signal) but never states when to choose this over sibling tools such as ip_reputation_aggregate, blacklist_check, or tor_exit_check. No explicit exclusions or selection criteria.

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

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

With no annotations, the description carries the burden and does well: it explicitly states 'no network' (offline, safe, no side effects) and lists the outputs it produces, including warnings. It doesn't mention error behavior for malformed headers, but it gives a solid behavioral picture for a read-only parser.

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 core action and output list, followed by a critical constraint ('Pure parsing — no network'). Every phrase 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?

For a single-parameter, no-annotation tool, the description covers what it does, what it returns (types of verdicts and warnings), and a key behavioral constraint. It lacks detail on output shape or handling of malformed input, but no output schema exists and the description is sufficient for an agent to invoke 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 the baseline is 3. The description adds that the input is 'pasted raw email headers' which reinforces the required format, but doesn't add syntax or format guidance beyond the schema's 'copied verbatim from the message source'. A baseline 4 is slightly generous; 3.5 would be apt. However, the description does tell the agent the tool expects raw header text specifically, which complements the schema.

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

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

The description uses a specific verb ('Parse') and resource ('pasted raw email headers'), and enumerates exactly what it extracts: Received path with per-hop delays, SPF/DKIM/DMARC verdicts, originating IP, and spoofing warnings. This clearly distinguishes it from siblings like spf_check or dkim_lookup, which perform live lookups rather than parse pasted headers.

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 phrase 'Pure parsing — no network' clearly signals the context: use this when you already have raw headers and want offline analysis, not live DNS checks. It doesn't explicitly name alternatives like dkim_lookup or spf_check, which would be the live-lookup siblings, but the distinction is strongly implied.

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 are provided, so the description carries the full burden, and it does meaningful work: it discloses the operational footprint ('read-only DNS plus one GET of the public MTA-STS policy file') and that output includes warnings on weak/missing configuration. It omits any note on rate limits, failure modes when the MTA-STS policy file is unreachable, or caching 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?

Two sentences, front-loaded with the verb and resource, then the record breakdown, then the behavioral disclosure. No filler or redundancy; every clause carries 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 must tell the agent what comes back, and it does: enforce/testing mode, max_age, MX for MTA-STS, reporting address for TLS-RPT, logo + VMC for BIMI, plus warnings. Nothing critical for correct invocation or interpretation 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 'domain' parameter with a 100% schema description, so the schema already does the work. The description only refers to 'a domain's' records without adding format, TLD, or subdomain-handling semantics, which is the expected baseline when coverage is complete.

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 (report) and resource (a domain's modern email-security records) and enumerates the exact record types covered: MTA-STS, TLS-RPT, BIMI. The phrase 'beyond SPF/DMARC/DKIM' cleanly separates it from siblings like spf_check, dmarc_check, and dkim_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?

The 'beyond SPF/DMARC/DKIM' framing tells the agent this tool complements rather than replaces the SPF/DMARC/DKIM siblings, and the mention of warnings hints at triage use. However, it never gives an explicit when-to-use or when-not-to-use directive (e.g. 'run this after dmarc_check to surface modern-record gaps').

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 are provided, so the description must carry the safety profile, and it does disclose two meaningful traits: 'Keyless' (no API key/auth needed) and 'read-only' (non-mutating). It stops short of rate-limit or failure-mode detail, but the key operational facts an agent needs are present.

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 tight sentences with the core purpose front-loaded and no redundant restatement of the title. The trailing 'Keyless, read-only' clause earns its place by supplying the missing annotation information compactly.

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 fills the gap by explaining the return values (0–1 probability, 30-day window, percentile rank). Combined with the keyless/read-only note, an agent has everything required to call and interpret this single-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?

Only one parameter exists and the schema documents it at 100% coverage with a format example ('CVE-2021-44228'), so the schema does the heavy lifting. The description adds interpretive value about what the returned score means but nothing about the input 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 and resource ('Get a CVE's EPSS score') and immediately defines what that value means (exploitation probability over 30 days plus percentile rank). It explicitly differentiates from the sibling kev_check by framing EPSS as a forward-looking likelihood versus confirmed exploitation.

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 phrase 'complements kev_check's confirmed exploitation' gives clear contextual guidance on when this tool is the right pick relative to a named sibling. There is no explicit when-not or prerequisite guidance, but the positioning is unambiguous enough for an agent to route 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?

No annotations are provided, so the description carries the full behavioral burden, and it largely succeeds: it discloses that the lookup is keyless (no auth), that it is purely threat-intel and 'never touches the target' (safety profile), and that it is read-only. It does not mention rate limits, caching, or behavior on lookup failure, so it stops short of full transparency.

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?

A single dense paragraph with the purpose, source, hit semantics, input handling and safety posture front-loaded in that order. The parenthetical malware-family list and the 'Read-only' tag are short and each sentence carries information the 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?

For a one-parameter, no-annotation, no-output-schema tool, the description covers everything an agent needs: what it queries, what a hit means, what fields come back (malware name, port, first-seen date), input coercion rules, and that the target is never contacted. With no output schema available, describing the return content is exactly the missing piece it supplies.

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

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

Schema coverage is 100% for the single 'target' parameter, so the baseline is 3, and the description earns above that by explaining non-obvious input handling: a host name is accepted and the first resolved IP is used. That is real semantics an agent could not infer from the schema's 'IP address or host name' description alone.

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 precise verb and resource ('Check an IP against abuse.ch's Feodo Tracker botnet C2 blocklist') and names the authoritative data source, which cleanly distinguishes it from siblings like ip_blocklist_check, dshield_ip_check and tor_exit_check. It also defines what a hit means (known C2 server for a named malware family), so an agent knows the semantic weight of a positive result.

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 clearly implied by the description – this is the C2-specific blocklist check – but it never states when to prefer it over adjacent tools such as ip_blocklist_check, ip_reputation, ip_reputation_aggregate or dshield_ip_check, nor when it is insufficient on its own. It does add one routing-relevant behavior ('For a host name the first resolved IP is used'), which helps an agent decide what to pass.

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 well: it discloses that the origin is the caller's IP (the user when run client-side), that no connection is made to the target, and that the return is structured endpoints plus an SVG link intended for the human. It omits caveats about geolocation accuracy and failure modes, but the key behavioral traits are surfaced.

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 and scope, then the output shape, then the crucial non-contact caveat. 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 single-parameter read-only lookup with no output schema, the description specifies what comes back (structured endpoints plus map link) and clarifies audience of the image and that the target is never contacted. Only missing pieces are behavioral edges like geolocation accuracy or error handling, which are minor here.

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?

One parameter with 100% schema description coverage, so the schema already documents 'host' as a hostname or IP with an example. The description adds no syntax or format guidance 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?

Clear specific verb (Show) and resource (network path from caller to target host on a world map), with the three outputs enumerated (origin, destination, great-circle distance). The 'network path' phrasing could momentarily suggest a traceroute, but the description immediately clarifies it is geolocation plus great-circle distance. It does not explicitly distinguish itself from the many geo/DNS siblings such as asn_geoip or passive_dns.

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 explicit when-to-use statement or named alternative. Context is implied by the described outputs: use it when you want a caller-to-host geographic visualization with distance, not a trace or reputation check. Acceptable but leaves the agent to infer selection versus asn_geoip or dns_lookup.

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 well: it discloses passive-only behavior, keyless access, read-only semantics, that it reads Shodan's own scan data rather than probing, and the CDN accuracy limitation. It omits data freshness/staleness and any rate-limit or caching behavior, which would matter for an agent deciding reliability.

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 purpose and data source, followed by method and the CDN caveat. Every clause carries operational information; nothing is redundant 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?

No output schema exists, and the description compensates by enumerating the returned fields, which is what an agent needs to judge fit. The remaining gap is behavioral detail on data freshness and failure modes, minor for a single-parameter passive lookup.

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

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

Schema coverage is 100% for the single target parameter, so baseline is 3. The description adds genuine meaning beyond the schema by explaining that for a domain the first resolved IP is used and that CDN-fronted domains yield edge data — behavior an agent cannot glean from the schema string alone.

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 ('Report a host's internet-facing exposure') plus the exact data source (Shodan's InternetDB) and enumerates the returned fields (open ports, CPEs, CVEs, hostnames, tags). This clearly separates it from siblings like ip_reputation, scan_site, and passive_dns, which cover different data or methods.

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 implied usage context — passive lookup that 'never touches the target' — and a caveat that behind a CDN results reflect the edge, not the origin. However, no alternative tool is named and there is no explicit when-to-use/when-not statement, so the agent must infer the routing itself.

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 provided, the description carries the full disclosure burden and does well: it declares 'Read-only', specifies the external API queried, and explicitly states this is not a probe of the target, which tells the agent no packets reach the domain's own infrastructure. It omits rate limits, auth requirements, and error behavior, which keeps it out of the top score.

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

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

The primary purpose is front-loaded in the first clause, followed by the data source and return fields. The middle sentence explaining preload's HTTPS guarantee is genuinely useful orientation but is the longest element and edges toward background exposition rather than invocation guidance.

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 correctly compensates by enumerating the return values (status preloaded/pending/unknown, bulk-imported flag, parent domain). For a one-parameter, unauthenticated lookup that is nearly sufficient; only edge cases such as invalid input or API failure handling are unaddressed.

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 only one trivially-named parameter, so the schema already does the documenting work. The description adds no format constraints, sub-domain handling rules, or examples beyond the schema's 'Domain, e.g. example.com'.

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 ('Check whether a domain is in the browsers' HSTS preload list') and goes further to state the data source (hstspreload.org's keyless status API) and the exact returned dimensions (status, bulk-imported, parent coverage). This is clearly distinguishable from siblings like tls_posture or security_txt, which check live headers rather than preload membership.

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 clarifies the nature of the operation ('A membership lookup, never a probe of the target') and contextualizes it against header-based checks ('a stronger guarantee than the Strict-Transport-Security header alone'), which implicitly steers the agent to header tools when a live probe is wanted. However, it never explicitly names an alternative tool or states when not to use this one, so it falls 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?

With no annotations, the description carries the full behavioral burden and does it well: it enumerates the external sources consulted (Astur, Shodan InternetDB, GreyNoise, Spamhaus/FireHOL, Feodo, Tor, DShield), discloses that deep is slower with more calls, and warns that the deep signals can only WORSEN the overall grade, never lift it. It stops short of stating auth needs, rate limits, or timeout behavior for the slow multi-call path, so it is not fully complete.

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 purpose and the routing rule are front-loaded, and the long enumeration of report contents is informative rather than filler for an aggregation tool. It is dense and the output enumeration is heavy, but each clause corresponds to a real returned signal, so little is wasted.

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

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

For a tool with no annotations and no output schema, the description enumerates the returned report components and explains the depth flag, so an agent knows what it will get back. It omits response format/structure and error or timeout handling for the heavier deep sweep, which leaves a small gap for a multi-call aggregation 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 baseline is 3, but the description adds real meaning beyond the schema by explaining the consequence of depth='deep' (adds RPKI, disclosure contacts, subdomain takeover, IP reputation verdict, TLS posture, CVE ranking; more calls, slower) and its effect on the grade. This goes beyond the terse enum-like 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 ('Run a full reconnaissance sweep of a domain or URL') and then enumerates the exact dimensions of the correlated report (web-security grade, SPF/DMARC, nameservers, MX, registrar, CT subdomains, IP exposure, reputation, roll-up grade). It explicitly distinguishes itself from the granular siblings at the end, so an agent can tell it apart from scan_site or spf_check 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 explicit routing guidance: 'Use this for broad investigate X requests; use the granular tools (scan_site, spf_check, …) for specific questions.' It also states the condition that selects the expensive path ('Pass depth="deep" to also run the heavier OSINT (more calls, slower)'), covering both when-to-use and the alternative 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?

With no annotations, the description carries the full burden and does well: it declares read-only, 'never contacts the target', keyless (no auth), and explains the return shape (matched lists with CIDR and reference, plus which lists were reachable). It omits rate limits, timeouts, or caching 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?

Front-loaded with the core purpose, then return behavior, differentiation, hostname handling, and safety in a compact set of sentences. It is dense but each sentence adds information; slightly more length than the leanest possible form.

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 or annotations, yet the description explains the data sources, what gets returned, partial failure (which lists were reachable), hostname handling, and safety. It does not specify no-match representation or exact response format, but is otherwise complete for a single-parameter lookup 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 only one parameter exists, so the baseline is 3. The description adds meaningful behavior beyond the schema by stating that for a host name the first resolved IP is used, which clarifies how the 'target' input is interpreted.

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), resource (an IP inside a netblock), and scope (curated keyless reputation lists: Spamhaus DROP/EDROP and FireHOL level1). It distinguishes itself from ip_reputation and blacklist_check, so an agent can tell it apart 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?

Explicitly names two sibling tools (ip_reputation for GreyNoise scanner telemetry, blacklist_check for mail DNSBLs) and describes this tool's distinct niche ('sits in a known-bad network' reputation). This gives clear alternative routing and a when-to-use condition.

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: declares it read-only, discloses the severe shared keyless quota (25/week server-wide), explains the degraded-mode behavior (says so at once with reset time instead of querying), and interprets result semantics. Exceptionally transparent.

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 primary purpose and result semantics, then the availability caveat. Dense but every sentence earns its place; slightly long but justified by the quota caveat.

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?

A single-parameter, no-output-schema tool, and the description covers purpose, result interpretation, quota failure mode, and host-name handling — everything an agent needs to call it and interpret outcomes 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 baseline is 3; however the description adds meaning the schema doesn't — that host names are accepted and the first resolved IP is used, which explains non-obvious behavior of the single 'target' parameter.

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 (an IP) and the exact data source (GreyNoise Community) plus what is returned (noise status, classification, scanner name, last-seen time). Unmistakably distinct from siblings like ip_reputation_aggregate or blacklist_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?

Explains what a 'not observed' result means (not an endorsement) and notes host names resolve to the first IP, giving clear interpretation guidance. It does not explicitly route to the ip_reputation_aggregate sibling, but the context is otherwise 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?

With no annotations, the description carries the full behavioral burden and does so richly: verdict semantics, the rule that a confirmed-bad listing forces 'malicious', the scanner/Tor exception for GreyNoise-identified benign research scanners, the 'unknown' condition, GreyNoise's keyless 25-lookup/week server-wide quota and its failure handling, hostname resolution behavior, and the read-only safety profile. This is far more than the schema or any annotation would provide.

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

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

Long but dense and front-loaded: the aggregate verdict comes first, then the decision rules, then the failure mode. Each sentence carries information, though the single-paragraph block is heavy and could be more scannable, keeping it just under a 5.

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 and no annotations, the description compensates fully — it describes the return content (verdict, which signals fired, which sources answered or failed), the degradation path when GreyNoise is unavailable, and the safety profile. Nothing an agent needs to invoke or interpret 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?

Schema coverage is 100% and there is only one parameter, so the baseline is 3. The description adds meaning beyond the schema by specifying the resolution policy for a host name ('the first resolved IP is used'), which the schema's example does not state.

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 ('Fold every keyless IP-reputation source into one verdict') and enumerates exactly which sibling checks are subsumed (ip_blocklist_check, ip_reputation, feodo_c2_check, tor_exit_check, dshield_ip_check). An agent can distinguish this aggregate from the individual checks 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?

Clearly conveys the context in which this tool is the right call — when a single consolidated verdict is wanted instead of the five underlying lookups, which it names. It stops short of an explicit directive ('use this rather than calling ip_blocklist_check directly') or any when-not-to-use exclusion, so it falls 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?

With no annotations present, the description carries the full burden and does well: it declares 'Keyless, read-only' (no auth required, non-mutating) and enumerates the returned fields (vendor/product, added date, remediation due date, ransomware campaign usage). It stops short of describing failure behavior for a CVE that is absent from the catalogue.

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 purpose, followed by return contents and the workflow hook. Every sentence earns its place with no 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?

No output schema exists, and the description compensates by enumerating the returned fields, so an agent knows what comes back. Safety profile, auth posture and input meaning are all covered for a simple single-parameter lookup.

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 one parameter and schema description coverage is 100%, so the schema already documents the CVE ID and its format. The description adds no extra syntax, casing or normalization guidance, 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?

Specific verb ('Check whether a CVE is in') plus a precisely named resource (CISA's Known Exploited Vulnerabilities catalogue), with the semantic meaning spelled out ('confirmed exploited in the wild, the strongest patch-this-now signal'). This cleanly separates it from siblings like cve_lookup, cve_triage and epss_score 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 clear context for when to reach for it: 'Interprets the CVE IDs host_exposure surfaces,' which ties it into an explicit upstream workflow. It does not, however, state exclusions or name alternatives such as cve_lookup or epss_score for non-KEV CVEs, so it falls short of a full when/when-not treatment.

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 it does disclose the read-only nature plus the return ordering and that IPs are resolved. It omits failure behavior (no MX, NXDOMAIN), caching/rate limits, and whether resolution failures are reported, so the safety profile is only partially 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?

A single front-loaded sentence stating the resource, the ordering, the enrichment, and the safety profile, with zero filler. Nothing could be removed without losing 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?

There is no output schema, so the description usefully explains the return shape (preference-ordered hosts with resolved IPs) and states read-only. For a simple one-parameter lookup this is nearly complete; only error/edge-case behavior is unaddressed.

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 'domain' parameter, so the schema already carries the semantics. The description adds no format or syntax detail beyond what the schema states, which is the expected baseline 3.

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

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

States a specific verb (List) and resource (MX records) and further specifies ordering by preference and IP resolution of each host. An agent can distinguish it from generic siblings like dns_lookup or spf_check 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?

Usage is only implied by the resource itself (mail-routing investigation); there is no explicit when-to-use or when-not statement, and the obvious alternative, dns_lookup, is never mentioned. Adequate but leaves routing between siblings 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?

With no annotations, the description carries the full burden and does well: it declares the read-only nature, states it reads the passive-DNS database and never touches the target, and notes the keyless data source. It still omits operational traits such as rate limits, pagination, or result caps, 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?

Two dense sentences, front-loaded with the core purpose and scope before the differentiator and safety note. Every clause carries information; nothing is redundant with the schema or title.

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, no-output-schema tool, the description covers source, directionality of results, per-record fields (first/last-seen, observation count), and read-only safety. It is nearly complete, missing only result-volume/pagination 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 coverage is 100% with a single documented 'query' parameter, so the baseline is 3. The description adds real semantic value by explaining that a domain yields historical answers while an IP yields the names that pointed at it, clarifying how the one input changes the result shape.

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: historical DNS resolutions for a domain or IP, with the exact data source (Mnemonic keyless Passive DNS) named. It clearly distinguishes itself from live-lookup siblings like dns_lookup and reverse_dns by describing bidirectional historical mapping (answers for a name, names for an IP).

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?

'Surfaces old/rotated infrastructure a live lookup can't' gives clear usage context and implicitly routes the agent away from live-DNS siblings. It stops short of explicitly naming the alternative tools or stating exclusions, so it is clear context but not full when/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?

No annotations are provided, so the description carries the full burden. It does declare 'Read-only' and lists the fields returned (handle, name, statuses, lifecycle events, raw record), which is useful. However it omits rate-limit behavior, auth requirements, and what happens when a domain has no RDAP server or is not found.

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

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

One dense sentence, front-loaded with the action and resource, with the parenthetical gloss and the return-field list earning their place. No filler or redundancy.

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

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

For a single-parameter, read-only lookup with no output schema, the description covers purpose, mechanism and returned content adequately. It stops short of failure modes and TLD/RDAP-server coverage, which an agent would benefit from knowing.

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 including a concrete example (example.com, 192.0.2.1). The description's 'domain or IP' phrasing aligns with but adds nothing beyond the schema, so the 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 (look up) and resource (registration data) and clarifies the mechanism (RDAP, JSON successor to WHOIS), which cleanly separates it from siblings like dns_lookup, passive_dns or tls_certificate. It also enumerates what is returned (handle, name, statuses, lifecycle events, raw record), so an agent can identify 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?

Usage is implied rather than stated: it targets registration/ownership data, distinct from DNS resolution or reputation checks, but there is no explicit when-to-use guidance, no mention of alternatives such as passive_dns for historical ownership, and no note on lookup failures for unsupported TLDs.

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 disclose the key traits: 'Read-only' (safety) and 'passive' (no active probing), plus the external source (crt.sh). It omits rate-limit/pagination behavior and result size expectations, so it falls 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?

One front-loaded sentence with the verb first; the em-dash aside efficiently explains the mechanism. Slightly dense, but every clause earns its place 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?

For a one-parameter lookup with no output schema and no annotations, the description covers purpose, source, passivity, and safety. The only gap is that the return format (a list of domains) is left implicit, which is acceptable given the phrasing.

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' param is self-evident. The description restates 'the given domain' but adds no format rules or edge-case guidance beyond the schema's example, 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?

Specific verb ('Find') plus a precise resource ('other registrable domains that share a TLS certificate'). It names the mechanism (common SAN) and data source (crt.sh), which clearly distinguishes it from siblings like cert_transparency and ct_org_search that operate on the target's own certs.

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 phrase 'passive link to sibling properties' implies the investigative use case, but the description never states when to prefer this over cert_transparency/ct_org_search or any exclusion conditions. Usage is inferable but not explicit.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does usefully declare 'Read-only', covering the safety profile, and the plural 'host name(s)' hints that zero or multiple PTRs may come back. However, it omits common reverse-DNS realities such as frequent empty results and any timeout/rate-limit 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?

Two short sentences with zero waste; the core action is front-loaded and the safety note trails efficiently.

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 tool with no output schema, the description covers the action, the input space, and the return shape (PTR host names). The main gap is absent routing guidance against sibling lookup tools, but nothing essential for calling 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 100%, so the single 'ip' parameter is already documented as IPv4 or IPv6 with an example. The description adds nothing beyond the schema, 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 (reverse-resolve) and resource (IP address to PTR host names), which is unambiguous and implicitly separable from forward-lookup siblings like dns_lookup or passive_dns. It does not explicitly name or differentiate itself from any sibling, 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?

The description says what the tool does but offers no when-to-use context or alternatives. With ~50 siblings including dns_lookup and passive_dns, an agent gets no guidance on when reverse DNS is the right choice versus those.

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 are provided, so the description carries the full burden and does so: read-only, passive, no crawling or brute-forcing, and it carefully bounds its own behavior ('for the one sitemap fetched' — not all sitemaps). It discloses that only two public files are touched, which is meaningful operational 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 core action and the recon value are front-loaded, and every clause carries information. It is a dense single paragraph with several parentheticals, which is slightly heavier than necessary but not 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 enumerates the return payload precisely: disallowed paths, crawl-delay, sitemap URLs, plus index status, <loc> count, and sample entries. Combined with the explicit negative scope, an agent has everything needed to call 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?

With one parameter at 100% schema description coverage, the schema already documents 'domain' including the 'Domain or URL, e.g. example.com' example. The description adds no format, normalization, or scope detail beyond that, so baseline 3 is appropriate.

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

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

States a specific verb and resource pair ('passively read a site's robots.txt and the sitemap it points to') and enumerates exactly what is returned. It also explicitly distinguishes itself from scan_site and active content discovery, so an agent can pick it apart from siblings 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 scopes usage to passive reading of two owner-published files and names the alternative ('that active content discovery is scan_site/Astur's job'). It also states what the tool does NOT do (crawl, guess, brute-force), giving both when-to-use and when-not-to-use guidance.

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

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

With no annotations, the description carries the full burden and does disclose the data source (RIPEstat), that the operation is read-only, and the edge-case behavior for host names (first resolved IP is used). It does not mention rate limits or whether upstream failures degrade to 'unknown', which are the remaining gaps.

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 with no filler: purpose first, then the meaning of each result value, then the host-name caveat and read-only note. Everything is front-loaded and each clause adds 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 single-parameter tool with no output schema and no annotations, the description covers purpose, result semantics, input edge cases, and safety profile, which is nearly everything an agent needs. It could still note what accompanies the verdict (covering ROA/prefix/ASN details) or behavior for unannounced prefixes, but the essential contract 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 coverage is 100% for the single target parameter, so the baseline is 3. The description adds real meaning beyond the schema by specifying that a host name is resolved and only the first IP is validated, which the schema's 'host name' wording does 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: validate the BGP route-origin of an IP/prefix against RPKI via RIPEstat. It also defines the three outcome values (valid/invalid/unknown), so the agent knows exactly what the tool computes. No sibling tool covers RPKI, so it is easily distinguished.

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 semantics of the return values (e.g. 'invalid' signals a possible hijack or misconfiguration), which helps the agent interpret when the result matters. However, it never states when to reach for this tool versus related siblings like asn_prefixes, geo_route, or ip_reputation, and offers no exclusions or prerequisites.

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

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

With no annotations, the description carries the full behavioral burden and does disclose the key trait: the scan is passive and non-intrusive with no active probing, which is the main safety concern an agent must know. It omits auth requirements, rate limits, and side-effect details, so it stops short of full coverage.

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 verb and resource, followed by output shape and the safety qualifier. No filler and every clause 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?

For a one-parameter, no-output-schema tool, the description supplies the return values (grade, score, OWASP-mapped findings) and the passive nature, which is nearly everything an agent needs. Only explicit routing against sibling tools 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 the single 'url' parameter is already documented as an absolute http(s) URL with an example. The description adds no syntax or format detail beyond the schema, 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 verb and resource ('passive web-security scan of a URL') and even names the engine (Astur). It also summarizes the output (A–F grade, 0–100 score, OWASP WSTG/ASVS findings), making it clearly distinguishable from the many single-signal siblings like tls_posture or host_exposure.

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 'passive web-security scan', and the 'non-intrusive — no active probing' note hints at when it is safe. However, it gives no explicit when-to-use guidance versus the sibling recon tools and no exclusions, leaving the agent to infer that this is the broad-sweep tool rather than a per-signal check.

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 provided, the description carries the full behavioral burden and does so well: it states 'Read-only, no probing,' identifies the file as public and owner-published, explains fallback from /.well-known/security.txt to /security.txt, and lists the returned fields including conformance warnings. This is far beyond what the schema or annotations supply.

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 then densely lists exactly what is returned and how the fetch behaves. Every clause earns its place, and the final sentence 'Read-only, no probing.' efficiently reinforces the safety profile.

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

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

Despite having no output schema and no annotations, the description fully covers the retrieval behavior, fallback logic, return contents, and relationship to the sibling abuse_contact tool. An agent has everything needed to select and invoke 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 already documented as 'Domain or URL, e.g. example.com.' The description adds context about what file is fetched from that domain but does not add parameter-specific semantics such as accepted URL schemes or normalization rules, 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?

The description uses a specific verb ('Fetch') and resource ('site's vulnerability-disclosure file (RFC 9116)') and names the file paths, so an agent can immediately tell it apart from siblings like abuse_contact and disclosure_contacts. It also clarifies the fallback location and the exact contents returned.

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

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

The description explicitly distinguishes this tool from abuse_contact by calling it a complement to 'the RIR's registered mailbox' and framing it as 'the owner's own disclosure channel.' It gives clear context for when to reach for it, but does not include explicit when-not conditions or a full routing 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?

No annotations are provided, so the description carries the full burden. It does disclose the read-only nature and the shape of what is surfaced (lookup count, all qualifier, warnings), which is real behavioural value, but it says nothing about error handling, domains with no SPF record at all, or any rate/query limits. Adequate but with clear gaps for an unannotated 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?

One dense sentence, front-loaded with the verb and resource, with the enumerated outputs and the read-only tag appended and no wasted clauses. Nothing could be removed without losing 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 single-parameter, no-output-schema, no-annotation tool, the description covers what is fetched, how it is interpreted (RFC 7208 limit, qualifier, warnings), and that it is read-only. The main omission is routing guidance among the many sibling DNS/email tools, which is a usage-guideline gap more than a completeness one.

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 (domain) and the schema documents it at 100% coverage with an example ('example.com'). The description adds no syntax, format, or edge-case detail beyond the schema, so the high-coverage 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 verb pair (fetch and analyse) and resource (a domain's SPF record), then enumerates exactly what is produced: parsed DNS-lookup count against the RFC 7208 limit of 10, the 'all' qualifier, and policy warnings. That specificity distinguishes it in practice from spf_expand or dmarc_check, but no sibling is named, so the differentiation is implicit rather than explicit.

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 never says when to reach for this tool versus spf_expand, dmarc_check, email_posture, or spoofability, which all live in the same email/DNS neighbourhood. Usage can only be inferred from the resource name. The RFC 7208 reference is domain colour, not 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the read-only, DNS-only nature of the operation, the recursive traversal behavior, the RFC 7208 limit being evaluated, and what it returns (flattened include tree, total lookup count, warnings on excess, loops, void lookups). It does not mention performance or query-volume implications of the recursive lookup, but otherwise provides strong transparency for a read-only 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?

Two dense sentences plus a short read-only/DNS-only tag, front-loaded with the core action and scope. Every clause adds information (recursive traversal, limit, failure mode, return values, safety), with no wasted wording.

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

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

Given the tool's complexity (recursive DNS traversal with loop/void detection) and the absence of both annotations and an output schema, the description supplies the missing return-value shape and safety profile (read-only, DNS-only) and names the key domain semantics. An agent has everything needed to select and invoke it correctly.

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

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

Schema description coverage is 100%: the lone 'domain' parameter is already documented in the schema as 'Domain to query, e.g. example.com'. The description adds no additional parameter syntax, format constraints, or edge-case semantics beyond what the schema 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?

The description names a specific verb and resource (recursively expand a domain's SPF record) and a precise scope (follow every include: and redirect=, count DNS-lookup mechanisms across the WHOLE tree against the RFC 7208 limit of 10). It explicitly distinguishes itself from the sibling tool spf_check by naming the failure mode spf_check misses, so an agent can tell the two apart 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?

It names the alternative (spf_check) and the exact condition that selects this tool instead: nested includes quietly push the total over 10 and the record hits permerror. That is an explicit when-to-use vs. alternative statement, leaving little 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?

With no annotations provided, the description carries the full behavioral burden and does disclose the key traits: it is a read-only DNS operation, it returns a categorical verdict plus an A–F grade and concrete reasons, and it explains the semantics of each verdict value. It omits rate limits, caching, or failure behavior, but covers the safety and output profile well.

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 definitions are front-loaded and each sentence contributes — verdict semantics, the DMARC controlling factor, and the read-only note. It is dense but not padded, though the parenthetical explanation of p=none could be trimmed.

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

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

For a single-parameter read-only tool with no output schema and no annotations, the description covers the return shape (verdict, grade, reasons) and the operation's nature, which is enough for correct invocation. Minor gaps like error behavior are acceptable at this complexity.

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

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

Schema description coverage is 100% for the single 'domain' parameter, so the schema already documents the input. The description adds no syntax or format detail beyond what the schema provides, 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?

The description states a specific verb (judge) and resource (how easily a domain's mail can be forged), and defines the tool as a correlation of SPF and DMARC into a single verdict. This implicitly distinguishes it from single-record siblings like dmarc_check and spf_check, which an agent can tell apart 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?

It explains the meaning of each verdict and notes that 'the controlling factor is DMARC', which implies usage, but it never explicitly says when to prefer this synthesized verdict over calling dmarc_check or spf_check directly. Usage is inferable 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?

With no annotations, the description carries the full burden and discloses important behavior: it is DNS-first, performs an HTTP GET only for CNAME matches, and defines what 'vulnerable', 'dangling', and 'potential' mean. It does not cover authentication, rate limits, or side effects, but for a read-only security check it provides strong operational context.

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

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

The description is a single dense sentence but front-loads the core purpose and follows with necessary technical distinctions. It is appropriately sized for the complexity of the check, though splitting the status definitions could improve readability.

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

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

Given the absence of output schema and annotations, the description supplies the relevant methodology and return statuses. It is largely complete for tool selection and invocation, though an agent might still wonder about rate limits or input restrictions.

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

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

The schema has 100% description coverage for the single 'domain' parameter, and the description reinforces the domain scope implicitly. It adds no format or syntax details beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: checking a domain's subdomains for dangling-CNAME takeover risk. It explains the mechanism (Certificate Transparency enumeration, CNAME delegation) and defines distinct outcome statuses, making it clearly distinguishable from siblings like cert_transparency 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?

The description gives a clear context for use: assessing subdomain takeover risk via dangling CNAMEs. It does not explicitly name alternative tools or when not to use it, but the scenario is specific enough that an agent can infer when this tool is appropriate.

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

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

With no annotations, the description carries the full burden and does well: it discloses that a real TLS handshake occurs, that no HTTP request is made, and that internal targets are blocked. Permission/rate-limit behavior and timeout/error handling are unstated, keeping 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, and the enumeration of returned fields, the sibling comparison, and the safety note all earn their place. The middle clause is a dense list, but nothing is redundant or wasted.

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

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

There is no output schema, and the description compensates by itemizing precisely what the inspection returns, including the chain trust verdict and negotiated protocol/cipher. Combined with the handshake behavior and target guard, 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% and both parameters (host, port with default 443) are documented in the schema, so the description adds no parameter-level detail beyond examples already present. Baseline 3 applies 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 and resource: inspect the leaf certificate served during a live TLS handshake, then enumerates exactly what is returned (subject, issuer, SANs, validity, algorithms, chain, trust verdict). It explicitly distinguishes itself from the sibling cert_transparency by contrasting 'presented right now' with 'historical CT logs'.

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 alternative (cert_transparency) and the condition that selects between them (live handshake vs historical CT logs), and notes the internal-target guard. It does not state when not to use this tool or mention related siblings like tls_posture or cert_revocation, so it falls short of a full 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?

With no annotations, the description carries the full burden and does well: it discloses 'a benign TLS handshake plus a keyless HSTS lookup — no probing' and 'Read-only', covering the network-touch and safety profile. It also explains what raises and lowers the grade. It omits rate limits or auth requirements, 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 sentences, front-loaded with the core purpose before the factor details and behavioral note. Dense but essentially waste-free; the parenthetical lists of factors are informative rather than filler.

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

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

There is no output schema, but the description explains the return values (letter grade, 0–100 score, contributing factors) so an agent knows what to expect. Combined with the read-only/no-probing disclosure, it is nearly complete for a two-parameter read tool; only auth/rate-limit context 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 description coverage is 100% and both parameters (host, port with default 443) are fully documented in the schema. The description adds no parameter-level meaning beyond what the schema provides, so the 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 (grade), resource (host's transport security), and output form (A–F letter grade) in the first clause. It distinguishes itself from siblings by naming exactly which tools it aggregates: tls_certificate, cert_revocation, and hsts_preload_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?

The phrase 'in one call' plus the explicit correlation of three sibling tools strongly implies this is the aggregator to use instead of calling tls_certificate/cert_revocation/hsts_preload_check separately. It lacks an explicit 'use this when... instead of...' exclusion, but the routing intent 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?

No annotations are provided, so the description carries the full burden, and it does so well: 'keyless' (no auth required), 'Read-only' (safety profile), the data source, and the hostname handling rule (first resolved IP). It omits rate limits and return format, but the operational profile is substantially disclosed.

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 clauses, front-loaded with the action and source, then rationale, then edge-case behavior. Every sentence earns its place 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?

For a simple one-parameter boolean check with no output schema, the description covers source, safety profile, and hostname handling adequately. A brief note on the return value shape (e.g. exit/non-exit and list freshness) would make it fully complete, but it is close.

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 'target' parameter is already documented. The description nonetheless adds real meaning beyond the schema: 'For a host name the first resolved IP is used', clarifying resolution behavior the agent couldn't infer from the field alone.

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: 'Check whether an IP is a current Tor exit node', with the authoritative source named (Tor Project bulk exit list). An agent can immediately distinguish this from generic IP-reputation siblings like ip_reputation or ip_blocklist_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?

The description implies a usage scenario ('an IP seen in logs may not be the true origin — a useful context signal'), which tells the agent why to reach for it. However, it names no alternatives or exclusions relative to the many IP-checking siblings, leaving the when-to-use decision partly 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?

With no annotations, the description carries the full burden and does disclose key traits: read-only, keyless (no auth), and critically 'Reads Tranco's database, never the target' — an important disclosure that it does not touch the scanned domain. It omits rate limits, caching, or data-freshness caveats, keeping it 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-loads the purpose in the first clause, then layers interpretation value. Every sentence earns its place — the phishing-tell and scrutiny framing are directly actionable, and there is 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?

No output schema exists, so the description must explain return values, and it does (rank, band, daily-list count). For a one-parameter read tool, 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 description coverage is 100% with a single trivially-named 'domain' parameter, so the schema already fully documents the input. The description adds no input syntax or format guidance beyond what the schema provides; 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 ('Report a domain's popularity on the Tranco research list') and enumerates the return units (rank, band, daily-list appearance count). This is distinguishable from every sibling (typosquat_scan, blacklist_check, related_domains) 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 clear framing for when the result matters ('a cheap context signal', 'a top-1k domain and an unranked one warrant very different scrutiny', 'an unexpectedly unranked lookalike is a phishing tell'). However, it never names a specific sibling alternative to use instead or an explicit exclusion, so it falls short of the 5 bar.

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 well: it discloses that the scan is DNS-only, read-only, 'never touches the target,' and that candidate generation is bounded for speed. It does not mention rate limits, resolution timeouts, or how results are ordered, but the safety and performance profile is unusually well covered for an unannotated 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?

One front-loaded sentence with the mechanism and output, followed by two tight clauses covering safety and performance. Every clause earns its place; nothing is redundant with 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?

There is no output schema, so the description must hint at returns — it does ('report which ones actually resolve in DNS'). Safety, scope, and performance are all covered, so an agent has what it needs to call it correctly; only result-shape detail (ordering, fields per lookalike) is absent, which is 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?

Single parameter with 100% schema coverage, so the schema already documents 'domain'. The description implies the parameter is the base domain from which variants are generated but adds no syntax, normalization, or format guidance beyond the schema's own example. 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 compound verb (generate variants + report which resolve) on a named resource (lookalike domain variants), and enumerates the exact variant classes (omission, transposition, homoglyph, adjacent-key, hyphenation, TLD-swap). This clearly separates it from neighbors like related_domains or dns_lookup, so an agent can route to 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?

The phrase 'the registered lookalikes worth checking for phishing or brand abuse' implies the investigative context, so usage is inferable. However, it never states when NOT to use it or names an alternative sibling (e.g., related_domains) for the adjacent question, leaving the agent to infer the boundary.

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 are supplied, so the description carries the full burden, and it does substantial work: 'keyless' (no auth required), 'Read-only', and 'Reads urlscan's data, never the target' clearly characterize the operation. It also enumerates the returned data points. It omits pagination, result caps, and any rate-limit behavior for an external API.

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 data source, then layers the scope restriction and return contents in a single dense sentence. Every clause is informative, though the long parenthetical makes it heavier than it needs to be.

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 well by describing the fields returned (final URL, resolved IP, hosting country/server/ASN, links to result and screenshot, related-domain roll-up) and by flagging keyless read-only semantics. Missing only edge-case behavior such as no-results handling or limits.

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 parameter, so the schema already documents the expected domain format. The description's mention of a raw urlscan field query (`ip:1.2.3.4`) largely restates what the schema description already states, adding little beyond the baseline.

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

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

States a specific verb (Search) against a specific resource (urlscan.io's public scan database) and precisely scopes it: scans of the site itself, explicitly excluding 'other sites that merely load something from it'. The phrase 'Reads urlscan's data, never the target' cleanly separates it from live-scan siblings like scan_site.

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 context for when to reach for it (keyless, historical public scan data, domain or IP) and hints at the alternative by noting it never touches the target. It stops short of naming a specific sibling such as scan_site or passive_dns as the substitute for live or DNS-history lookups.

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, so the description must carry the load; it does disclose read-only behavior, the keyless CDX backend, and that each snapshot comes with a link. It omits failure behavior (what happens when a domain is unarchived), rate limits, or output shape beyond the link.

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?

One dense sentence followed by a two-word safety tag; the purpose and sibling disambiguation are front-loaded 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?

For a single-param lookup with no output schema, the description covers purpose, sibling disambiguation, backend, and read-only safety. Slightly short on what the response contains when no captures exist, but adequate.

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

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

Schema coverage is 100% with a single required 'domain' string, and the description's only parameter-relevant hint is 'a domain,' adding nothing beyond the schema. Baseline 3 for high coverage.

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

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

States a specific verb (report) and resource (first and most recent captures of a domain in the Wayback Machine), and explicitly distinguishes itself from sibling wayback_urls by naming what that tool does (lists archived URLs).

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?

Frames the tool as a site-age / history signal and names the alternative (wayback_urls) for listing URLs, giving a clear selection rule. No explicit when-not conditions, but the intended use 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?

No annotations provided, so description carries full burden. It adds substantial value: keyless CDX API, passive (reads archive, never the target), read-only, and covers subdomains. It does not cover rate limits, output format, or pagination, but the safety and fetch semantics are well disclosed.

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?

Compact, front-loaded: verb, resource, source in the first clause, then value-add modifiers. 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?

Given one param, 100% schema coverage, no output schema, and no annotations, the description is nearly complete: it covers source, passivity, read-only, scope, and the type of data returned. Missing return-format/pagination hints, but no output schema so not strictly required.

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

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

Schema coverage is 100% with the domain parameter documented including subdomain inclusion. The description adds minor confirmation of subdomain scope but largely repeats the schema. Baseline 3 is met; slight top-up for reinforcing scope.

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 (List), resource (historical URLs), and data source (Wayback Machine CDX API). Explicitly covers what kinds of results (old endpoints, forgotten paths, files no longer live) and scope (domain + subdomains), distinguishing it from wayback_snapshot which would fetch a single snapshot.

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?

Describes what the tool does and hints at the OSINT use case (passive recon), but does not explicitly say when to use this vs wayback_snapshot or passive_dns, nor any preconditions. Usage is implied by 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?

With no annotations, the description carries the full behavioral burden and does so well: it declares the tool is read-only, external, operates over DNS/TCP, and never touches the target's application. It also enumerates the exact per-name-server verdicts, including the safe defaults and the edge case (NS resolving to an internal address), which is unusually complete.

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?

A single dense paragraph with the purpose front-loaded and supporting detail (RFC reference, verdict vocabulary, safety profile) ordered by usefulness. It is heavier than strictly minimal and leans on em-dashes, but nearly every clause contributes 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?

There is no output schema, so the description must explain the return values — and it enumerates every verdict with its meaning plus the attached record sample. Combined with the safety disclosure, nothing needed to interpret results is missing for a one-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?

Only one parameter, fully documented in the schema at 100% coverage ('Domain, e.g. example.com'). The description adds no syntax, format, or constraint detail beyond the schema, 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 verb and resource — testing whether a domain's authoritative name servers allow an AXFR zone transfer — and immediately frames it as a misconfiguration check. An agent can distinguish this from dns_lookup or dns_propagation among the siblings 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?

The description situates the tool within DNS security auditing ('classic misconfiguration that leaks the entire zone') and defines what each outcome means, which tells the agent when the result is actionable. It does not explicitly name an alternative or state when NOT to use it, so it stops short of the top score.

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