vulners-mcp

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

With no annotations, the description carries the full burden. It discloses the backend (Vulners DB) and that it is an audit (implying read-only), but says nothing about rate limits, result size, or error behavior. Adequate but thin.

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 verb+resource and then the data source. No wasted 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?

For a 4-parameter tool with no annotations and no output schema, the description identifies the function but omits what the audit returns (vulnerability list shape, limits, pagination) and any prerequisite for obtaining valid package strings.

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 schema already explains os, version, package format, and include_candidates in detail. The description adds only the RPM/DEB framing, which the schema already covers.

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 ('Linux package audit') scoped to RPM/DEB distros and names the data source (Vulners database). It distinguishes itself from generic tools but does not explicitly differentiate from the sibling 'audit_software', which an agent must infer.

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 use this versus 'audit_software' or the other search tools, nor any prerequisites or exclusions. The only routing help ('Use get_supported_os()') lives in the schema's parameter descriptions, not the description itself.

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?

No annotations are provided, so the description carries the full burden. 'Audit ... for known vulnerabilities' implies a read-only lookup, but it says nothing about the response shape (catalog of CVEs?), whether an unmatched version errors or returns empty, or any limits. It hints at the behavioral profile without disclosing 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?

Two sentences with the purpose front-loaded and the search_lucene exclusion last; every sentence carries meaning. The emoji framing and repeated all-caps add visual noise without adding information, which is a minor deduction.

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 annotations and no output schema, the description must cover behavioral and return-value context on its own, but it only covers input expectations. For a tool whose result (a vulnerability report) is entirely unspecified, an agent still cannot predict what it will get back.

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 the nested CPE fields are thoroughly documented in the schema itself. The description reinforces the exact-version requirement and repeats the Chrome example already present in the schema, adding little beyond it, so the baseline 3 is appropriate.

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 a clear qualifier: 'Audit specific software versions for known vulnerabilities,' plus a concrete example. It distinguishes itself from search_lucene, but says nothing about the closely related sibling audit_linux_packages, leaving one obvious boundary unaddressed.

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 names the precondition ('when you have exact software version information') and an exclusion ('NEVER use search_lucene for version-specific software audits'), which is strong when-to-use/when-not-to guidance. It omits routing against audit_linux_packages, the most similar sibling, so the guidance is clear but not exhaustive.

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?

No annotations are provided, so the description carries the full burden and does so: it names exactly what the default compact response contains, warns that requesting everything 'can be very large', and quantifies the reference-graph risk (a few KiB to 100+ MiB). Silent-list-mode behavior changes are disclosed rather than left to discovery.

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 primary-use case and the size warnings, and every sentence carries operational content. Slightly verbose in places where it restates schema field lists, and the emoji banner is noise, but there is no filler paragraph.

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 needn't document return shapes, and it still covers the practical gaps: default vs widened projections, payload size ceilings, and the list-mode override. Nothing an agent needs to call this 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it enumerates the default projected field set, names high-value fields to widen with, and explains that list inputs force references=False. Most of this also appears in the schema field text, so it complements rather than exceeds 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 verb (Fetch) plus resource (bulletin) and scopes it to 'known IDs' via CVE or Vulners ID. It explicitly distinguishes itself from the sibling search_lucene, so an agent can pick it 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 when-to-use ('PRIMARY TOOL FOR KNOWN IDs'), when-not ('NEVER use search_lucene for known IDs'), and the alternative widened-response path (fields=[...] or references=True). It also states the list-mode override ('references are automatically set to False'), leaving no routing 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?

No annotations are provided, so the description carries the burden. The verbs 'List'/'Get' imply a safe read-only lookup, which is reasonable for a zero-parameter enumerator, but the description discloses nothing about return size, pagination, caching, or auth needs. With an output schema present, the return-shape gap is partially excused.

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 primary purpose. There is mild redundancy between 'List supported OS identifiers/versions' and 'Get available operating systems', which repeat the same idea rather than adding new 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?

