Skip to main content
Glama

NPMScan

by com.npmscan
OverviewDiscussions(1)Admin

Rank a batch of flagged vulnerabilities by what to fix first

prioritize_remediation
Read-only

Rank vulnerability findings other tools already returned (batch_query_vulnerabilities, query_vulnerabilities, analyze_transitive_dependencies, diff_dependencies...) by what to fix first. Pass up to 200 {packageName, cveId?, severity?, advisoryId?, currentVersion?, fixedVersion?, findingType?}. Each gets a tier: remove-now / patch-now / patch-soon / scheduled / monitor.

How the tier is decided:

  • remove-now: confirmed malware — findingType: "malware", a MAL-* advisoryId, or an advisoryId whose OSV record is a malware advisory (CWE-506 or a MAL-* alias, looked up automatically). Malware is removed, not patched. Advisories that could not be looked up are listed in malwareCheckFailedAdvisoryIds.

  • patch-now: on the CISA KEV list (actively exploited), whatever the severity.

  • otherwise a score led by FIRST.org EPSS (30-day exploitation probability), with severity as a secondary signal — or the only signal when there is no EPSS data (no CVE id). An EPSS of 10% or more always ranks at least patch-soon.

The tier is a fix-ORDER across a backlog, not a severity verdict or a merge gate: a CRITICAL CVE with low EPSS can rank monitor. Never describe a monitor/scheduled finding as "low severity", and judge whether a change that INTRODUCES a vulnerability is acceptable by its severity, not this tier.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
findingsYes1-200 previously-flagged vulnerability findings to rank

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
rankedYes
summaryYes
totalFindingsYes
uniqueCveCountYes
malwareCheckFailedAdvisoryIdsYesadvisoryIds whose OSV record could not be fetched, so whether they are malware is unknown — not confirmed safe.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / findings / items / properties / advisoryId / description
      Previous value: -"GHSA/OSV advisory id, passed through unchanged for reference — a MAL-* id is auto-detected as malware even without findingType set"New value: +"GHSA/OSV advisory id — looked up on OSV.dev: a MAL-* id, or a GHSA whose record is a malware advisory (CWE-506 / MAL-* alias), is auto-detected as malware even without findingType set"
    • addedOutput schema / properties / malwareCheckFailedAdvisoryIds
      Added value: +{
+  "description": "advisoryIds whose OSV record could not be fetched, so whether they are malware is unknown — not confirmed safe.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • changedOutput schema / required
      Previous value: -[
-  "totalFindings",
-  "uniqueCveCount",
-  "summary",
-  "ranked"
-]New value: +[
+  "totalFindings",
+  "uniqueCveCount",
+  "summary",
+  "ranked",
+  "malwareCheckFailedAdvisoryIds"
+]
  2. Changed7 schema fields changed
    • changedInput schema / properties / findings / items / properties / advisoryId / description
      Previous value: -"GHSA/OSV advisory id, passed through unchanged for reference"New value: +"GHSA/OSV advisory id, passed through unchanged for reference — a MAL-* id is auto-detected as malware even without findingType set"
    • addedInput schema / properties / findings / items / properties / findingType
      Added value: +{
+  "description": "\"malware\" forces the remove-now tier regardless of score/CVE/severity — set this (or pass a MAL-* advisoryId) for a confirmed-malicious package. Omit for an ordinary vulnerability finding.",
+  "enum": [
+    "malware",
+    "vulnerability",
+    "supply-chain",
+    "install-script"
+  ],
+  "type": "string"
+}
    • addedOutput schema / properties / ranked / items / properties / findingType
      Added value: +{
+  "enum": [
+    "malware",
+    "vulnerability",
+    "supply-chain",
+    "install-script"
+  ],
+  "type": "string"
+}
    • changedOutput schema / properties / ranked / items / properties / tier / enum
      Previous value: -[
-  "patch-now",
-  "patch-soon",
-  "scheduled",
-  "monitor"
-]New value: +[
+  "remove-now",
+  "patch-now",
+  "patch-soon",
+  "scheduled",
+  "monitor"
+]
    • changedOutput schema / properties / ranked / items / required
      Previous value: -[
-  "rank",
-  "packageName",
-  "cveId",
-  "advisoryId",
-  "currentVersion",
-  "fixedVersion",
-  "severity",
-  "kev",
-  "epss",
-  "score",
-  "tier",
-  "reason",
-  "npmscanUrl",
-  "cveNpmscanUrl"
-]New value: +[
+  "rank",
+  "packageName",
+  "cveId",
+  "advisoryId",
+  "currentVersion",
+  "fixedVersion",
+  "severity",
+  "kev",
+  "epss",
+  "score",
+  "tier",
+  "findingType",
+  "reason",
+  "npmscanUrl",
+  "cveNpmscanUrl"
+]
    • addedOutput schema / properties / summary / properties / removeNow
      Added value: +{
+  "type": "number"
+}
    • changedOutput schema / properties / summary / required
      Previous value: -[
-  "patchNow",
-  "patchSoon",
-  "scheduled",
-  "monitor",
-  "kevListedCount"
-]New value: +[
+  "removeNow",
+  "patchNow",
+  "patchSoon",
+  "scheduled",
+  "monitor",
+  "kevListedCount"
+]
  3. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations cover the safety profile (readOnly, non-destructive), and the description adds substantial behavior the annotations cannot: the full tier taxonomy (remove-now/patch-now/patch-soon/scheduled/monitor), the inputs that drive each tier (KEV, EPSS ≥10%, malware detection via MAL-*/CWE-506), and a failure-mode output (malwareCheckFailedAdvisoryIds). This is unusually rich behavioral disclosure.

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 purpose, then a clearly labeled 'How the tier is decided' block, then caveats. Structure is excellent. It is somewhat long and the malware/remove-now rule is restated in both the tier bullets and the schema, but no sentence is wasted relative to the tool's complexity.

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 tool with an output schema (so return shape needn't be explained) and full schema coverage, the description supplies everything an agent needs: what it consumes, how each tier is derived, the meaning of the output tiers, and explicit guidance on how NOT to interpret them. Nothing material is missing.

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 per-field baseline would be 3. The description goes beyond the schema by explaining how fields interact with outcomes — findingType/advisorId triggering remove-now, EPSS being the primary signal and severity the fallback, and the 200-item cap. That cross-field semantic layer is real added value over the schema's per-property 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 (rank) and resource (vulnerability findings) with explicit scope: it consumes output other tools already returned, and it names those siblings (batch_query_vulnerabilities, query_vulnerabilities, etc.). An agent can tell it apart from the query tools it depends on 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 Guidelines5/5

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

Explicitly says this operates on findings 'other tools already returned' and lists them, so the agent knows not to call it for fresh scanning. It also gives a strong when-NOT-to-use caveat: the tier is a fix-order across a backlog, not a severity verdict or merge gate, with concrete misuse warnings (don't call monitor findings 'low severity').

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

All NPMScan toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources