NPMScan

Simulate an npm dependency upgrade

simulate_dependency_upgrade

Read-only

Given a package and a current/target version, tells you whether that specific upgrade is a safe patch/minor bump or a likely-breaking major bump, before you actually run npm install. Natural follow-up to prioritize_remediation: pass its packageName + currentVersion + fixedVersion straight in to check whether the suggested fix is a drop-in patch or something that needs a review pass. Classifies the jump by semver (major/minor/patch/prerelease), treats a minor bump between two pre-1.0 (0.x) versions as breaking-risk per semver's own "the API isn't stable yet" convention, and flags skipping over multiple major versions in one jump (e.g. 2.x -> 5.x) as needing a per-major changelog review rather than just a diff against the final target. Beyond semver, it also checks the registry for real signals the version number alone won't tell you: whether the target version is marked deprecated, whether it introduces a preinstall/install/postinstall/prepare lifecycle script the current version didn't have, whether it tightens its engines.node requirement, and whether it is itself a prerelease. Finally it batch-checks both versions against OSV.dev and reports vulnerabilityDelta (introduced/fixed/still-vulnerable/still-clean) — catching the case where a suggested "fix" version doesn't actually clear every open CVE. Combines all of this into one riskTier (safe/low-risk/review-recommended/breaking-change-likely/unknown) with a reasons list explaining exactly which signals drove it. This does NOT read the package's changelog/release notes or scan the target tarball's source diff for actual breaking API usage — it's a fast, deterministic pre-check, not a substitute for reading the release notes on a flagged major bump. For simulating more than one upgrade at once — e.g. every "patch-now" finding prioritize_remediation just ranked — pass packages: [{packageName, currentVersion, targetVersion?}, ...] (1-100 items) instead of packageName/currentVersion/targetVersion, not both. Registry fetches are deduped/parallelized and all OSV checks for the whole batch run as one call, so this is not the same cost as N single-item calls. A package that can't be resolved at all (typo, unpublished, registry error) shows up as its own results entry with fetchError set instead of failing the whole batch.

Input Schema

TableJSON Schema

Name	Required	Description
`packages`	No	Batch of upgrades to simulate (1-100 items), each mirroring the single-item packageName/currentVersion/targetVersion fields. Use this OR packageName/currentVersion, not both. Natural pairing with prioritize_remediation: pass its ranked findings straight in as one call instead of one simulate_dependency_upgrade call per finding.
`packageName`	No	Exact npm package name, e.g. "lodash" or "@scope/name". Use this (with currentVersion) OR `packages`, not both.
`targetVersion`	No	Version to simulate upgrading to — exact version, range, or dist-tag (e.g. the fixedVersion a prioritize_remediation finding named). Omit to use the registry's "latest" dist-tag. Only applies to the single-item `packageName` form.
`currentVersion`	No	Currently installed version — an exact version (e.g. "4.17.20"), a semver range (e.g. "^4.17.0"), or a dist-tag. Required when `packageName` is used.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`reasons`	No
`results`	No
`verdict`	No
`riskTier`	No
`direction`	No
`npmscanUrl`	No
`semverBump`	No
`packageName`	No
`batchSummary`	No
`engineChange`	No
`zeroMajorNote`	No
`targetDeprecated`	No
`targetVersionNote`	No
`currentVersionNote`	No
`isBreakingBySemver`	No
`targetIsPrerelease`	No
`targetIsVulnerable`	No
`vulnerabilityDelta`	No
`currentIsVulnerable`	No
`majorVersionsSkipped`	No
`resolvedTargetVersion`	No
`targetVulnerabilities`	No
`requestedTargetVersion`	No
`resolvedCurrentVersion`	No
`installScriptIntroduced`	No
`requestedCurrentVersion`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedSep 4, 2026

changedInput schema / properties / currentVersion / description

Previous value: -"Currently installed version — an exact version (e.g. \"4.17.20\"), a semver range (e.g. \"^4.17.0\"), or a dist-tag"New value: +"Currently installed version — an exact version (e.g. \"4.17.20\"), a semver range (e.g. \"^4.17.0\"), or a dist-tag. Required when `packageName` is used."

changedInput schema / properties / packageName / description

