Skip to main content
Glama

Osv Query Package

osv_query_package
Read-onlyIdempotent

Query known vulnerabilities for a single package version across any supported ecosystem. Returns all matching OSV advisories with severity (CVSS vectors), CVE aliases, affected version ranges, and the fixed versions listed for the queried package. Use osv_list_ecosystems to validate the ecosystem string before querying — ecosystem strings are case-sensitive exact matches and an invalid value returns an error, not empty results.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameYesPackage name as it appears in the ecosystem (e.g. "express", "requests", "serde"). Case-sensitive.
versionYesPackage version to check (e.g. "4.17.1", "3.1.4", "1.0.0"). Must be an exact version string, not a range.
ecosystemYesEcosystem identifier. Must be an exact match (case-sensitive). Use osv_list_ecosystems to see valid values. Examples: "npm", "PyPI", "crates.io", "Go", "Maven", "NuGet".

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
vulnsNoVulnerabilities matching this package version. An empty array means no known vulnerabilities ONLY when truncated is false.
noticeNoPresent on the clean path — confirms no known vulnerabilities for the queried package.
queryMetaNoQuery parameters as submitted.
truncatedNoTrue when OSV returned more result pages than the fetch cap could follow — the vulnerability list may be INCOMPLETE. A truncated empty list is NOT a clean result; raise OSV_QUERY_MAX_PAGES or narrow the query.
effectiveQueryNoThe package@version (ecosystem) tuple as queried, echoed for content-only clients.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed13 schema fields changed
    • removedInput schema / properties / ecosystem / minLength
      Removed value: -1
    • removedInput schema / properties / name / minLength
      Removed value: -1
    • removedInput schema / properties / version / minLength
      Removed value: -1
    • changedOutput schema / properties / vulns / items / properties / affectedRanges / items / properties / fixed / description
      Previous value: -"First safe version — the version to upgrade to (convenience view — see events[])."New value: +"The last \"fixed\" event of this range (convenience view — a multi-interval range carries several; see events[])."
    • changedOutput schema / properties / vulns / items / properties / fixedVersions / description
      Previous value: -"First safe version(s) per affected package entry. Empty if no fix exists yet."New value: +"Every fixed version the advisory lists for the queried package, in record order. A multi-interval range contributes one per interval (typically one per release line); affectedRanges shows which interval each one closes. Excludes other packages' fixes and GIT commits. Empty when the advisory lists no fix for this package."
    • changedOutput schema / properties / vulns / items / properties / fixedVersions / items / description
      Previous value: -"A first-safe version string."New value: +"A version that fixes the vulnerability for the queried package."
    • changedOutput schema / properties / vulns / items / properties / severity / description
      Previous value: -"CVSS severity entries. May be empty for advisories not yet scored."New value: +"Record-level severity entries (CVSS vectors, Ubuntu priorities). Empty for advisories not yet scored and for advisories that score each affected package separately — severitySource then carries the queried package entry used."
    • changedOutput schema / properties / vulns / items / properties / severity / items / description
      Previous value: -"One CVSS severity entry."New value: +"One record-level severity entry."
    • changedOutput schema / properties / vulns / items / properties / severity / items / properties / score / description
      Previous value: -"CVSS vector string (e.g. \"CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:L\")."New value: +"CVSS vector string (e.g. \"CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:L\"), or the Ubuntu priority (e.g. \"medium\") for type \"Ubuntu\"."
    • changedOutput schema / properties / vulns / items / properties / severity / items / properties / type / description
      Previous value: -"CVSS version: \"CVSS_V3\", \"CVSS_V4\", or \"CVSS_V2\"."New value: +"Severity type: \"CVSS_V3\", \"CVSS_V4\", \"CVSS_V2\", or \"Ubuntu\"."
    • changedOutput schema / properties / vulns / items / properties / severityLabel / description
      Previous value: -"Human-readable severity label (\"LOW\", \"MODERATE\", \"HIGH\", \"CRITICAL\"). Present on GHSA-sourced records; null otherwise."New value: +"Severity label (\"LOW\", \"MODERATE\", \"HIGH\", \"CRITICAL\") from the first source that yields one: database_specific.severity, an Ubuntu priority, then the highest CVSS v3/v4 score (0.1–3.9 LOW, 4.0–6.9 MODERATE, 7.0–8.9 HIGH, 9.0–10.0 CRITICAL). Uses the queried package's affected-level severity entries when the record-level list is empty. Null when no source yields a label."
    • addedOutput schema / properties / vulns / items / properties / severitySource
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": false,
      +      "properties": {
      +        "computedScore": {
      +          "description": "CVSS score computed from the vector as published: a CVSS 4.0 vector over every metric group it carries (threat and environmental included), a CVSS 3.x vector with its temporal metrics. Present only for CVSS sources.",
      +          "type": "number"
      +        },
      +        "score": {
      +          "description": "The published value the label came from: the database_specific.severity text, the Ubuntu priority, or the CVSS vector.",
      +          "type": "string"
      +        },
      +        "type": {
      +          "description": "Source kind: the database_specific.severity label, an Ubuntu priority, or a CVSS vector.",
      +          "enum": [
      +            "database_specific",
      +            "Ubuntu",
      +            "CVSS_V3",
      +            "CVSS_V4"
      +          ],
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "type",
      +        "score"
      +      ],
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "The severity entry severityLabel was derived from. Null exactly when the label is."
      +}
    • changedOutput schema / properties / vulns / items / required
      Previous value: -[
      -  "id",
      -  "summary",
      -  "aliases",
      -  "severity",
      -  "severityLabel",
      -  "fixedVersions",
      -  "affectedRanges",
      -  "cweIds",
      -  "published",
      -  "modified"
      -]New value: +[
      +  "id",
      +  "summary",
      +  "aliases",
      +  "severity",
      +  "severityLabel",
      +  "severitySource",
      +  "fixedVersions",
      +  "affectedRanges",
      +  "cweIds",
      +  "published",
      +  "modified"
      +]
  2. Changed2 schema fields changed
    • removedOutput schema / properties / vulns / items / properties / severityLabel / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / vulns / items / properties / severityLabel / type
      Added value: +[
      +  "string",
      +  "null"
      +]
  3. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "vulns",
      +      "truncated",
      +      "queryMeta"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • addedOutput schema / properties / error
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Present when the call failed. Absent on success.",
      +  "properties": {
      +    "code": {
      +      "description": "JSON-RPC error code for this failure.",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "data": {
      +      "additionalProperties": {},
      +      "properties": {
      +        "reason": {
      +          "description": "Machine-readable failure mode. Declared by this tool: `invalid_ecosystem`: The ecosystem string is not recognized by OSV. Ecosystem names are case-sensitive exact matches. Other values are possible when a failure originates below the handler.",
      +          "examples": [
      +            "invalid_ecosystem"
      +          ],
      +          "type": "string"
      +        },
      +        "recovery": {
      +          "additionalProperties": {},
      +          "description": "Actionable next step for the caller.",
      +          "properties": {
      +            "hint": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "hint"
      +          ],
      +          "type": "object"
      +        },
      +        "retryable": {
      +          "description": "Whether retrying may succeed.",
      +          "type": "boolean"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "message": {
      +      "description": "Human-readable description of what went wrong.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "code",
      +    "message"
      +  ],
      +  "type": "object"
      +}
    • removedOutput schema / required
      Removed value: -[
      -  "vulns",
      -  "truncated",
      -  "queryMeta"
      -]
  4. Changed6 schema fields changed
    • addedInput schema / properties / ecosystem / minLength
      Added value: +1
    • addedInput schema / properties / ecosystem / pattern
      Added value: +"\\S"
    • addedInput schema / properties / name / minLength
      Added value: +1
    • addedInput schema / properties / name / pattern
      Added value: +"\\S"
    • addedInput schema / properties / version / minLength
      Added value: +1
    • addedInput schema / properties / version / pattern
      Added value: +"\\S"
  5. Changed11 schema fields changed
    • addedOutput schema / properties / truncated
      Added value: +{
      +  "description": "True when OSV returned more result pages than the fetch cap could follow — the vulnerability list may be INCOMPLETE. A truncated empty list is NOT a clean result; raise OSV_QUERY_MAX_PAGES or narrow the query.",
      +  "type": "boolean"
      +}
    • changedOutput schema / properties / vulns / description
      Previous value: -"Vulnerabilities matching this package version. Empty array means no known vulnerabilities."New value: +"Vulnerabilities matching this package version. An empty array means no known vulnerabilities ONLY when truncated is false."
    • changedOutput schema / properties / vulns / items / properties / affectedRanges / items / properties / ecosystem / description
      Previous value: -"Affected package ecosystem."New value: +"Affected package ecosystem. Empty for source-only advisory ranges."
    • addedOutput schema / properties / vulns / items / properties / affectedRanges / items / properties / events
      Added value: +{
      +  "description": "Ordered event boundaries for this range — the loss-free view preserving multiple introduced/fixed pairs the scalar fields collapse.",
      +  "items": {
      +    "additionalProperties": false,
      +    "description": "One ordered range event.",
      +    "properties": {
      +      "type": {
      +        "description": "Event boundary type: \"introduced\", \"fixed\", \"last_affected\", or \"limit\".",
      +        "type": "string"
      +      },
      +      "value": {
      +        "description": "Version string or commit identifier at this boundary.",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "type",
      +      "value"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / properties / vulns / items / properties / affectedRanges / items / properties / fixed / description
      Previous value: -"First safe version — the version to upgrade to."New value: +"First safe version — the version to upgrade to (convenience view — see events[])."
    • changedOutput schema / properties / vulns / items / properties / affectedRanges / items / properties / introduced / description
      Previous value: -"First affected version."New value: +"First affected version (convenience view — see events[])."
    • changedOutput schema / properties / vulns / items / properties / affectedRanges / items / properties / lastAffected / description
      Previous value: -"Last affected version. Present when no fix exists."New value: +"Last affected version. Present when no fix exists (convenience view — see events[])."
    • changedOutput schema / properties / vulns / items / properties / affectedRanges / items / properties / packageName / description
      Previous value: -"Affected package name (may differ from queried name for umbrella advisories)."New value: +"Affected package name (may differ from queried name for umbrella advisories). Empty for source-only advisory ranges."
    • addedOutput schema / properties / vulns / items / properties / affectedRanges / items / properties / repo
      Added value: +{
      +  "description": "Source repository URL for GIT ranges. Absent on version ranges.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / vulns / items / properties / affectedRanges / items / properties / versions
      Added value: +{
      +  "description": "Explicit affected versions listed on this package entry. Absent or empty when affected versions are expressed only as ranges.",
      +  "items": {
      +    "description": "An explicitly-listed affected version.",
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "vulns",
      -  "queryMeta"
      -]New value: +[
      +  "vulns",
      +  "truncated",
      +  "queryMeta"
      +]
  6. Changed2 schema fields changed
    • addedOutput schema / properties / effectiveQuery
      Added value: +{
      +  "description": "The package@version (ecosystem) tuple as queried, echoed for content-only clients.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / notice
      Added value: +{
      +  "description": "Present on the clean path — confirms no known vulnerabilities for the queried package.",
      +  "type": "string"
      +}
  7. Added

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds useful behavioral detail: ecosystem matching is case-sensitive exact, invalid values produce an error, and returned advisories include severity, aliases, affected ranges, and fixed versions. 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.

Conciseness5/5

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

Three sentences, front-loaded with the core action, followed by return contents and a usage prerequisite. Every sentence contributes necessary information with no filler or repetition of schema details.

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

Completeness5/5

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

The output schema already handles return structure, so the description only needs to cover invocation scope, the ecosystem validation prerequisite, and the failure mode. All of that is present, making the definition complete for correct single-package query usage.

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

Parameters3/5

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

Schema description coverage is 100%, with each parameter already documented with examples and case-sensitivity notes. The description reinforces the exact-version requirement and adds the invalid-ecosystem error behavior, but it does not meaningfully expand on what the schema already provides, so the baseline of 3 is appropriate.

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

Purpose5/5

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: 'Query known vulnerabilities for a single package version.' It also lists concrete return contents (severity, CVEs, affected ranges, fixed versions) and the 'single package version' scope distinguishes it from the sibling 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.

Usage Guidelines4/5

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

The description explicitly tells the agent to use osv_list_ecosystems to validate the ecosystem string before querying, and warns that invalid values error rather than return empty. It does not explicitly state when to prefer osv_get_vulnerability or osv_query_batch, so exclusions are absent, but the intended 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.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.