osv-advisory-mcp-server

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

Annotations declare readOnlyHint=true and idempotentHint=true. Description adds value by listing the fields returned (summary, details, CVEs, etc.), providing behavioral context beyond 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 sentences: first clearly states purpose, second explains usage and return content. Front-loaded and concise with no unnecessary words.

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

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

Given the simple parameter, existence of output schema, and the description's thorough listing of return fields (summary, details, CVEs, affected packages, etc.), the description is complete for an agent to understand functionality and outcomes.

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

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

Schema description coverage is 100% and includes details about the 'id' parameter (prefixes, example). The tool description repeats no parameter-specific information beyond what the schema already provides, so it adds no new semantic value.

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

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

The description uses a specific verb ('Fetch') and resource ('full advisory record for an OSV vulnerability ID'). It distinguishes from siblings by mentioning that osv_query_package and osv_query_batch return vuln IDs, and this tool provides the full context.

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 states when to use: after osv_query_package or osv_query_batch returns a vuln ID and you need full advisory context. Does not mention when not to use, but the usage context is clear.

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

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

Annotations already provide readOnlyHint and idempotentHint. The description adds that the list is static and may lag new ecosystems, providing additional behavioral context beyond the annotations. No contradictions.

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 concise and front-loaded with the main action. Every sentence adds value, and there is no wasted text. It is well-structured for quick parsing.

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

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

Given the tool has no parameters, detailed annotations, and an output schema, the description is fully complete. It provides all necessary information for the agent to use 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?

The tool has zero parameters and schema coverage is 100%, so the description does not need to add parameter information. Baseline is 4 for tools with no parameters.

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 that it returns the list of supported ecosystem identifier strings for use with other tools. It specifies the purpose and exactly what the tool provides, distinguishing it from sibling tools like osv_query_package and osv_query_batch.

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

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

The description explicitly says to use this tool before querying or to verify an ecosystem identifier. It also notes case sensitivity concerns. While it does not explicitly state when not to use it, the guidance is clear for a simple list tool with no alternatives.

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 and idempotentHint, so safety and idempotency are clear. The description supplements with positional correspondence and chaining hints, adding value 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?

Two sentences, front-loaded with purpose and use cases, no filler. Every sentence provides 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?

Given the batch complexity and the presence of an output schema (not evaluated but noted), the description adequately covers input structure and positional output. It could mention the output schema format, but the context signal suggests it exists.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions tuple format and limits, but these are already in the schema. No significant additional semantic meaning 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 clearly states the tool queries vulnerabilities for multiple packages, labels it as the 'primary tool' for dependency audits, and distinguishes it from siblings like osv_query_package (which queries one 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?

It specifies use cases (dependency audits, SBOM scanning, lockfile triage), contrasts with single-query sibling, and mentions a 1000-package limit. However, it does not explicitly state when to avoid this 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 indicate readOnlyHint=true, idempotentHint=true. The description adds behavioral details: returns OSV advisories with severity (CVSS), CVE aliases, affected version ranges, and first safe version. It also notes that invalid ecosystem returns error, not empty results. No contradictions.

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 focused sentences: the first states the core function, the second provides essential usage guidance. No unnecessary words, and critical information is front-loaded.

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

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

For a single-package query tool, the description covers input validation, return contents, and error behavior. An output schema exists (not shown but noted), so return values are expectedly documented. The description is complete for effective use.

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

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

Schema coverage is 100%, so the schema already documents each parameter thoroughly (type, pattern, examples). The description adds context about ecosystem validation and case-sensitivity, but this is largely redundant with the schema descriptions. Baseline 3 is appropriate with minimal added value.

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 the tool queries known vulnerabilities for a single package version across supported ecosystems, using specific verbs and resource. It implicitly distinguishes from siblings like osv_get_vulnerability (which queries by ID) and osv_query_batch (which handles multiple packages).

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 to use osv_list_ecosystems for ecosystem validation before querying, and warns that invalid ecosystem strings return errors. This provides clear when-to-use guidance and a direct alternative, meeting the top criteria.

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