CVE Intelligence by Casco

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

The annotations already cover safety because the tool is read-only, idempotent, open-world, and non-destructive. The description adds value beyond that: it explains the three possible outcomes, warns that 'unknown is not clean' and that 'no matches is not proof of safety', and discloses that cache misses send package identities and versions to OSV. This is genuine behavioral context an agent could not infer from 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 definition is front-loaded with purpose, then input forms, then outcome semantics, then the privacy note. Every sentence carries information, so nothing is redundant with the schema or annotations.

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?

An output schema exists, so the description does not need to explain return values. Still, the definition covers batch limits, input modes, outcome interpretation, and outbound data disclosure, which is everything needed to call this single-parameter, open-world 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 100%, so the baseline is 3. The description goes further by explaining that identity can be supplied in two alternative shapes—ecosystem or packageManager plus name and exact version, or a purl—which the flat schema does not make explicit, and by restating the exact-version and batching rule. It could still clarify which identity fields are required in each mode.

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 definition opens with a specific verb and resource: checking installed package versions against OSV advisories, plus a hard batch bound of 100. That is enough for an agent to tell it apart from sibling lookups such as get_cve (single advisory) and list_ecosystems (enumeration).

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 definition gives clear positive guidance on how to invoke the tool: supply 'ecosystem or packageManager plus name and exact version, or a Package URL'. It also states an explicit prohibition against sending raw files, source code, or secrets. It does not name sibling tools or say when to prefer get_cve, so it falls short of full alternative 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?

Beyond the annotations, the description discloses what data the record returns, notes rejection status and source freshness, and clarifies the scope limit that this is not a system-affected determination. It also adds an important trust-boundary warning that source text is untrusted data and never instructions.

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 three compact sentences, front-loads the core lookup purpose, then adds scope and safety context. Every sentence contributes useful information without repetition.

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

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

For a read-only exact-CVE lookup, the description covers the returned record contents, the scope limitation, and the untrusted-source warning. With an output schema present, it need not explain return structure in more detail; the definition is complete enough to invoke the 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 coverage is 100%, and the schema already documents the exact CVE identifier with a pattern and example. The description reinforces that the ID must be exact but does not add syntax or formatting details 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 states a specific verb and resource ('Look up an exact CVE ID') and enumerates what the record contains, including affected products, CVSS severity, references, rejection status, and source freshness. It also distinguishes the result from a system-specific assessment, which separates it from the sibling check_dependencies tool.

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 exact-ID framing tells the agent this is for direct lookups rather than listing updates, and the caveat that this is not a determination of system impact steers away from using it for dependency checking. It does not explicitly name list_cve_updates or check_dependencies as alternatives, so the routing guidance is clear but not fully 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?

Beyond the readOnly/idempotent/openWorld annotations, it discloses three behaviors an agent could not infer: results are bounded, rejected CVEs are included, and the snapshot is explicitly not a complete mirror or event history. That last caveat is exactly the kind of expectation-setting that prevents misuse. It withholds the freshness window (what 'recently updated' actually spans) and any rate-limit guidance, keeping it off 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?

Four tight sentences, front-loaded with the default no-parameter behavior before introducing the incremental mode. Every sentence carries an operational fact, including the closing caveat, and there is no restatement of the title or 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?

With an output schema present, the description only needed to cover mode selection, pagination discipline, and scope caveats, all of which it does. The remaining gap is the unspecified recency window and whether the bounded snapshot has a documented size, which matters for an agent reasoning about completeness of 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?

The description adds real meaning beyond the 67% schema coverage: it explains that after is a checkpoint from a *completed* call and cursor is a nextCursor from an *unfinished* page, and that they are mutually exclusive modes. It also clarifies that the checkpoint is only valid to save after pagination finishes, which the schema does not state. The undescribed limit parameter is a minor, defaults-visible omission.

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

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

The description names a specific verb and resource ('get a bounded snapshot of recently updated CVEs') and separately defines the incremental mode, so the tool's identity as a change-feed reader is unmistakable. It does not explicitly contrast itself with siblings like get_cve or list_ecosystems, but the polling-feed framing is distinctive enough that confusion is unlikely.

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?

Mode selection is spelled out conditionally: omit after/cursor for a snapshot, supply after for incremental changes since a saved checkpoint. It also instructs 'Follow nextCursor and save checkpoint only after pagination completes', which is actionable sequencing guidance. The gap is that it never names an alternative tool or says when a caller should prefer this feed over fetching individual CVEs.

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=false, and destructiveHint=false, so the safety profile is fully covered. The description adds that the payload includes aliases, distribution release requirements, and dependency-check limits, which is genuinely useful context, but it discloses nothing further about volume, currency/staleness of the catalog, or versioning.

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

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

Two sentences, both front-loaded with the enumerations an agent needs. The closing rule is compact but punningly terse ('must remain unknown'), which costs a little clarity for the sake of brevity.

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 parameters, full annotation coverage, and an output schema handling return structure, the description only needs to convey purpose and call timing, which it does. The catalog's freshness and how identities map into check_dependencies inputs are left implicit.

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-burden baseline of 4 applies. Nothing in the description needs to explain arguments, and the sentence about unknown identities is a behavioral rule rather than a parameter claim.

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 ('List') plus a precisely scoped resource ('supported OSV ecosystems, package-manager aliases, distribution release requirements, and dependency-check limits'), which is plainly distinct from the sibling tools check_dependencies, get_cve, and list_cve_updates. It stops short of naming a sibling to contrast with, so it is clear but not fully differentiating.

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?

'before choosing package identities' gives a concrete call-timing rule, and 'Unsupported or ambiguous identities must remain unknown' tells the agent not to guess ecosystem names. What is missing is an explicit pointer to check_dependencies as the follow-up tool once valid identities are known.

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