vuln-intel

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

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description layers on substantive behavior: citations are validated against the retrieved corpus, ungrounded ones are flagged in 'citations.ungrounded' with 'citations_grounded=false'. It also draws an honest boundary ('this guards the citations only — never read it as a verdict on whether your finding itself is real'), which is exactly the kind of caveat an agent needs.

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 main purpose and the four numbered deliverables are front-loaded, and the guard explanation is a useful, non-redundant sentence. It is on the verbose side with nested parentheticals, but every clause carries information 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?

With no output schema and a read-only analysis tool, the description carries the full burden and meets it: it describes the four brief sections and the citations_grounded structure of the return. Combined with the explicit sibling contrast, 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 0%, so the description must compensate. It explains the 'query' parameter well (optional override of retrieval text, defaulting to the finding itself) and clarifies 'finding' via the paste instruction, but the 'limit' parameter (default 15) is left entirely unexplained. Two of three params are meaningfully covered, so a mid score.

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: a 'submission & escalation co-pilot' that turns a draft finding into a grounded brief. It even enumerates the four deliverables, so the agent knows exactly what it returns. It explicitly distinguishes itself from the sibling find_attack_approaches ('which returns the raw prior-art cards').

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?

Tells the agent to paste a DRAFT finding plus what was tried/couldn't be achieved, which gives clear situational context. It names and contrasts the closest sibling, routing the agent appropriately. It stops short of an explicit when-not condition, so 4 rather than 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: results are de-duplicated and ranked by priority/EPSS/CVSS, ambiguous name collisions are flagged with distinct_vendors, and match.products should be checked. It stops short of 5 by not explaining result contents or pagination.

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 and structures the disambiguation caveat and args clearly. Slightly redundant phrasing ('Distinct products that share a name are kept distinct' followed by the vendor-collision example) costs a little, but every block still 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?

No output schema exists, so the description must describe returns; it covers the ambiguous flag, distinct_vendors, match.products, and the ranking basis, which is the important part for correct interpretation. It does not describe the shape of an individual vulnerability record, leaving a modest gap for a 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?

With 0% schema description coverage, the description carries the full burden and does it well: product, version ('filters to vulns whose affected range actually includes it'), ecosystem with concrete examples, and vendor as a disambiguation filter with example values. Only limit ('max results') is thin, and it is self-explanatory.

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 with unusual precision: 'Find vulnerabilities affecting a product across NVD (CPE) and OSV (package ecosystems), de-duplicated and ranked by priority/EPSS/CVSS.' The product-centric scope implicitly separates it from the broader search_vulns sibling, but no sibling is named or contrasted, 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?

Gives concrete operating context: when a name maps to several unrelated vendors, pass vendor= to disambiguate, and always verify match.products before trusting a hit. It never states when not to use this tool or explicitly routes to alternatives like search_vulns, so it lacks the explicit when/when-not framing 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds the useful fact that the data is local-corpus metadata (counts and timestamps), but says nothing about cost, caching, or how the freshness values should be interpreted.

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 tight parenthetical phrase, front-loaded with the two things it reports. It is efficient, though the verbless fragment form is slightly less self-explanatory than a full sentence.

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 (counts plus latest timestamps), which is exactly what an agent needs to know. A zero-param read-only tool needs little more.

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 zero parameters, so the schema carries nothing to explain; baseline 4 applies. The description correctly implies a no-argument snapshot call.

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 the resource (corpus) and precisely enumerates the signals returned: CVE/KEV/EPSS counts and latest timestamps. No verb, and it doesn't differentiate from siblings like search_vulns or enrich_cve, but the intent is unambiguous.

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 call this versus alternatives. The agent must infer that this is a pre-flight freshness/metadata check rather than a search tool; nothing in the text guides that 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 declare readOnlyHint and openWorldHint, and the description is consistent with both while adding genuine context: include_poc performs a live GitHub query, and exploit signal is described as live. It does not discuss latency, rate limits, or what happens when a CVE is unknown, but the live-network behavior of the optional flag is disclosed, which the annotations alone would not convey.

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

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

