Skip to main content
Glama

Osv Query Batch

osv_query_batch
Read-onlyIdempotent

Query vulnerabilities for multiple packages in one call — the primary tool for dependency audits, SBOM scanning, and lockfile triage. Pass up to 1000 mixed {name, ecosystem, version} tuples and {purl, version?} identifiers, with exactly one embedded or separate version per PURL. Each entry in the response corresponds positionally to the input. Each finding includes CVE aliases for chaining to nist-nvd-mcp-server for CVSS scoring. Large replies retain the complete summary. For overflow, repeat the original packages array with page: overflow.page. Continue the same path with offset: page.nextOffset and revision: page.revision until nextOffset is null. Retrieve each entries[].deferred.path separately at offset zero without a revision. Do not pass the output page object as input. /results/17 selects original input row 17, even when earlier rows failed. Pages are fresh lookups and do not recompute the initial summary; restart a changed node without a revision. Transmission overflow and upstream truncated are separate; neither confirms clean.

Input Schema

NameRequiredDescriptionDefault
pageNoRepeat the original packages array with page: overflow.page first. Continue using path, offset: page.nextOffset and revision: page.revision. /results/17/... keeps original row index 17; start deferred children without a revision.
packagesYesPackages to audit. One entry per dependency. Positional: result[i] corresponds to packages[i].

Output Schema