Previous value: -"Exact npm package name, e.g. \"lodash\" or \"@scope/name\""New value: +"Exact npm package name, e.g. \"lodash\" or \"@scope/name\". Use this (with currentVersion) OR `packages`, not both."

addedInput schema / properties / packages

Added value: +{
+  "description": "Batch of upgrades to simulate (1-100 items), each mirroring the single-item packageName/currentVersion/targetVersion fields. Use this OR packageName/currentVersion, not both. Natural pairing with prioritize_remediation: pass its ranked findings straight in as one call instead of one simulate_dependency_upgrade call per finding.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "currentVersion": {
+        "description": "Currently installed version — an exact version, a semver range, or a dist-tag",
+        "maxLength": 128,
+        "minLength": 1,
+        "type": "string"
+      },
+      "packageName": {
+        "description": "Exact npm package name, e.g. \"lodash\" or \"@scope/name\"",
+        "maxLength": 214,
+        "minLength": 1,
+        "type": "string"
+      },
+      "targetVersion": {
+        "description": "Version to simulate upgrading to — exact version, range, or dist-tag. Omit to use the registry's \"latest\" dist-tag.",
+        "maxLength": 128,
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "packageName",
+      "currentVersion"
+    ],
+    "type": "object"
+  },
+  "maxItems": 100,
+  "minItems": 1,
+  "type": "array"
+}

changedInput schema / properties / targetVersion / description

Previous value: -"Version to simulate upgrading to — exact version, range, or dist-tag (e.g. the fixedVersion a prioritize_remediation finding named). Omit to use the registry's \"latest\" dist-tag."New value: +"Version to simulate upgrading to — exact version, range, or dist-tag (e.g. the fixedVersion a prioritize_remediation finding named). Omit to use the registry's \"latest\" dist-tag. Only applies to the single-item `packageName` form."

removedInput schema / required

Removed value: -[
-  "packageName",
-  "currentVersion"
-]

