Skip to main content
Glama

Osv Query Package

osv_query_package
Read-onlyIdempotent

Query known vulnerabilities for a single package version using {name, ecosystem, version} or {purl, version?}; supply exactly one embedded or separate version. 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. For overflow, repeat the original input 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. Set page.advisoryId to an announced ID to fetch its fields with fixes and severity for the queried package; retain advisoryId on subsequent pages. Pages are fresh lookups; restart a changed node without a revision. Transmission overflow and upstream truncated are separate; neither confirms clean.

Input Schema

NameRequiredDescriptionDefault
nameNoExact package name in its ecosystem.
pageNoRepeat the original input with page: overflow.page first; later select path, offset: page.nextOffset and revision: page.revision. Retain advisoryId when set.
purlNoPURL alternative to name and ecosystem; supply one embedded or separate version.
versionNoExact package version, never a range.
ecosystemNoCase-sensitive ecosystem identifier from osv_list_ecosystems.

Output Schema

NameRequiredDescriptionDefault
pageNoOne bounded page of an addressed normalized node.
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.
previewNoCompact view; overflow identifies omissions. This is not the complete record.
overflowNoTransmission overflow disclosure; independent of upstream truncation.
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. Changed18 schema fields changed
    • changedInput schema / properties / ecosystem / description
      Previous value: -"Ecosystem identifier. Must be an exact match (case-sensitive). Use osv_list_ecosystems to see valid values. Examples: \"npm\", \"PyPI\", \"crates.io\", \"Go\", \"Maven\", \"NuGet\"."New value: +"Case-sensitive ecosystem identifier from osv_list_ecosystems."
    • changedInput schema / properties / name / description
      Previous value: -"Package name as it appears in the ecosystem (e.g. \"express\", \"requests\", \"serde\"). Case-sensitive."New value: +"Exact package name in its ecosystem."
    • changedInput schema / properties / page / description
      Previous value: -"Retrieve an announced field or advisory with the original package tuple."New value: +"Repeat the original input with page: overflow.page first; later select path, offset: page.nextOffset and revision: page.revision. Retain advisoryId when set."
    • changedInput schema / properties / page / properties / advisoryId / description
      Previous value: -"ID announced in this package advisory list; one GET with package-scoped normalization."New value: +"ID from this query’s advisory list. Retain this ID when continuing its fields with fixes and severity for the original package."
    • 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."
    • addedInput schema / properties / purl
      Added value: +{
      +  "description": "PURL alternative to name and ecosystem; supply one embedded or separate version.",
      +  "type": "string"
      +}
    • changedInput schema / properties / version / description
      Previous value: -"Package version to check (e.g. \"4.17.1\", \"3.1.4\", \"1.0.0\"). Must be an exact version string, not a range."New value: +"Exact package version, never a range."
    • removedInput schema / required
      Removed value: -[
      -  "name",
      -  "ecosystem",
      -  "version"
      -]
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous 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 changed after its revision was announced. `advisory_not_found`: The selected advisory no longer exists. `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."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_purl`: The PURL is malformed. `unsupported_purl`: OSV does not support this PURL type or namespace. `invalid_purl_version`: Both or neither version sources were supplied. `invalid_purl_query`: OSV rejected the PURL query. `invalid_page_path`: The pointer is unknown or cannot fit a bounded page. `stale_page_revision`: The re-fetched node changed after its revision was announced. `advisory_not_found`: The selected advisory no longer exists. `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."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "invalid_page_path",
      -  "stale_page_revision",
      -  "advisory_not_found",
      -  "invalid_ecosystem"
      -]New value: +[
      +  "invalid_purl",
      +  "unsupported_purl",
      +  "invalid_purl_version",
      +  "invalid_purl_query",
      +  "invalid_page_path",
      +  "stale_page_revision",
      +  "advisory_not_found",
      +  "invalid_ecosystem"
      +]
    • 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 / queryMeta / properties / purl
      Added value: +{
      +  "description": "Original PURL when used instead of the package tuple.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / vulns / items / properties / aliases / description
      Previous value: -"Alternative IDs — typically CVE IDs (e.g. [\"CVE-2020-28500\"]). Accepted by nist-nvd-mcp-server for CVSS scores, EPSS, and CISA KEV status."New value: +"Alternative IDs — typically CVE IDs (e.g. [\"CVE-2020-28500\"]). 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 an announced field or advisory with the original package tuple.",
      +  "properties": {
      +    "advisoryId": {
      +      "description": "ID announced in this package advisory list; one GET with package-scoped normalization.",
      +      "maxLength": 1024,
      +      "type": "string"
      +    },
      +    "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": [
      -      "vulns",
      -      "truncated",
      -      "queryMeta"
      -    ]
      -  },
      -  {
      -    "required": [
      -      "error"
      -    ]
      -  }
      -]New value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    }
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"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."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 changed after its revision was announced. `advisory_not_found`: The selected advisory no longer exists. `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."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "invalid_ecosystem"
      -]New value: +[
      +  "invalid_page_path",
      +  "stale_page_revision",
      +  "advisory_not_found",
      +  "invalid_ecosystem"
      +]
    • 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. 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"
      +]
  4. 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"
      +]
  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": [
      +      "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"
      -]
  6. 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"
  7. 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"
      +]
  8. 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"
      +}
  9. Added

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only declare readOnly/idempotent/closed-world safety; the description adds the transactional behavior an agent actually needs: case-sensitive exact-match ecosystems that error rather than return empty, page-freshness and stale-revision restart rules, the instruction not to feed the output page object back as input, and the warning that transmission overflow and upstream truncation are distinct and neither implies a clean result.

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?

Purpose is front-loaded and every sentence carries protocol detail, but the pagination/offset/revision instructions are partly duplicated between the description and the nested page object's schema description, making it longer than strictly necessary.

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?

Given a nested page object and an output schema, the description supplies everything an agent needs to drive the lookup end to end: ecosystem validation, version uniqueness, overflow entry point, offset/revision continuation, deferred child retrieval, and advisoryId-based follow-up. Return fields (CVSS, aliases, ranges, fixes) are summarized where the output schema does the rest.

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, but the description adds a constraint the schema does not encode (no oneOf/required list exists): exactly one of {name, ecosystem} or purl must be supplied, with exactly one embedded or separate version. It also clarifies advisoryId retention and the offset-zero/no-revision rule for deferred paths, which goes beyond the field-level text.

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 known vulnerabilities for a single package version') plus the exact input shapes accepted ({name, ecosystem, version} or {purl, version?}). The scoping word 'single' distinguishes it from the batch and commit siblings without needing their schemas.

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?

Explicitly routes the agent to osv_list_ecosystems before querying and explains the consequence of skipping it (error, not empty results). It also details the overflow/deferred-page continuation protocol, but never names osv_query_batch, osv_query_commit, or osv_get_vulnerability as alternatives for other scopes, so the when-not is left implicit.

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.