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

Given a batch of vulnerability findings already flagged elsewhere (e.g. from batch_query_vulnerabilities, analyze_transitive_dependencies, or query_vulnerabilities across a whole package.json/lockfile audit), ranks them by what to actually fix first. Combines CISA KEV status (confirmed active exploitation in the wild — an automatic top-priority override), FIRST.org EPSS (probability of exploitation in the next 30 days — the primary ranking signal, since it measures likelihood rather than just impact), and severity (a secondary/fallback signal, most useful for a GHSA finding with no CVE alias) into one composite score and a remove-now/patch-now/patch-soon/scheduled/monitor tier per finding. A finding with findingType: "malware" (or a MAL-* advisoryId, auto-detected even when findingType is omitted) always lands in remove-now — the tier above patch-now — regardless of score: a confirmed-malicious package needs removal/replacement, not an "urgent patch" (there often isn't a fixed version to patch TO), and EPSS/severity don't meaningfully apply to "how malicious" the way they do to a genuine vulnerability. When EPSS data isn't available at all (no CVE id, or a real CVE that just isn't in FIRST.org's database) severity becomes the sole usable signal and is scored on its own scale instead of being diluted to a ~10% sliver of the composite — a bare CRITICAL/HIGH GHSA finding with no CVE alias lands in patch-soon/scheduled, not monitor, the way it would if severity kept its normal secondary weight with nothing else to combine it with. This does NOT re-query OSV/NVD itself — pass in the severity/CVE id findings other tools already returned; it only adds KEV/EPSS enrichment (the same data get_cve returns per-CVE) and ranks the batch. A CVE id shared by multiple findings in the same call is only looked up once.

Input Schema

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

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
rankedYes
summaryYes
totalFindingsYes
uniqueCveCountYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. 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"
+]
  2. Added

TDQS

A4.9/5.0
Behavior5/5

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

The description goes far beyond the sparse annotations (readOnlyHint, openWorldHint, destructiveHint). It discloses the full ranking logic: combination of CISA KEV, EPSS, and severity; the malware override to remove-now; the fallback to severity alone when EPSS is absent; and the deduplication of shared CVE IDs. These behavioral details are exactly what an agent needs to predict side effects and edge cases.

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?

The description is long but every sentence serves a purpose: it is front-loaded with the core purpose, then details the ranking signals, edge cases, and exclusions. While it is verbose, the complexity of the tool justifies the length. It could be tightened slightly by trimming explanatory asides, but overall structure is logical and easy to parse.

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 the tool's complexity, the presence of an output schema (which covers return structure), and the rich annotations, the description is complete. It covers input expectations, all ranking scenarios, the malware special case, the EPSS fallback, and what the tool does not do. Nothing an agent needs to call it correctly is missing.

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

Parameters5/5

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

Although schema descriptions cover 100% of parameters, the description adds deeper semantic meaning by explaining how each parameter influences ranking (e.g., cveId 'enables CISA KEV + FIRST.org EPSS enrichment', findingType 'forces the remove-now tier regardless of score', severity 'used as a fallback/secondary signal'). It also explains the interaction between parameters, such as EPSS unavailability causing severity to become the sole signal, which is not evident from schema alone.

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 states a clear, specific purpose: rank a batch of vulnerability findings by fix priority. It names the input sources (batch_query_vulnerabilities, analyze_transitive_dependencies, query_vulnerabilities) and explicitly differentiates itself from siblings by stating it does NOT re-query OSV/NVD. This makes the tool's role unambiguous.

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?

It explicitly states when to use it: 'Given a batch of vulnerability findings already flagged elsewhere... ranks them by what to actually fix first.' It also clarifies what it does not do ('does NOT re-query OSV/NVD itself') and what the caller must supply ('pass in the severity/CVE id findings other tools already returned'). This gives clear operational guidance and excludes misuse cases.

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