NameRequiredDescriptionDefault
pageNoOne bounded page of an addressed normalized node.
errorNoPresent when the call failed. Absent on success.
noticeNoPresent on all-clean or all-errors batches — the aggregate outcome for content-only clients.
previewNoCompact view; overflow identifies omissions. This is not the complete record.
resultsNoPer-package results, positionally matching the input array.
summaryNoAggregate statistics across the full batch.
overflowNoTransmission overflow disclosure; independent of upstream truncation.
effectiveQueryNoCompact scan summary (package and outcome counts), echoed on edge-case batches for content-only clients.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed14 schema fields changed
    • addedInput schema / properties / packages / items / anyOf
      Added value: +[
      +  {
      +    "description": "Exact package tuple.",
      +    "properties": {
      +      "ecosystem": {
      +        "description": "Case-sensitive ecosystem identifier from osv_list_ecosystems.",
      +        "pattern": "\\S",
      +        "type": "string"
      +      },
      +      "name": {
      +        "description": "Exact package name in its ecosystem.",
      +        "pattern": "\\S",
      +        "type": "string"
      +      },
      +      "purl": {
      +        "description": "Use purl instead of the tuple, never together with name or ecosystem.",
      +        "type": "string"
      +      },
      +      "version": {
      +        "description": "Exact package version, never a range.",
      +        "pattern": "\\S",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "name",
      +      "ecosystem",
      +      "version"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "description": "PURL alternative with exactly one version source.",
      +    "properties": {
      +      "purl": {
      +        "description": "Complete Package URL, such as pkg:pypi/jinja2@3.1.4. Supply its version either here or separately, exactly once.",
      +        "type": "string"
      +      },
      +      "version": {
      +        "description": "Exact version only when the PURL does not embed one.",
      +        "pattern": "\\S",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "purl"
      +    ],
      +    "type": "object"
      +  }
      +]
    • removedInput schema / properties / packages / items / properties
      Removed value: -{
      -  "ecosystem": {
      -    "description": "Ecosystem identifier. Case-sensitive exact match. Use osv_list_ecosystems to validate.",
      -    "pattern": "\\S",
      -    "type": "string"
      -  },
      -  "name": {
      -    "description": "Package name as it appears in the ecosystem.",
      -    "pattern": "\\S",
      -    "type": "string"
      -  },
      -  "version": {
      -    "description": "Exact version string to check.",
      -    "pattern": "\\S",
      -    "type": "string"
      -  }
      -}
    • removedInput schema / properties / packages / items / required
      Removed value: -[
      -  "name",
      -  "ecosystem",
      -  "version"
      -]
    • removedInput schema / properties / packages / items / type
      Removed value: -"object"
    • changedInput schema / properties / page / description
      Previous value: -"Retrieve original-index rows at /results or a selected /results/17/... node with the original packages array."New value: +"Repeat the original packages array with page: overflow.page first. Continue using path, offset: page.nextOffset and revision: page.revision. /results/17/... keeps original row index 17; start deferred children without a revision."
    • changedInput schema / properties / page / properties / offset / description
      Previous value: -"Entry offset, or Unicode code-point offset for text."New value: +"Start at zero; on later calls set this to the previous page.nextOffset until it is null. Text offsets count Unicode code points."
    • changedInput schema / properties / page / properties / path / description
      Previous value: -"RFC 6901 pointer into normalized output; empty string selects its root."New value: +"Field pointer announced by overflow or entries[].deferred.path; empty string selects the root. Keep the same path while following nextOffset."
    • changedInput schema / properties / page / properties / revision / description
      Previous value: -"Revision returned for this node; omit on first retrieval."New value: +"Use page.revision only when continuing the same path. Omit on the first call to any deferred child path; restart without it after stale_page_revision."
    • changedOutput schema / properties / overflow / properties / page / description
      Previous value: -"First retrieval arguments; repeat the original tool input."New value: +"Repeat the original tool input with page: overflow.page. Later select path, offset: page.nextOffset and revision: page.revision; do not pass the output page object."
    • changedOutput schema / properties / overflow / properties / page / properties / offset / description
      Previous value: -"Entry offset, or Unicode code-point offset for text."New value: +"Start at zero; on later calls set this to the previous page.nextOffset until it is null. Text offsets count Unicode code points."
    • changedOutput schema / properties / overflow / properties / page / properties / path / description
      Previous value: -"RFC 6901 pointer into normalized output; empty string selects its root."New value: +"Field pointer announced by overflow or entries[].deferred.path; empty string selects the root. Keep the same path while following nextOffset."
    • changedOutput schema / properties / overflow / properties / page / properties / revision / description
      Previous value: -"Revision returned for this node; omit on first retrieval."New value: +"Use page.revision only when continuing the same path. Omit on the first call to any deferred child path; restart without it after stale_page_revision."
    • addedOutput schema / properties / results / items / properties / purl
      Added value: +{
      +  "description": "Original PURL when supplied; name, ecosystem and version show its effective coordinate on success.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / results / items / properties / vulns / items / properties / aliases / description
      Previous value: -"CVE IDs and other aliases. Accepted by nist-nvd-mcp-server for CVSS/KEV/EPSS context."New value: +"CVE IDs and other aliases. Accepted by nist-nvd-mcp-server for CVSS scores and CISA KEV status."
  2. Changed7 schema fields changed
    • addedInput schema / properties / page
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Retrieve original-index rows at /results or a selected /results/17/... node with the original packages array.",
      +  "properties": {
      +    "offset": {
      +      "default": 0,
      +      "description": "Entry offset, or Unicode code-point offset for text.",
      +      "maximum": 9007199254740991,
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    "path": {
      +      "description": "RFC 6901 pointer into normalized output; empty string selects its root.",
      +      "maxLength": 1024,
      +      "pattern": "^(?:\\/(?:[^~]|~[01])*)?$",
      +      "type": "string"
      +    },
      +    "revision": {
      +      "description": "Revision returned for this node; omit on first retrieval.",
      +      "pattern": "^[a-f0-9]{64}$",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "path"
      +  ],
      +  "type": "object"
      +}
    • changedOutput schema / anyOf
      Previous value: -[
      -  {
      -    "not": {
      -      "required": [
      -        "error"
      -      ]
      -    },
      -    "required": [
      -      "results",
      -      "summary"
      -    ]
      -  },
      -  {
      -    "required": [
      -      "error"
      -    ]
      -  }
      -]New value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    }
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_page_path`: The pointer is unknown or cannot fit a bounded page. `stale_page_revision`: The re-fetched node or input order changed. Other values are possible when a failure originates below the handler."
    • addedOutput schema / properties / error / properties / data / properties / reason / examples
      Added value: +[
      +  "invalid_page_path",
      +  "stale_page_revision"
      +]
    • addedOutput schema / properties / overflow
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Transmission overflow disclosure; independent of upstream truncation.",
      +  "properties": {
      +    "complete": {
      +      "description": "Complete top-level fields retained in this response.",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "notice": {
      +      "description": "Transmission omission and fresh re-fetch semantics.",
      +      "type": "string"
      +    },
      +    "omitted": {
      +      "description": "Omitted values, all addressable through page.path.",
      +      "items": {
      +        "additionalProperties": false,
      +        "description": "An oversized child; parent offset advances past this descriptor.",
      +        "properties": {
      +          "path": {
      +            "description": "Exact child pointer to retrieve separately.",
      +            "type": "string"
      +          },
      +          "total": {
      +            "description": "Number of child entries or Unicode code points; one for scalars.",
      +            "type": "number"
      +          },
      +          "type": {
      +            "description": "Child value kind.",
      +            "enum": [
      +              "array",
      +              "object",
      +              "string",
      +              "scalar"
      +            ],
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "path",
      +          "type",
      +          "total"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "page": {
      +      "additionalProperties": false,
      +      "description": "First retrieval arguments; repeat the original tool input.",
      +      "properties": {
      +        "offset": {
      +          "default": 0,
      +          "description": "Entry offset, or Unicode code-point offset for text.",
      +          "maximum": 9007199254740991,
      +          "minimum": 0,
      +          "type": "integer"
      +        },
      +        "path": {
      +          "description": "RFC 6901 pointer into normalized output; empty string selects its root.",
      +          "maxLength": 1024,
      +          "pattern": "^(?:\\/(?:[^~]|~[01])*)?$",
      +          "type": "string"
      +        },
      +        "revision": {
      +          "description": "Revision returned for this node; omit on first retrieval.",
      +          "pattern": "^[a-f0-9]{64}$",
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "path",
      +        "offset"
      +      ],
      +      "type": "object"
      +    }
      +  },
      +  "required": [
      +    "complete",
      +    "omitted",
      +    "page",
      +    "notice"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / page
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "One bounded page of an addressed normalized node.",
      +  "properties": {
      +    "entries": {
      +      "description": "Source-order entries for arrays, objects and scalars.",
      +      "items": {
      +        "additionalProperties": false,
      +        "description": "One source entry, complete or deferred.",
      +        "properties": {
      +          "deferred": {
      +            "additionalProperties": false,
      +            "description": "Retrievable child descriptor when its value does not fit.",
      +            "properties": {
      +              "path": {
      +                "description": "Exact child pointer to retrieve separately.",
      +                "type": "string"
      +              },
      +              "total": {
      +                "description": "Number of child entries or Unicode code points; one for scalars.",
      +                "type": "number"
      +              },
      +              "type": {
      +                "description": "Child value kind.",
      +                "enum": [
      +                  "array",
      +                  "object",
      +                  "string",
      +                  "scalar"
      +                ],
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "path",
      +              "type",
      +              "total"
      +            ],
      +            "type": "object"
      +          },
      +          "key": {
      +            "description": "Object key or original array index.",
      +            "type": "string"
      +          },
      +          "value": {
      +            "description": "Complete child value, unmodified."
      +          }
      +        },
      +        "required": [
      +          "key"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "nextOffset": {
      +      "description": "Next offset, strictly greater or null when finished.",
      +      "type": [
      +        "number",
      +        "null"
      +      ]
      +    },
      +    "notice": {
      +      "description": "Fresh re-fetch disclosure; no saved historical snapshot.",
      +      "type": "string"
      +    },
      +    "offset": {
      +      "description": "Starting entry or code-point offset.",
      +      "type": "number"
      +    },
      +    "path": {
      +      "description": "Addressed JSON pointer.",
      +      "type": "string"
      +    },
      +    "revision": {
      +      "description": "SHA-256 revision of the addressed normalized node; batch collection uses original input order.",
      +      "type": "string"
      +    },
      +    "text": {
      +      "description": "Verbatim Unicode code-point slice for strings.",
      +      "type": "string"
      +    },
      +    "total": {
      +      "description": "Total entries or Unicode code points.",
      +      "type": "number"
      +    },
      +    "type": {
      +      "description": "Addressed value kind.",
      +      "enum": [
      +        "array",
      +        "object",
      +        "string",
      +        "scalar"
      +      ],
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "path",
      +    "type",
      +    "offset",
      +    "total",
      +    "nextOffset",
      +    "revision",
      +    "notice"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / preview
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Compact view; overflow identifies omissions. This is not the complete record.",
      +  "propertyNames": {
      +    "type": "string"
      +  },
      +  "type": "object"
      +}
  3. Changed6 schema fields changed
    • removedInput schema / properties / packages / items / properties / ecosystem / minLength
      Removed value: -1
    • removedInput schema / properties / packages / items / properties / name / minLength
      Removed value: -1
    • removedInput schema / properties / packages / items / properties / version / minLength
      Removed value: -1
    • changedOutput schema / properties / results / items / properties / vulns / items / properties / fixedVersions / description
      Previous value: -"First safe version(s) to upgrade to. Empty if no fix exists."New value: +"Every fixed version the advisory lists for this row's package, in record order — one per affected interval, typically one per release line. Excludes other packages' fixes and GIT commits. Empty when the advisory lists no fix for this package."
    • changedOutput schema / properties / results / items / properties / vulns / items / properties / fixedVersions / items / description
      Previous value: -"A first-safe version string."New value: +"A version that fixes the vulnerability for this package."
    • changedOutput schema / properties / results / items / properties / vulns / items / properties / severityLabel / description
      Previous value: -"Severity label: \"LOW\", \"MODERATE\", \"HIGH\", \"CRITICAL\", or null."New value: +"Severity label: \"LOW\", \"MODERATE\", \"HIGH\", \"CRITICAL\", or null. Same derivation as osv_query_package: database_specific.severity, then an Ubuntu priority, then the highest CVSS v3/v4 score, using this row's package-level severity entries when the record has none."
  4. Changed6 schema fields changed
    • removedOutput schema / properties / results / items / properties / error / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / results / items / properties / error / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / results / items / properties / vulns / items / properties / severityLabel / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / results / items / properties / vulns / items / properties / severityLabel / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / summary / properties / worstSeverity / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / summary / properties / worstSeverity / type
      Added value: +[
      +  "string",
      +  "null"
      +]
  5. 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": [
      +      "results",
      +      "summary"
      +    ]
      +  },
      +  {
      +    "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.",
      +          "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: -[
      -  "results",
      -  "summary"
      -]
  6. Changed6 schema fields changed
    • addedInput schema / properties / packages / items / properties / ecosystem / minLength
      Added value: +1
    • addedInput schema / properties / packages / items / properties / ecosystem / pattern
      Added value: +"\\S"
    • addedInput schema / properties / packages / items / properties / name / minLength
      Added value: +1
    • addedInput schema / properties / packages / items / properties / name / pattern
      Added value: +"\\S"
    • addedInput schema / properties / packages / items / properties / version / minLength
      Added value: +1
    • addedInput schema / properties / packages / items / properties / version / pattern
      Added value: +"\\S"
  7. Changed5 schema fields changed
    • addedOutput schema / properties / results / items / properties / truncated
      Added value: +{
      +  "description": "True when OSV paginated beyond the fetch cap for this package — its result may be INCOMPLETE. A truncated row with no vulnerabilities is NOT confirmed clean.",
      +  "type": "boolean"
      +}
    • changedOutput schema / properties / results / items / required
      Previous value: -[
      -  "name",
      -  "ecosystem",
      -  "version",
      -  "vulnerable",
      -  "error",
      -  "vulnCount",
      -  "vulns"
      -]New value: +[
      +  "name",
      +  "ecosystem",
      +  "version",
      +  "vulnerable",
      +  "truncated",
      +  "error",
      +  "vulnCount",
      +  "vulns"
      +]
    • changedOutput schema / properties / summary / properties / cleanCount / description
      Previous value: -"Packages with no vulnerabilities."New value: +"Packages confirmed clean — no vulnerabilities, no error, and not truncated."
    • addedOutput schema / properties / summary / properties / truncatedCount
      Added value: +{
      +  "description": "Packages whose OSV results were truncated (may be incomplete). A truncated package with no findings is NOT counted as clean.",
      +  "type": "number"
      +}
    • changedOutput schema / properties / summary / required
      Previous value: -[
      -  "totalPackages",
      -  "vulnerableCount",
      -  "cleanCount",
      -  "errorCount",
      -  "totalVulns",
      -  "worstSeverity"
      -]New value: +[
      +  "totalPackages",
      +  "vulnerableCount",
      +  "cleanCount",
      +  "truncatedCount",
      +  "errorCount",
      +  "totalVulns",
      +  "worstSeverity"
      +]
  8. Changed2 schema fields changed
    • addedOutput schema / properties / effectiveQuery
      Added value: +{
      +  "description": "Compact scan summary (package and outcome counts), echoed on edge-case batches for content-only clients.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / notice
      Added value: +{
      +  "description": "Present on all-clean or all-errors batches — the aggregate outcome for content-only clients.",
      +  "type": "string"
      +}
  9. Changed2 schema fields changed
    • removedInput schema / properties / canvas_id
      Removed value: -{
      -  "description": "Reuse an existing DataCanvas table token to append results. Omit to create a new canvas. Only relevant when package count >= 200.",
      -  "type": "string"
      -}
    • removedOutput schema / properties / canvas_id
      Removed value: -{
      -  "description": "DataCanvas table token. Present when the package count is >= 200 or a canvas_id was provided. Use to run SQL queries across the full result set via the canvas tools.",
      -  "type": "string"
      -}
  10. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the readOnly/idempotent annotations: documents positional result mapping, summary retention in large replies, the overflow→page→nextOffset→revision continuation protocol, deferred-path retrieval at offset zero without revision, and the caveat that overflow/truncation do not imply a clean result. These are real behavioral traits an agent cannot infer from the schema or annotations.

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

Conciseness4/5

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

Front-loaded with the purpose and the primary qualifier (1000 mixed identifiers) before paging rules, which is the right ordering. However, the tail of the description is a dense run of paging clauses that partly restate the page.path/offset/revision schema descriptions, and a few phrases ("restart a changed node without a revision") are terse to the point of ambiguity.

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?

For a high-complexity tool with nested input, 2 parameters, and an output schema, the description covers the gaps structured fields cannot: positional correspondence, per-entry failure handling via /results/N, overflow recovery, and the distinction between overflow and upstream truncation. Return-shape detail is correctly left to the output schema.

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

Parameters4/5

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 value by explaining that offset/revision continuation is tied to the same path, that a revision must be omitted on first calls to deferred children, and that output page objects must not be fed back as input. Some paging detail is duplicated from the schema rather than newly added, keeping it below 5.

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?

States a specific verb and resource ("Query vulnerabilities for multiple packages in one call") and immediately scopes it against the single-package sibling by emphasizing batch semantics and the 1000-entry limit. An agent can distinguish this from osv_query_package 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.

Usage Guidelines4/5

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

Names concrete use cases (dependency audits, SBOM scanning, lockfile triage) and prescribes when to use tuple vs PURL vs embedded version, plus a downstream chaining path to nist-nvd-mcp-server. It does not explicitly say when to prefer osv_query_package or osv_query_commit instead, so the sibling exclusion is only implied.

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.