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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds the genuinely useful ABUSEIPDB_API_KEY prerequisite, but says nothing about rate limits, quota exhaustion, or what happens for private/invalid IPs — gaps that matter for an open-world API call.

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 no waste; the resource and the domain restriction are front-loaded, followed by the key prerequisite.

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 small read-only lookup with no output schema, the description covers the resource, the input constraint and the auth requirement. The one real hole is the undocumented investigation_id parameter, which leaves an agent guessing on a two-parameter tool.

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

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

Schema description coverage is 0%, so the description carries the full burden. It clarifies ip_address (public IPs only, not domains) but leaves investigation_id completely unexplained — an agent has no way to know what that parameter does or when to supply it.

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-implied resource: abuse reports plus a confidence score for a public IP, with an explicit exclusion ('not domains') that separates it from resolve_domain and subdomains. It does not distinguish itself from the closest reputation siblings like virustotal_check or threat_lists_check, 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?

Usage is implied by the 'public IP address (not domains)' constraint, which tells the agent when not to use it, and the API-key prerequisite is stated. There is no explicit guidance on when to prefer this over virustotal_check or threat_lists_check for the same IP, which is the main ambiguity.

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

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

Beyond the annotations, the description adds important behavioral context: it never reveals key values, it reports where missing keys can be obtained, and it clarifies that many security lookups remain usable without keys. Those details directly affect how an agent should interpret and act on the result.

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

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

The definition is two sentences and front-loads the core behavior: configured keys are shown, values are never exposed, and missing-key sources are provided. The second sentence is a compact list that earns its place by clarifying which lookups remain viable without keys.

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 zero-parameter, read-only diagnostic tool with rich annotations and no output schema, the description covers the essential behavior: what is shown, what is deliberately hidden, and how to address missing keys. 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?

The tool takes no parameters, so there is no parameter semantics burden. The baseline for a zero-parameter tool is 4, and the description appropriately does not invent parameter details.

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 and resource: it shows which data-source API keys are configured, without exposing their values, and indicates where to obtain missing ones. This clearly distinguishes the tool from the sibling lookup tools, which query security data sources rather than report configuration status.

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 clear context for use by explaining that most lookups work without keys and listing which sources fall into that category, including the NVD slowdown caveat and the Shodan InternetDB alternative. It does not explicitly state a 'use this before calling X' workflow, but the practical guidance is strong enough for an agent to know when key configuration matters.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so safety is covered. The description then adds genuinely new behavioral context: the comparison is deterministic ("with no model involved") and non-mutating of the report — it only lists problems for the agent to fix. It stops short of specifying the exact return shape, but that is a minor gap given the annotations.

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

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

The trigger ("Run before giving the final report") is front-loaded, as is the core action and the remediation instruction. The long middle enumeration of failure modes is dense but each item earns its place by teaching the agent what to double-check; only minor trimming is possible.

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, no-output-schema, read-only tool, the description covers the essential question of when to call it and what it returns conceptually (a list of unsupported claims). Nothing critical is missing, though a note on whether the report is passed verbatim or re-read from the investigation would round it out.

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

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