addedOutput schema / properties / batchSummary

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "fetchFailedCount": {
+      "type": "number"
+    },
+    "riskTierCounts": {
+      "additionalProperties": false,
+      "properties": {
+        "breakingChangeLikely": {
+          "type": "number"
+        },
+        "lowRisk": {
+          "type": "number"
+        },
+        "reviewRecommended": {
+          "type": "number"
+        },
+        "safe": {
+          "type": "number"
+        },
+        "unknown": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "safe",
+        "lowRisk",
+        "reviewRecommended",
+        "breakingChangeLikely",
+        "unknown"
+      ],
+      "type": "object"
+    },
+    "totalRequested": {
+      "type": "number"
+    },
+    "vulnQueryFailedCount": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "totalRequested",
+    "fetchFailedCount",
+    "riskTierCounts",
+    "vulnQueryFailedCount"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / results

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "currentIsVulnerable": {
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "currentVersionNote": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "direction": {
+        "enum": [
+          "upgrade",
+          "downgrade",
+          "same",
+          "unresolved"
+        ],
+        "type": "string"
+      },
+      "engineChange": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "after": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "before": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "tightened": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "before",
+              "after",
+              "tightened"
+            ],
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "fetchError": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "installScriptIntroduced": {
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "isBreakingBySemver": {
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "majorVersionsSkipped": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "npmscanUrl": {
+        "type": "string"
+      },
+      "packageName": {
+        "type": "string"
+      },
+      "reasons": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "requestedCurrentVersion": {
+        "type": "string"
+      },
+      "requestedTargetVersion": {
+        "type": "string"
+      },
+      "resolvedCurrentVersion": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "resolvedTargetVersion": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "riskTier": {
+        "enum": [
+          "safe",
+          "low-risk",
+          "review-recommended",
+          "breaking-change-likely",
+          "unknown"
+        ],
+        "type": "string"
+      },
+      "semverBump": {
+        "anyOf": [
+          {
+            "enum": [
+              "major",
+              "premajor",
+              "minor",
+              "preminor",
+              "patch",
+              "prepatch",
+              "prerelease"
+            ],
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "targetDeprecated": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "targetIsPrerelease": {
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "targetIsVulnerable": {
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "targetVersionNote": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "targetVulnerabilities": {
+        "items": {
+          "$ref": "#/properties/targetVulnerabilities/items"
+        },
+        "type": "array"
+      },
+      "verdict": {
+        "type": "string"
+      },
+      "vulnerabilityDelta": {
+        "anyOf": [
+          {
+            "enum": [
+              "introduced",
+              "fixed",
+              "still-vulnerable",
+              "still-clean",
+              "unknown"
+            ],
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "zeroMajorNote": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "required": [
+      "packageName",
+      "npmscanUrl",
+      "requestedCurrentVersion",
+      "requestedTargetVersion",
+      "resolvedCurrentVersion",
+      "resolvedTargetVersion",
+      "currentVersionNote",
+      "targetVersionNote",
+      "direction",
+      "semverBump",
+      "isBreakingBySemver",
+      "majorVersionsSkipped",
+      "zeroMajorNote",
+      "targetIsPrerelease",
+      "targetDeprecated",
+      "installScriptIntroduced",
+      "engineChange",
+      "currentIsVulnerable",
+      "targetIsVulnerable",
+      "vulnerabilityDelta",
+      "targetVulnerabilities",
+      "riskTier",
+      "reasons",
+      "verdict",
+      "fetchError"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

removedOutput schema / required

Removed value: -[
-  "packageName",
-  "npmscanUrl",
-  "requestedCurrentVersion",
-  "requestedTargetVersion",
-  "resolvedCurrentVersion",
-  "resolvedTargetVersion",
-  "currentVersionNote",
-  "targetVersionNote",
-  "direction",
-  "semverBump",
-  "isBreakingBySemver",
-  "majorVersionsSkipped",
-  "zeroMajorNote",
-  "targetIsPrerelease",
-  "targetDeprecated",
-  "installScriptIntroduced",
-  "engineChange",
-  "currentIsVulnerable",
-  "targetIsVulnerable",
-  "vulnerabilityDelta",
-  "targetVulnerabilities",
-  "riskTier",
-  "reasons",
-  "verdict"
-]

AddedSep 3, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations declare readOnlyHint=true / destructiveHint=false / openWorldHint=true, and the description still adds substantial behavioral detail beyond them: the riskTier taxonomy, the reasons list, pre-1.0 minor-bump-as-breaking convention, multi-major skip flagging, registry-sourced signals (deprecation, new lifecycle scripts, engines.node tightening), and the fetchError-per-entry failure isolation. It also states the batch cost characteristic (deduped/parallelized fetches, one OSV call) that no annotation conveys.

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 core promise ('tells you whether that specific upgrade is safe ... before you run npm install') and every sentence carries signal. It is dense and long, and the batch/param guidance repeats what the schema already documents, so some trimming is possible, but the length is justified by 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 complex, zero-required-param, batch-capable tool with an output schema, the description covers the classification logic, the riskTier output, the per-entry fetchError behavior, and the cost model without needing to restate return fields. An agent has everything required to select and invoke it correctly, including the choosing between single and batch forms.

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 and the description must add value to earn more. It does: it spells out the mutual exclusivity of packages vs packageName/currentVersion ('not both'), clarifies that targetVersion is optional and defaults to the registry latest dist-tag, and links the fields to prioritize_remediation's output shape. This largely mirrors schema text, so it lands at 4 rather than 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 precise verb+resource (simulate a dependency upgrade) and goes further to enumerate exactly what it classifies (semver jump type, deprecation, lifecycle scripts, engines.node, prerelease, OSV vulnerabilityDelta) and what it explicitly does NOT do (read changelog/source diff). It distinguishes itself from siblings both by naming prioritize_remediation as the upstream pairing and by defining its boundary as a fast deterministic pre-check rather than a full review.

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?

Gives explicit when-to-use ('before you actually run npm install', 'natural follow-up to prioritize_remediation: pass its packageName + currentVersion + fixedVersion straight in') and when-not-to-use ('not a substitute for reading the release notes on a flagged major bump'). It also routes the batch case explicitly ('for simulating more than one upgrade at once ... pass packages ... not both'), which is exactly the discrimination an agent needs.

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

All NPMScan tools Inspect

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

Need Help?