The payload list is front-loaded in the first sentence and the Args block is terse. Every clause carries information, though the '(live)' qualifier appears twice and the second occurrence is redundant.

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 enumerates the returned fields so an agent knows what to expect, and annotations cover the read-only safety profile. Missing details are minor: no guidance on unknown-CVE behavior or the cost/latency of the live PoC query.

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 burden and largely meets it: cve_id gets an explicit format example ("CVE-2025-12345") and include_poc is explained as a live GitHub PoC lookup (default true, which the schema supplies). The only gap is that the description never says what happens if cve_id is malformed/unknown.

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 (enrich) and resource (single CVE) and then enumerates exactly what intelligence is returned: CVSS, KEV, EPSS, CISA SSVC fields, P1-P4 priority with rationale, affected products/versions, and live exploit signal. The 'single CVE' scope cleanly separates it from corpus-wide siblings like search_vulns.

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: you call this to get the full picture on one known CVE id. The description does give the condition for the optional flag ('include_poc: also query GitHub for public PoC/exploit repos'), but never states when to prefer this over siblings such as search_vulns or verify_cve_claim, nor any prerequisite for having a valid CVE id.

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 only cover readOnlyHint=true and openWorldHint=false, so the description adds real behavioral context: results are grounded in publicly-disclosed paid HackerOne reports, novelty-ranked to surface non-obvious moves (or bounty-ranked in capec mode), and each result reports program liveness/in-scope status. It stops short of describing pagination or result volume behavior, keeping it just 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 purpose and then organized into a clear query/cve block and an optional-filters block, so it is scannable. It is somewhat verbose and stylized (BORROW, UNSTUCK, quoted asides), and a few clauses restate the value proposition, but nearly every sentence carries actionable invocation detail.

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 7-parameter, no-output-schema retrieval tool, the description covers input modes, filter interactions, ranking behavior, and even the shape of returned fields (capec class, trigger, program, bounty, program liveness). 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?

With 0% schema description coverage the description must carry every parameter, and it does: query (with examples), cve_id, bug_class, days, tried (with a concrete example and its push-down semantics), and capec (with an example and the solo-usage constraint). The only unmentioned param is limit, whose default of 10 is self-evident; the mutual-exclusivity rule for capec is a genuine semantic addition the schema cannot express.

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: retrieving real disclosed bug-bounty mechanic-cards by mechanism similarity to a query or seed CVE. It layers the purpose precisely ('the what approach worked on a bug like this, on which program, and what did it pay layer') and explicitly positions itself as a complement to find_similar_vulns, so an agent can distinguish it 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?

Gives explicit when-to-use framing ('BORROW a proven attack approach... especially to get UNSTUCK') plus concrete invocation modes: EITHER query OR cve_id, and capec 'Pass it ALONE (no query/cve)' for coverage-driven retrieval. It also names the alternative/complement (find_similar_vulns) and the exhausted-playbook scenario that selects the tried filter.

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 only cover readOnly/openWorld; the description goes far beyond them with a HARD CONTRACT that every result is status=UNVERIFIED (a legal move, never a confirmed bug) and that each carries a 'decisive_check' the agent must verify against the target. It also discloses the matching substrate (full report bodies vs. distilled cards), which affects what the tool can surface.

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?