For a zero-parameter lookup with an output schema, the description covers what the agent needs to select it: the resource (supported OS identifiers/versions) and the downstream purpose (Linux package audit, vulnerability analysis). No input details are required and returns are documented by the schema.

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, which is the baseline-4 case. Nothing in the description needs to explain inputs, and it correctly signals that this is a parameterless enumeration.

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: 'List supported OS identifiers/versions' and 'Get available operating systems.' It is clearly a reference/enumeration lookup, distinguishable from action-oriented siblings like audit_linux_packages or search_cpe, though it never names those alternatives explicitly.

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 phrases 'for Linux package audit' and 'for vulnerability analysis', which tell the agent this is a prerequisite lookup step. However, there is no explicit when-to-use/when-not guidance and no mention of which sibling to prefer for OS discovery.

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?

No annotations are provided, so the description carries the full behavioral burden. 'Get search suggestions' implies a read-only lookup, which is useful, but there is no disclosure of return shape, result limits, rate limiting, or authentication needs for a database-backed endpoint.

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 purpose and domain of suggestions. Minor redundancy between 'Autocomplete helper for search inputs' and 'Get search suggestions,' but 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 single-parameter helper with no output schema, the description covers what it is, what it takes, and the domain of acceptable inputs. Slightly thin on what the returned suggestions look like, but adequate for such a simple 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 100%, and the nested body/query structure is fully documented in the schema with examples. The description adds domain context ('vendors, products, CVEs') that tells the agent what kinds of strings are valid queries, going slightly beyond the schema's own examples.

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 combination: a suggestion/autocomplete helper for search inputs, with concrete examples (vendors, products, CVEs). It is not differentiated from siblings such as search_lucene or search_cpe, which an agent could plausibly confuse with a suggestion endpoint.

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?

Implicit usage is conveyed by 'for search inputs,' suggesting this returns suggestions rather than results. However, it never states when to prefer this over the real search tools (search_lucene, search_cpe), nor any exclusions or prerequisites.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It never states that this is a read-only lookup, says nothing about result limits beyond the schema default, matching/ranking behavior, or what a hit looks like. Only the bare 'search' semantics are conveyed.

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 concrete action. The second sentence largely restates the first in expanded form, which is mild redundancy but not bloat.

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 annotations and no output schema, the definition should say more about what is returned (CPE 2.3 strings? ranked matches?) and how size interacts with server defaults. It is minimally adequate but leaves real gaps for a 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 description coverage is 100%, so vendor, product, and size are already documented with examples and case-insensitivity notes. The description adds little beyond restating the vendor+product pairing, so the baseline 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?

States a specific verb (Find/Search) and resource (CPE strings / Common Platform Enumeration identifiers) with the scoping keys (vendor+product). It is clearly distinguishable from siblings like search_lucene or audit_software, though it does not explicitly name those alternatives.

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?

No guidance on when to use this tool versus search_lucene, query_autocomplete, or the audit_* tools. The parenthetical '(latest schema)' hints at a versioning choice but is unexplained, leaving the agent to infer context.

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?

No annotations exist, so the description carries the burden, and it delivers real behavioral context: supported Lucene syntax, the vendor/product field trap, and the fact that 'affectedSoftware' does not exist. It stops short of disclosing auth requirements, rate limits, or default result behavior beyond what the schema already states.

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 tool's role and the alternative-tool routing before the field caveat, and every sentence carries actionable content. Heavy emoji/ALL-CAPS emphasis and partial duplication of the schema's query description cost 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?

For a search tool with no output schema, it covers selection, alternatives, syntax, and field naming, and the fields parameter description conveys the default per-hit projection. Only the shape of the returned hits and pagination semantics 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?

Schema description coverage is 100%, so all four parameters (query, size, skip, fields) are already documented in the schema, including the 100 hard cap and the curated default projection. The description's query-field guidance largely duplicates the schema's query description, adding little beyond 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 verb and resource ('Full-text search in Vulners Knowledge Base using Lucene syntax') and immediately frames itself as the discovery tool for unknown vulnerabilities. It explicitly distinguishes itself from sibling tools bulletin_by_id and audit_software by naming the cases each handles.

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 ('ONLY when you don't have specific IDs or version information') and two when-not-to-use rules, each routing the agent to the correct sibling (bulletin_by_id, audit_software). The vendor/product field requirement further constrains correct invocation.

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