Schema description coverage is 0%, so the description carries the burden here. It only implicitly maps parameters: "your draft" implies report_markdown and "this investigation's tool results" implies investigation_id, with no guidance on markdown format, size limits, or how the investigation_id is obtained. Baseline 3 is appropriate — partial compensation, but not full.

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 action (compare draft report against this investigation's tool results and key facts) and enumerates the exact classes of unsupported claims it flags. That level of specificity clearly separates it from every sibling (cve_search, nvd_lookup, get_key_facts, etc.), none of which validate a report.

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

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

"Run before giving the final report" gives an unambiguous trigger point, and "Fix or remove each one" tells the agent what to do with the result. There are no explicit exclusions or named alternatives, but the placement in the workflow is clear enough that an agent would not confuse it with the lookup 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?

Annotations already declare readOnly, idempotent, open-world, non-destructive, so the safety profile needs no restating. The description adds real interpretive value with the caveat that a product match means the product has been exploited historically, not that the queried version is affected. It stops short of describing what a miss/empty result means or how results are shaped.

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 action front-loaded, followed by the interpretive caveat, then the routing advice. No filler and no repetition of the 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?

Purpose and usage are complete, but with no output schema the description never indicates what comes back (KEV entry fields? booleans per input? matches only?), and investigation_id is left unexplained for a tool that otherwise demands careful interpretation. Adequate for routing, thin for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it only partially does: it names CVE IDs and product names as the accepted inputs but gives no format guidance (e.g. CVE-YYYY-NNNN) or array/optionality behavior. The third parameter, investigation_id, is never mentioned anywhere, leaving it entirely opaque.

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

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

States a specific verb ("Check") and resource (CISA's Known Exploited Vulnerabilities catalog) plus accepted inputs (CVE IDs and/or product names). It also differentiates itself from siblings by noting version checks and CVE lookups already return KEV status for their CVEs.

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

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

Gives explicit routing: use version checks / CVE lookups first because they already surface KEV status, then use this "once per product for its KEV history, or for CVE IDs from elsewhere." It also states a when-not-to-over-read rule for product matches, so the agent knows what conclusions the result does and does not support.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description does add genuinely non-structured context: that results are recency-ordered and that the tool is not version-aware. It says nothing about result caps, pagination, or NVD key/rate-limit behavior, so the addition is real but modest against an already-annotated 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?

Three tight sentences: what it does, the version caveat and alternative, then the query-construction rule. Front-loaded and zero 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 two-parameter read-only search with no output schema, the description covers purpose, alternative routing, and query shape, and briefly indicates the return set ('most recent matching CVEs'). The one gap is the undocumented investigation_id parameter, which an agent would have to guess at.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It does add meaning for search_term ('real product or vendor names', 'never fragments of a name', examples), but investigation_id is never mentioned anywhere in the description or schema, leaving one of two parameters fully opaque.

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

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

States a specific verb and resource ('Keyword search of NVD') plus the return scope ('most recent matching CVEs') with concrete examples ('grafana', 'log4j'). It also explicitly separates itself from version_specific_vulnerability_check by declaring it is 'not version-aware', so an agent can distinguish it from the sibling without opening either schema.

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

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

Gives explicit routing ('prefer version_specific_vulnerability_check when a version is known') and even a call-budget rule: 'at most twice per product (product, then vendor)'. It closes with a negative constraint ('never fragments of a name'), 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?

Annotations already cover read-only, idempotent, non-destructive behavior, so the description's additional details are valuable: it names OSV.dev as the backend, says no API key is needed, and notes that release is auto-detected when possible. It does not describe rate limits or the exact result shape.

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 what the tool does and is dense with useful examples and usage conditions. Every sentence adds selection or invocation value, 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 read-only external security check, the description provides enough context to select and invoke it correctly, including the OSV.dev dependency and input chaining. Because there is no output schema, it could be stronger by briefly describing what the check returns, such as patched/not-patched status or affected CVE details.

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 0% schema description coverage, the description does substantial work: it explains package and package_version with a concrete example, clarifies that cve_ids come from a version check's affected_cve_ids, and says release is auto-detected. It leaves investigation_id undocumented and only implicitly covers distro via the Ubuntu/Debian 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?

The description states a specific verb and resource: checking Ubuntu/Debian package versions against distro security data via OSV.dev. It also distinguishes the tool by explaining that it counts distro-backported fixes without upstream version changes, which differentiates it from generic CVE lookup tools.

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

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

It gives clear usage contexts: when Shodan lists distro_packages or when the user provides an installed package version. It also explains how to chain from a version check by passing affected_cve_ids as cve_ids, though it does not explicitly state when not to use the 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?

Annotations already declare read-only/idempotent, but the description adds real value beyond them: results are computed without a model so they are stable across runs, and values contain third-party text (an implicit prompt-injection caution). It also explains the KEV 'confirmed' vs 'related' split logic, which the agent could not otherwise know. It doesn't cover error behavior for an unknown or incomplete investigation.

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 key differentiator (deterministic, model-free) before the enumeration of contents. Dense but every clause carries information; the nested quoted terms make it slightly harder to scan, and the field list could be tightened.

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

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

With no output schema, the description does the work of telling the agent what the return payload contains and how to interpret the KEV categories. What's missing is lifecycle context — prerequisites tying it to investigate_target and behavior when the investigation is absent or partial.

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 required parameter, investigation_id, and schema description coverage is 0%, so the description must compensate — but it never explains what an investigation_id is, where it comes from, or what happens with a stale/unknown id. Baseline is lowered from 4 (zero-param case) only slightly because the single parameter is self-evidently an identifier.

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 resource and scope: facts computed deterministically from this investigation's tool results, enumerating what is included (ports, network, reputation, version check, upgrade target, KEV split). This distinguishes it from live-lookup siblings like shodan_search or cisa_kev_check, which it aggregates. The only weakness is that the verb is a generic 'get' and the description doesn't state upfront that it is a post-investigation aggregation step.

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?

'Base the report's claims on these' implies the tool is for consolidating results before writing a report, but it never says when to call it instead of check_report or re-running individual checks. No prerequisite (e.g., that investigate_target must have run first) or exclusion is stated. 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?

Annotations already declare readOnly/idempotent/openWorld, and the description goes well beyond them: it names the upstream services actually queried per target type, discloses the call budget per depth level (8/15/25/40), and states the refusal rule for private/reserved/metadata IPs. It also previews the return payload (investigation_id, baseline results, next_steps).

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 imperative and the classification step, then the returns, then the depth semantics — a sensible priority order. The service enumeration is dense and the run-on sentence in the first paragraph could be tightened, but no sentence is filler.

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

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

For an orchestration entry point with only two parameters, no output schema, and 15 siblings, the description supplies everything needed: accepted inputs, downstream services, refusal rules, return handles, and the cost model that governs downstream call planning. No meaningful gap remains.

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

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

Schema coverage is 0%, so the description carries the full burden and does: the 'target' parameter is defined by enumerated accepted formats (public IP, domain or URL, CVE ID, 'software version' such as 'nginx 1.20.1'), and 'depth' is mapped from each enum value to a concrete tool-call budget and detail level. This is meaning the schema alone 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 ('Classifies the target ... and runs the baseline lookups') and enumerates exactly which target types it accepts. The opening 'Start here' plus the sibling list makes clear this is the entry point rather than one of the per-service checks like abuseipdb_check or virustotal_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?

Explicitly instructs when to use it ('Start here') and establishes the dependency for all siblings ('Returns an investigation_id to pass to every other tool'). It also names the condition under which the tool refuses work (private, reserved and cloud-metadata IPs), so an agent knows the boundary case.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered structurally. The description adds genuinely new context: the upstream data source is the RIR via RDAP and no API key is required, which tells the agent the call is free of credential prerequisites. It does not mention behaviour for private/invalid IPs or rate limits, 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?

Two dense sentences with the payload contents front-loaded and no filler; the source and key requirement are packed into trailing clauses. Nothing needs trimming.

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

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

With no output schema, the description usefully enumerates the returned fields (organisation, range, country, abuse contact), which covers the return-value burden. But it leaves the second parameter unexplained and says nothing about response shape for private IPs or lookup failures, so it is only minimally sufficient.

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

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

Schema description coverage is 0% for both parameters. The description does constrain ip_address indirectly by saying "public IP" and framing it as an IP found elsewhere. However, investigation_id is completely undocumented in both schema and description, and no format examples (IPv4 vs IPv6) are given, so the description only partially compensates for the coverage gap.

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

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

The description states exactly what is retrieved — the network registration record for a public IP (organisation, range, country, abuse contact) — and names the source (regional internet registry over RDAP). That source framing distinguishes it from reputation siblings like abuseipdb_check and virustotal_check, which report maliciousness rather than registration ownership.

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?

"Already run for an IP target; use it for other IPs you find" tells the agent this is a follow-on enrichment step for newly discovered IPs rather than the primary target. It gives clear context but never names an explicit alternative or exclusion condition, so the agent must infer when a different IP tool is the better choice.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive behavior. The description adds useful context by listing what the record contains and explaining that version-check results already carry severity, EPSS, KEV, exploit and fix data. It does not mention rate limits or authentication, so it is not fully 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 tightly written sentences, front-loaded with the primary purpose and followed by the exclusion and alternative use case. No wasted text.

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

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

With no output schema, the description usefully summarizes the record fields and the main usage boundary. It is nearly complete for a lookup tool, but the unexplained investigation_id parameter 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 description coverage is 0%, so the description must carry parameter meaning. It clarifies cve_id via format and example, but investigation_id is not explained anywhere in the description or schema, leaving one of two parameters undocumented.

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

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

States a specific verb and resource (full NVD record for one CVE), gives a concrete CVE example, and enumerates the returned fields. It is clearly distinguishable from cve_search and version_specific_vulnerability_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?

Explicitly says when not to use it: CVEs already returned by a version check. It also says when to use it: a CVE with no existing record, or to read full description and references. The alternative path is named directly.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds useful non-obvious context: results are public addresses only (external DNS), and the target domain has already been resolved in the investigation flow. No mention of rate limits or resolver behavior, but that is secondary given annotations.

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

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

Two short sentences, front-loaded with the action and output type, followed by the routing rule. 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?

With no output schema, the description does at least state the return type (IPv4/IPv6 addresses), which is the key missing piece. However, the unexplained 'investigation_id' parameter leaves a real hole for a tool that is presumably meant to attach results to an existing investigation.

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

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

Schema description coverage is 0% for both parameters, and the description mentions neither. 'domain' is inferable from the name, but 'investigation_id' is entirely undocumented — its purpose, whether it is required in practice, and what changes when it is supplied are all left to guesswork.

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 ('Resolve a domain') plus the exact output shape ('its public IPv4/IPv6 addresses'), which distinguishes it from sibling tools like shodan_search or subdomains. An agent knows immediately what this does.

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 real routing guidance: 'Already run for a domain target; use it for other domains you discover' tells the agent not to re-resolve the primary target and to use it on newly surfaced domains. It stops short of naming a sibling alternative for the primary-target case, so not 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?

Goes well beyond the annotations (readOnly/idempotent/openWorld are already given) by disclosing the quota constraint and, critically, the degraded fallback path when SHODAN_API_KEY is absent — the same call then returns only ports, software, OS and CVEs with no banners or organisation. That is exactly the kind of mode-dependent behavior an agent cannot infer from structured fields.

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

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

Three tight sentences, zero filler, front-loaded with capability before the quota and fallback caveats. Every clause carries operational value.

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 enumerating the returned fields and how the field set shrinks in fallback mode. The only real gap is the unexplained `investigation_id` parameter, which leaves a required piece of the calling contract ambiguous.

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

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

Schema description coverage is 0%, so the description carries the burden. It does explain the required `target` (public IP or domain, resolved to primary IP) well, but `investigation_id` is never mentioned — the agent gets no idea what it links to or when to supply it.

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 ('Shodan host lookup') immediately followed by the exact payload: open ports, services, product versions, hosting org/ASN. This clearly separates it from record-lookup siblings like virustotal_check, abuseipdb_check and ip_owner.

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

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

States accepted input ('a public IP or a domain — its primary IP is used'), which implicitly excludes private IPs, and gives a hard usage rule: 'call once per distinct IP' due to quota. It does not name an alternative sibling for cases where the org/reputation angle is the real goal (e.g. ip_owner or virustotal_check), so it stops short of explicit routing.

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

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

Adds genuine context beyond the annotations: named upstream providers, a fallback path when crt.sh is down, and the important caveat that returned hosts 'may no longer exist' (stale data). 'No key needed' clarifies auth requirements. Return format/pagination is not described, but annotations already cover safety and idempotency.

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

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

Three short sentences, zero filler, front-loaded with what the tool returns and backed by source and caveat. 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 should convey the return shape and the undisclosed investigation_id. It hints that results are hostname lists but leaves the second parameter entirely unexplained and says nothing about volume or paging of CT-log results.

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

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

Schema description coverage is 0% for both parameters, so the description must compensate and does not. The sole required parameter 'domain' is only obliquely referenced ('under a domain'), and 'investigation_id' is never mentioned at all — the agent gets no idea what it does or when to supply it.

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 resource (hostnames under a domain that have had TLS certificates) and the exact data source (crt.sh / Cert Spotter), which is far more informative than the title alone. It does not explicitly distinguish itself from siblings like resolve_domain or shodan_search, but the certificate-transparency framing makes its niche reasonably clear.

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?

'Use it to find other hosts a domain runs' gives an implied when-to-use, but there are no exclusions and no named alternatives among the many sibling tools (resolve_domain, shodan_search, investigate_target). The agent must infer whether this is a discovery step or a validation step.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it explains what each source contributes and discloses a hard rate limit plus the no-key fallback, which annotations cannot express.

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 capability is front-loaded and the parenthetical glosses on Spamhaus DROP and GreyNoise earn their space. The trailing 'Already run for an IP target' sentence is the one piece that is vague rather than informative.

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 should describe what a result looks like, and it does not (listing vs. verdict vs. raw payload). Combined with an entirely undocumented investigation_id parameter, an agent knows the gist but not the call contract.

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

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

Schema description coverage is 0%, so the description must compensate, and it does not. The required ip_address is implied by 'for a public IP', but investigation_id is never mentioned or explained anywhere.

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 ('keyless reputation for a public IP') and names the two underlying sources (Spamhaus DROP, GreyNoise). It does not explicitly differentiate itself from sibling IP-reputation tools like abuseipdb_check or virustotal_check, so an agent must infer the distinction from the source names alone.

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 'Already run for an IP target' hints at when it is relevant but is grammatically unclear and never states when to prefer this over abuseipdb_check, virustotal_check, or shodan_search. The rate-limit note ('10 lookups a day without GREYNOISE_API_KEY') is genuinely useful usage context but addresses constraints, not tool selection.

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

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

Annotations already cover read-only, idempotent, open-world, non-destructive, so the safety profile is settled. The description adds real behavioral substance: matching is gated on NVD CPE confirmation (so non-confirmed CVEs are excluded), results are ranked by KEV/EPSS/CVSS, and ruled-out CVEs are reported — useful expectations that annotations cannot convey.

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

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

The lead claim and the returned-content list are front-loaded, and the parameter examples are packed into the close. Dense but almost every clause carries information; only "Best tool for software risk" is slightly promotional padding.

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

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

With no output schema, the description does the work of describing returns (ranked findings, patch status, minimum safe version, ruled-out list), which is the key gap it needs to fill. The remaining hole is investigation_id semantics and any limits on the CPE-matching fallback when version is omitted.

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

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

Schema description coverage is 0%, so the description has to compensate, and it does for two parameters: software_name ('nginx', 'Apache httpd', 'OpenSSH') and version ('1.20.1', '8.9p1', omit only if unknown). The third parameter, investigation_id, is never mentioned, leaving its purpose and side effects undocumented in both schema and description.

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

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

States a specific verb and resource chain: finds CVEs that NVD CPE data confirms affect this exact product version, then ranks, annotates patch status, and reports ruled-out CVEs. This clearly separates it from siblings like cve_search, nvd_lookup, and cisa_kev_check, which do single-source lookups rather than version-confirmed aggregation.

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?

"Best tool for software risk" plus "Use for every product with a known version (e.g. from Shodan)" gives clear positive guidance and even a source hint for the version input. It does not explicitly name when to prefer cve_search or nvd_lookup instead, so it stops short of full when/when-not coverage.

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

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

Annotations already cover the safety profile: readOnly, idempotent, non-destructive, and open-world. The description adds useful context beyond annotations by stating the API key requirement and clarifying that the result reflects engine flag counts for malicious or suspicious reputation.

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 two front-loaded sentences with no filler. The first sentence states the core purpose and return meaning; the second adds the only hard prerequisite.

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 three-parameter tool with rich annotations but no output schema and zero schema descriptions, the description is adequate but incomplete. It explains the reputation summary and API key requirement, yet it omits parameter details, especially investigation_id, and does not fully specify the return shape.

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

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

Schema description coverage is 0%, so the description must carry the burden. It indirectly explains target_type by saying IP/domain, but it does not explain the target parameter format or the purpose of investigation_id, leaving meaningful required and optional parameter semantics undocumented.

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

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

The description names the specific resource (VirusTotal reputation for IP/domain) and states what the result represents: how many security engines flag the target as malicious or suspicious. It is clear enough to distinguish from generic tools, but it does not explicitly differentiate itself from siblings like abuseipdb_check or threat_lists_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 tool's intended use is implied by 'VirusTotal reputation' and the IP/domain scope, and the description notes the VIRUSTOTAL_API_KEY prerequisite. However, it gives no explicit guidance on when to choose this over sibling reputation tools such as abuseipdb_check or threat_lists_check.

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