cve-intelligence

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds useful non-obvious behavior: no key is required over MCP, an API key is honored only for attribution, and null fields carry a specific absence semantic. This goes well beyond the annotation metadata without contradicting it.

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 paragraph, but it front-loads the core purpose and packs in essential semantics like fixed-not-affected_through and absence behavior. No sentence is filler, though the structure could be tightened with clearer separation of concerns.

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 carries the burden of explaining the return value, and it does: it lists all major data categories, defines fixed vs affected_through, and clarifies null semantics. An agent has enough context to invoke the tool correctly and interpret the response.

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 already documents the single 'id' parameter with a format and example ('CVE-2024-3400'), so schema coverage is 100%. The description reinforces that the tool targets one CVE but adds no parameter-level 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?

The description opens with 'Full intelligence record for one CVE' and enumerates specific content: CVSS, EPSS, KEV, fixed versions, detection modalities, and news coverage. This clearly identifies the resource and differentiates it from search-oriented siblings like search_cves or get_scoreboard.

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 'for one CVE' plus the detailed record contents make the intended use case clear: when an agent already has a CVE id and needs the full intelligence profile. It does not explicitly name alternatives or state when not to use the tool, 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses important behavioral nuances: rises are compared within the same EPSS model version so model releases never create false movers, and KEV status is included as observed-exploitation context. It also states the ordering (largest rise first), which is not derivable from annotations or the schema.

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 compact and front-loaded: the core purpose appears in the first clause, followed by parameter default, a key methodological caveat, output fields, and ordering. Every sentence contributes useful information; there is no filler or repetition of the tool name.

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 read-only tool with only two optional parameters and no output schema, the description is fully self-sufficient. It tells the agent what is returned, the ordering, the available windows and defaults, and why the mover signal is reliable, leaving no critical 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?

The input schema already fully describes both parameters, including the enum for window, the range for limit, and defaults. The description adds contextual meaning for window by explaining that it is the rise window, but it does not materially expand on limit or introduce semantics 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?

The description clearly states what the tool does: it returns CVEs whose EPSS exploitation probability rose most recently. It also lists the exact output fields (cve_id, current score, delta, KEV status and url), which is specific and unambiguous. However, it does not explicitly contrast itself with sibling tools like search_cves or get_updates, so the differentiation is implicit rather than stated.

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 when to use the tool: when you want recent EPSS movers, and it explains the window choices (7d or 30d) and default. It does not explicitly state when not to use it or point to alternatives, leaving some routing inference to the agent.

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 communicate read-only and idempotent behavior. The description adds value by disclosing the CC BY 4.0 license and the citation requirement, which is a genuine behavioral constraint beyond annotations. No contradiction exists with readOnlyHint=true.

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?

At roughly 30 words, the description is compact and every phrase carries information: license, report contents, and citation. It is front-loaded with the resource name. It is slightly dense as a single long sentence, 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?

For a parameterless, read-only report getter, the description covers what the report contains and how to cite it, which compensates for the missing output schema. It does not specify the response format, but that is not essential for this 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?

The tool has zero parameters, so parameter documentation is unnecessary; the baseline of 4 applies. The description appropriately focuses on report content rather than inputs.

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 clearly identifies the resource (Defender Scoreboard report) and details its contents: exploited vs detectable vs patchable, method/caveat/denominator, corpus block, and method-change notes. This distinguishes it from siblings like get_cve or search_cves. However, it lacks an explicit verb like 'returns' or 'fetches' and does not directly contrast with sibling 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?

The content description makes the use case clear: an agent should call this when the user needs scoreboard statistics with methodology, caveats, and denominators. It does not explicitly name alternatives or state when not to use it, so it falls short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, lowering the threshold. The description adds genuine behavioral context beyond that: 'stamped with OUR publish time' clarifies that the timestamps are the site's publication moments, not the CVE's own dates (preventing a real misinterpretation), and 'Events for withdrawn CVE ids are omitted' discloses an important filtering behavior. Both add value over the read-only annotation. No contradiction with 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?