Purpose is front-loaded in the first sentence and the hardest constraint (UNVERIFIED contract) is placed last for emphasis. It is dense and slightly noisy with all-caps emphasis and asides, but nearly every sentence carries actionable 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 still explains the return shape (move_step techniques, decisive_check, status=UNVERIFIED), the source corpus, and param usage, so an agent knows both how to call it and how to interpret 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%, so the description must compensate, and it does for the two non-trivial params: 'position' is defined with concrete examples and a quality caveat, and 'program' is specified as a substring match on handle. The integer 'limit' is left unexplained, keeping this short of a 5.

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: it takes a product-free 'position' describing attacker state and returns 'continuations' (concrete move_step techniques) drawn from full disclosed-report bodies. It explicitly distinguishes itself from the sibling find_attack_approaches by labeling itself the 'by-step, full-body layer' versus the by-card layer.

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 an explicit trigger ('When you're STUCK mid-hunt') plus two worked examples of the position input and a sharpening hint ('richer/sharper the position, the better — vague positions retrieve generic moves'). It names the complementary alternative and the axis that separates the two 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 readOnlyHint=true and openWorldHint=false, so the safety profile is partly covered. The description adds genuine behavioral context beyond that: data provenance (KEV / CISA-SSVC-active / high-EPSS ranking, 'grounded in exploitation data, not model guesses'), the output ordering principle (dig_rank), and the explicit 'never a payload' assurance.

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 core action and output, then documents args compactly. The closing line ('Grounded in exploitation data, not model guesses; lays out facts... never a payload') is slightly redundant with the earlier ranking claims but reinforces the no-payload guarantee, so it mostly 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?

There is no output schema, yet the description adequately characterizes the return shape: ranked CVEs with source priorities, recurring_loci bug classes, and component dig_rank ordering. An agent has enough to know what it will get and how to call it, though pagination/limits and component-matching behavior are 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 description coverage is 0%, so the description carries the burden and does so well: technologies is explained with a concrete example list ('craftcms 4.4', 'nginx', 'keycloak'), and per_tech is defined as the count of top CVEs per component with its default of 4. Both parameters are given usable meaning that the schema lacks.

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

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

Names a specific verb (turn/rank) and resource (a recon'd stack into a ranked dig-order), and precisely describes the composite output: per-component CVEs plus recurring_loci CWE classes. This differentiates it cleanly from siblings like search_vulns and enrich_cve, which act on individual CVEs rather than a whole stack.

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 the context ('authorized bug-hunting', post-recon stack, triage/where-to-look) and the framing intent clearly. It does not explicitly name when to prefer it over siblings like search_vulns or find_attack_approaches, so it stops short of a full when/when-not rubric.

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 only declare readOnlyHint and openWorldHint; the description adds substantial behavior beyond that: the scan is non-blocking, takes ~1-4 min, cached results (<24h) return instantly, cache misses kick a background scan, and the caller must poll. It also states the authorization constraint. No contradiction with readOnlyHint since it only fetches public pages.

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 purpose, then a clearly delineated NON-BLOCKING status contract and an Args block. Every section is useful, though the 'recon workhorse' framing and parenthetical asides add slight 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 fully documents the three return states (ready/scanning/error) and their payloads, plus the polling contract and retry_after_seconds. That is exactly what an agent needs to drive a long-running, non-blocking tool 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 0%, so the description must carry the full burden, and it does: host is a hostname or URL in an authorized scope with an example, fresh forces a new background scan, and per_tech is the top CVEs surfaced per component with its default. All three parameters are explained with semantics beyond their bare type.

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+scope: 'Scan a host's exposed stack and join it to the CVE corpus', and clarifies it fingerprints homepage + JS bundles to recover backend identity and API endpoints. An agent knows exactly what it produces. It does not, however, differentiate itself from siblings such as check_technology or search_vulns by name.

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 operational context — authorized bounty scopes only, public pages only, and when to use the fresh flag to force a re-scan. It does not name any alternative sibling tool or state when this should be preferred over check_technology/search_vulns, so it stops short of explicit when-not guidance.

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

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

Annotations only declare readOnlyHint and openWorldHint=false; the description adds substantial context beyond that: data provenance (HackerOne disclosed reports, ~379 programs), selection bias (disclosure-selected sample), HackerOne-only scope, that it models bug-class rather than payout, and that it withholds a prior when sample size is too small. That is exactly the behavioral disclosure annotations cannot carry.

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?

Purpose is front-loaded in the first sentence, and the remaining sentences each add a distinct fact (data source, limitations, parameter example, sibling routing). Slightly overlengthy with heavy caps/emphasis and the 'DESCRIPTIVE, not predictive' point partially restated, costing it a point.

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 describe the return shape — and it does precisely: class distribution with lift over global base-rate, sample size, cited example reports, plus the `lands_rarely` bucket. Combined with scope limits and parameter guidance, an agent has everything needed to invoke and interpret it.

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% with a single required `program` param, so the description must compensate — and it does, stating 'a program handle or name' with concrete examples ('gitlab', 'shopify'). It stops short of format rules (case sensitivity, URL vs handle), so not a full 5.

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: retrieve a grounded prior over historically-landed bug classes for a named bounty program. It explicitly distinguishes itself from siblings by naming find_attack_approaches (mechanism transfer) and hunt_plan (CVE dig-order), so an agent can route 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 an explicit trigger ('At the START of an engagement'), an explicit goal ('what to look at first and what to skip'), and names the closest alternatives with the axis on which they differ. It also flags the negative case implicitly via `lands_rarely` ('where NOT to spend the first hour').

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 (readOnlyHint, openWorldHint), and the description adds real value on top: results are RAW and carry no vulnerability judgment, and the agent is expected to fetch and read hits rather than treat them as conclusions. It stops short of describing result shape, ranking, or rate-limit behavior, which matters for an open-web search.

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 purpose, then use-case, then a caveat about raw results, then args — a sensible order. The capitalized emphasis ("WHERE", "FETCH AND READ") and the args block are slightly heavier than needed given the schema already lists the properties, but nothing 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?

With no output schema, the description correctly tells the agent what comes back (raw locations, not judgments) and what to do next (fetch and read). For a read-only, open-world search tool that is close to sufficient; return format and pagination beyond `limit` remain unspecified.

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

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

Schema description coverage is 0%, so the description must carry the parameters — and it does. It defines `code` (an exact code string, with a concrete example), `lang` (language filter, default "c"), and `limit` (max hits), each adding meaning beyond the bare schema titles.

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 — 'Search public repositories for an exact code string' — and clarifies the output shape ('return WHERE it appears'), which is more than a restatement of the name. It does not name or contrast any sibling (e.g. search_vulns, which searches vulnerability records rather than code), so the differentiation is inferred 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?

Gives concrete when-to-use guidance: hunt vendored/copy-pasted copies of known-vulnerable code, start from a distinctive line or symbol, then fetch and read the hits to judge patch/reachability status. This is a clear operational workflow, but it offers no exclusions or contrast against the other search-flavored siblings.

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 only declare readOnlyHint=true and openWorldHint=false; the description goes further by disclosing that query defaults to fusing lexical+semantic retrieval, that order toggles which retrieval runs, that severity ranks P1>P4, and that product= is CPE-resolved with match.products provenance. It does not state pagination or result-size limits, so it falls short of the top of the scale.

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 mode taxonomy before the flat arg list, and the sibling routing is placed at the end as a footer. It is longer than strictly necessary — 'You decide which matches matter' and some parenthetical asides are filler — but nearly every sentence adds routing or behavioral 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?

With no output schema, the description compensates by describing the ranked cards, the priority/KEV/EPSS/CWE fields, total_matches for coverage, and the mode field that reports which retrieval ran. Gaps remain on how cwe combines with query and on result-size behavior, minor for a read-only search 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 0% and the schema exposes bare titles only, so the description carries the full burden. It nonetheless defines all seven parameters, including accepted value forms (e.g. 'CWE-502' or '502'), the enum-like order values, and the non-obvious constraint that days/product require NO query.

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 (search the CVE corpus) and enumerates the three retrieval modes keyed to distinct argument shapes. It explicitly differentiates itself from siblings hunt_plan and find_attack_approaches by naming the scenario each covers.

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 when-to-use routing: query for concept/keyword search with fusion defaults, cve_id for the 'what else looks like this' mechanism-sibling move, and days/product-only for the recent high-risk window. It also names two alternatives and the condition that selects each.

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=true and openWorldHint=false, and the description is consistent with that safe, corpus-local read. It goes beyond the annotations by disclosing the output shape (per-assertion supported/refuted/unverifiable verdicts with cited evidence) and the fact that free-text 'claim' returns summary/CWE evidence for the caller to judge. No permissions, rate limits, or pagination details, but none are needed for a stateless read.

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 purpose and the four verification axes, then usage, then a compact Args block and an example — a sensible order with little waste. The 'catch hallucinations before they ship' clause is mild marketing, and the Args list partially restates schema titles, but the net density is high.

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 and 0% schema coverage, the description must cover both invocation and return; it does, describing the verdict vocabulary and the evidence payload. An agent has everything needed to call it correctly 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?

Schema description coverage is 0%, so the description carries the full burden and does so: it marks cve_id as the id being claimed about, flags product/version/severity/exploited as optional with their semantics ('checks the affected-version claim in range', severity accepts a number or label), and explains claim as free-text evidence mode rather than a verdict. The example call demonstrates correct argument usage directly.

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 ('Fact-check a claim about a CVE against the corpus') and enumerates exactly what is verified: existence, affected product/version, severity, KEV exploitation. This clearly separates it from siblings like search_vulns and enrich_cve, which retrieve rather than adjudicate a claim.

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 an explicit trigger ('check what another agent (or a draft report) asserted') plus a worked example mapping a natural-language claim to an invocation, which is unusually actionable. It stops short of naming alternatives or when-not to use it (e.g., versus search_vulns for open retrieval), so it is clear context without exclusions.

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