A single information-dense paragraph with the purpose front-loaded, followed by pagination mechanics and optional scoping. Every sentence earns its place: purpose, timestamp semantics, since format, cursor continuation, cve filter, and the withdrawal exclusion. Slightly long as one block, but efficient 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 cursor-based stream with 5 parameters and no output schema, the description covers the critical calling mechanics: how to start (since), how to continue (cursor), and available filters (cve, type), plus what event types exist. Gaps are the limit parameter's semantics and the exact shape of returned events (no output schema to fall back on), but the essential continuation pattern an agent must know is fully specified. Fairly complete given the 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 coverage is only 20% (just the cve parameter has a description), so the description must compensate — and it does. It explains the since format (YYYY-MM-DD, strictly-after), the cursor continuation pattern (returned next_cursor), the cve scoping semantics, and enumerates the four type values. Only the limit parameter is left unaddressed. Strong compensation for the sparse 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 identifies a specific resource ('the publication change stream: what this site published') and a distinctive mechanism (cursor-based pagination stamped with OUR publish time). This distinguishes it from siblings like get_cve (single lookup), search_cves (search), and get_epss_movers (movers) without naming them. It's clear and specific, though it doesn't explicitly contrast with any sibling.

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?

Provides concrete, actionable usage instructions: pass since in YYYY-MM-DD strictly-after on the first call, then use the returned next_cursor to continue, with optional cve/type scoping. This is explicit call-pattern guidance. However, it doesn't state when to choose this tool over alternatives such as search_cves, so the when-vs-alternatives dimension is only partially covered (clear context, no exclusions).

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?

Even though annotations already indicate read-only and idempotent behavior, the description adds substantial behavioral context: KEV-first ordering, verbatim OSV range output, the events/fixed/affected_through projection, the explicit refusal to evaluate version membership, and the coverage caveat that absence is not evidence of safety. This goes well beyond what annotations 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?

The description is dense but every sentence earns its place: purpose, input modes, output format, version-range semantics, and an important coverage caveat. The main action is front-loaded and there is no filler or repetition of 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 correctly takes on the burden of explaining return values. It covers what is returned (CVE list, KEV-first), how version ranges are represented (fixed vs affected_through), and what the tool does not do. For a read-only package advisory lookup, nothing critical 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%, so the baseline is 3. The description adds meaningful semantics beyond the schema by clarifying purl vs ecosystem+name usage, flagging Maven group:artifact format, and giving concrete examples like pkg:npm/lodash, which helps an agent construct correct parameter combinations.

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

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

The description opens with a specific verb and resource: 'CVEs affecting one open-source package' and immediately distinguishes the query modes (purl vs ecosystem + name). It clearly separates this from siblings like search_cves and get_cve by emphasizing a single package's advisory list.

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 context for when to use the tool: when you need CVEs for one package, identified by purl or ecosystem + name. It does not explicitly name alternatives or exclusions, but the package-scoped scenario is unmistakable and no misleading guidance is present.

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

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

Beyond the readOnly and idempotent annotations, the description discloses important behaviors: KEV-first then EPSS ordering for filter-only queries, kev_from/kev_to implying kev=1, the precise meaning of fix=0, automatable's unassessed-neither semantics, and the tracked detection signal. These details materially shape how an agent interprets results without contradicting annotations.

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

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

The description is dense but every clause adds signal, and the opening sentence immediately establishes the tool's purpose before the parameter list. Parenthetical per-parameter explanations keep it scannable despite covering 19 parameters, with no filler or repetition of schema type 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?

Input-side behavior is exceptionally well covered given 19 parameters and no required fields. However, with no output schema, return value structure is only partially disclosed: ordering is stated for filter-only queries, but not for free-text queries, pagination defaults, or the full response shape. This is a modest gap in an otherwise thorough definition.

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 only 21%, so the description carries nearly the entire semantic burden for 19 parameters. It provides concrete formats (CWE-nnn, ATT&CK ids, ISO days, epss_gte 0..1), exact enum meanings, examples like 'Microsoft' and 'npm/lodash', and cross-parameter implications. This is far beyond what the bare schema provides.

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

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

The description opens with a clear verb-resource pair, 'Search the catalog', and then enumerates the full set of search dimensions. It differentiates itself from siblings like get_cve by framing this as multi-filter catalog search rather than single-record lookup, and it routes range queries to query_package.

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 concrete usage context, including that filter-only queries return the /browse slice ordered KEV-first then EPSS, and it explicitly names query_package as the alternative for pkg ranges. It does not systematically state when to prefer get_cve or get_updates instead, but the context is clear enough for a competent agent.

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