Skip to main content
Glama

Evaluate an exact dependency change in project context

evaluate_dependency_change
Read-onlyIdempotent

CALL immediately before adding or upgrading an npm dependency. Answers "is this exact version safe to take on" from registry metadata, advisory deltas, provenance, license, and repository evidence, and returns blockers, warnings, a recommendation, and a verification plan. Example: {"dependency":"lodash","to_version":"4.17.21"} — every field is top-level, never nested under a "change" key. Only dependency is required — omit to_version to evaluate the latest published version, exactly as npm install <pkg> would. to_version also accepts a dist-tag ("latest") or a SemVer range ("^4.17.0"); it resolves to one exact version, reported back in change.to_version. Everything RepoPilot can infer is inferred, and every default, repair, and resolution is listed in input_adjustments. Evaluates only; never installs or edits anything.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
intentNoOptional free text describing why you are making this change. Advisory only; it changes no verdict.
projectNoOptional, source-free facts about the project you are changing. Supplying it adds Node/peer/license compatibility and a command-level verification plan. Omit it entirely and compatibility comes back "unknown" - read that as not checked, never as no problem found. Every field is optional; anything missing is defaulted and reported in input_adjustments, never rejected. Never send source code.
dependencyYesA STRING: the npm package name on its own, with no version and no surrounding object — "lodash", "@types/node". Not {"name":...}, not {"lodash":"^4.17.0"}, not a list, and never wrapped in a top-level {"change":{...}} object — every field here is top-level. The version goes in to_version, the currently installed one in from_version.
to_versionNoThe version you intend to install — an exact version ("4.18.1"), a dist-tag ("latest"), or a SemVer range ("^4.17.0"). A quoted string is preferred; a bare JSON number ("to_version": 19) is also accepted and read as the string "19". Omit to evaluate the latest published version.
from_versionNoThe version currently installed, or omitted when adding a new dependency. A bare JSON number is accepted the same way as to_version. Supplying it produces a before/after advisory comparison.
policy_profileNoNamed team dependency policy. Strict requires provenance and denies package install hooks. Must be spelled exactly — a near-miss spelling is rejected rather than guessed, because reading it wrong would answer under a policy you did not ask for.balanced
dependency_typeNoWhere the dependency goes, in THESE words: "runtime" for a dependencies entry, "development" for devDependencies. The manifest and CLI spellings ("dev", "devDependencies", "--save-dev", "prod") are mapped onto these and reported in input_adjustments.runtime
package_managerNoOptional. Only affects the commands and lockfile named in the verification plan. Inferred from project.lockfile_path when you send a project snapshot, and assumed to be npm otherwise.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
toolYes
agentYes
statusYes
schema_versionYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / project / properties / dependency_usage / description
      Previous value: -"Optional local call shapes for this dependency under native Node with default conditions. No source, paths, local names or call arguments. Coverage is always partial; transpiled/bundled code is unsupported."New value: +"Optional local call shapes for this dependency under native Node with default conditions. No source, paths, local names or call arguments. Coverage is always partial; transpiled CommonJS output is read, bundles are unsupported. instance_member names a method called on an instance of the export."
    • addedInput schema / properties / project / properties / dependency_usage / properties / uses / items / properties / instance_member
      Added value: +{
      +  "maxLength": 100,
      +  "pattern": "^[A-Za-z_$][A-Za-z0-9_$]*$",
      +  "type": "string"
      +}
  2. Changed1 schema field changed
    • addedInput schema / properties / project / properties / dependency_usage
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Optional local call shapes for this dependency under native Node with default conditions. No source, paths, local names or call arguments. Coverage is always partial; transpiled/bundled code is unsupported.",
      +  "properties": {
      +    "coverage": {
      +      "const": "partial",
      +      "type": "string"
      +    },
      +    "runtime": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "arch": {
      +          "maxLength": 32,
      +          "pattern": "^[a-z0-9_]+$",
      +          "type": "string"
      +        },
      +        "node": {
      +          "maxLength": 32,
      +          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
      +          "type": "string"
      +        },
      +        "platform": {
      +          "maxLength": 32,
      +          "pattern": "^[a-z0-9_]+$",
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "node",
      +        "platform",
      +        "arch"
      +      ],
      +      "type": "object"
      +    },
      +    "schema_version": {
      +      "const": 1,
      +      "type": "integer"
      +    },
      +    "uses": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "export_path": {
      +            "items": {
      +              "maxLength": 100,
      +              "pattern": "^[A-Za-z_$][A-Za-z0-9_$]*$",
      +              "type": "string"
      +            },
      +            "maxItems": 2,
      +            "type": "array"
      +          },
      +          "loader": {
      +            "enum": [
      +              "require",
      +              "import"
      +            ],
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "loader",
      +          "export_path"
      +        ],
      +        "type": "object"
      +      },
      +      "maxItems": 50,
      +      "type": "array"
      +    }
      +  },
      +  "required": [
      +    "schema_version",
      +    "runtime",
      +    "coverage",
      +    "uses"
      +  ],
      +  "type": "object"
      +}
  3. Changed5 schema fields changed
    • changedInput schema / properties / dependency / description
      Previous value: -"A STRING: the npm package name on its own, with no version and no surrounding object — \"lodash\", \"@types/node\". Not {\"name\":...}, not {\"lodash\":\"^4.17.0\"}, not a list. The version goes in to_version, the currently installed one in from_version."New value: +"A STRING: the npm package name on its own, with no version and no surrounding object — \"lodash\", \"@types/node\". Not {\"name\":...}, not {\"lodash\":\"^4.17.0\"}, not a list, and never wrapped in a top-level {\"change\":{...}} object — every field here is top-level. The version goes in to_version, the currently installed one in from_version."
    • changedInput schema / properties / from_version / description
      Previous value: -"The version currently installed, or omitted when adding a new dependency. Supplying it produces a before/after advisory comparison."New value: +"The version currently installed, or omitted when adding a new dependency. A bare JSON number is accepted the same way as to_version. Supplying it produces a before/after advisory comparison."
    • changedInput schema / properties / from_version / type
      Previous value: -[
      -  "string",
      -  "null"
      -]New value: +[
      +  "string",
      +  "number",
      +  "null"
      +]
    • changedInput schema / properties / to_version / description
      Previous value: -"A STRING: the version you intend to install — an exact version (\"4.18.1\"), a dist-tag (\"latest\"), or a SemVer range (\"^4.17.0\"). Quote it even when it looks numeric (\"19\", not 19). Omit to evaluate the latest published version."New value: +"The version you intend to install — an exact version (\"4.18.1\"), a dist-tag (\"latest\"), or a SemVer range (\"^4.17.0\"). A quoted string is preferred; a bare JSON number (\"to_version\": 19) is also accepted and read as the string \"19\". Omit to evaluate the latest published version."
    • changedInput schema / properties / to_version / type
      Previous value: -"string"New value: +[
      +  "string",
      +  "number"
      +]
  4. Changed3 schema fields changed
    • changedInput schema / properties / dependency / description
      Previous value: -"The npm package name on its own, with no version — \"lodash\", \"@types/node\"."New value: +"A STRING: the npm package name on its own, with no version and no surrounding object — \"lodash\", \"@types/node\". Not {\"name\":...}, not {\"lodash\":\"^4.17.0\"}, not a list. The version goes in to_version, the currently installed one in from_version."
    • changedInput schema / properties / dependency_type / description
      Previous value: -"Where the dependency goes. Defaults to runtime."New value: +"Where the dependency goes, in THESE words: \"runtime\" for a dependencies entry, \"development\" for devDependencies. The manifest and CLI spellings (\"dev\", \"devDependencies\", \"--save-dev\", \"prod\") are mapped onto these and reported in input_adjustments."
    • changedInput schema / properties / to_version / description
      Previous value: -"The version you intend to install: an exact version (\"4.18.1\"), a dist-tag (\"latest\"), or a SemVer range (\"^4.17.0\"). Omit to evaluate the latest published version."New value: +"A STRING: the version you intend to install — an exact version (\"4.18.1\"), a dist-tag (\"latest\"), or a SemVer range (\"^4.17.0\"). Quote it even when it looks numeric (\"19\", not 19). Omit to evaluate the latest published version."
  5. Changed14 schema fields changed
    • changedInput schema / additionalProperties
      Previous value: -trueNew value: +false
    • changedInput schema / examples
      Previous value: -[
      -  {
      -    "change": {
      -      "name": "lodash",
      -      "to_version": "latest"
      -    }
      -  },
      -  {
      -    "change": {
      -      "from_version": "4.18.2",
      -      "name": "express",
      -      "to_version": "^5.0.0"
      -    }
      -  },
      -  {
      -    "change": {
      -      "dependency_type": "runtime",
      -      "name": "zod",
      -      "to_version": "3.23.8"
      -    },
      -    "policy_profile": "strict",
      -    "project": {
      -      "direct_dependencies": {
      -        "zod": "^3.22.0"
      -      },
      -      "installed_versions": {
      -        "zod": "3.22.4"
      -      },
      -      "node_version": "20.11.0",
      -      "package_manager": "pnpm",
      -      "scripts": [
      -        "build",
      -        "test"
      -      ]
      -    }
      -  }
      -]New value: +[
      +  {
      +    "dependency": "lodash",
      +    "to_version": "4.17.21"
      +  },
      +  {
      +    "dependency": "express",
      +    "from_version": "4.18.2",
      +    "to_version": "^5.0.0"
      +  },
      +  {
      +    "dependency": "zod",
      +    "policy_profile": "strict",
      +    "project": {
      +      "direct_dependencies": {
      +        "zod": "^3.22.0"
      +      },
      +      "installed_versions": {
      +        "zod": "3.22.4"
      +      },
      +      "node_version": "20.11.0",
      +      "package_manager": "pnpm",
      +      "scripts": [
      +        "build",
      +        "test"
      +      ]
      +    },
      +    "to_version": "3.23.8"
      +  }
      +]
    • removedInput schema / properties / change
      Removed value: -{
      -  "additionalProperties": true,
      -  "description": "The single dependency you are about to add or upgrade. One dependency per call.",
      -  "properties": {
      -    "dependency_type": {
      -      "default": "runtime",
      -      "description": "Where the dependency goes. Defaults to runtime.",
      -      "enum": [
      -        "runtime",
      -        "development",
      -        "optional",
      -        "peer"
      -      ],
      -      "type": "string"
      -    },
      -    "ecosystem": {
      -      "const": "npm",
      -      "default": "npm",
      -      "description": "Always npm. Omit it.",
      -      "type": "string"
      -    },
      -    "from_version": {
      -      "description": "The version currently installed, or null / omitted when adding a new dependency. Supplying it is what produces a before/after advisory comparison. Alias keys \"current_version\", \"old_version\", \"previous_version\", and \"installed_version\" are adopted onto it.",
      -      "maxLength": 128,
      -      "type": [
      -        "string",
      -        "null"
      -      ]
      -    },
      -    "name": {
      -      "description": "The npm package name on its own — \"lodash\", \"@types/node\". Do NOT append a version here; a \"name@version\" spec is split for you and reported in input_adjustments. Alias keys \"package\", \"package_name\", \"pkg\", \"dep\", \"dependency\", \"dependency_name\", \"module\", \"library\", \"npm_package\", \"npm_package_name\", \"package_spec\", and \"dependency_spec\" are adopted onto it, as is any case or separator variant of \"name\".",
      -      "maxLength": 214,
      -      "minLength": 1,
      -      "type": "string"
      -    },
      -    "to_version": {
      -      "description": "The version you intend to install: an exact version (\"4.18.1\"), a dist-tag (\"latest\"), or a SemVer range (\"^4.17.0\", \"~1.2\", \"4.x\"). Omit it entirely to evaluate the latest published version, which is what plain `npm install <pkg>` would give you. Ranges and tags resolve to one exact version — read change.to_version in the response for the version the verdict actually covers. Alias keys \"version\", \"target_version\", \"new_version\", \"desired_version\", and \"requested_version\" are adopted onto it.",
      -      "maxLength": 128,
      -      "minLength": 1,
      -      "type": "string"
      -    }
      -  },
      -  "required": [
      -    "name"
      -  ],
      -  "type": "object"
      -}
    • addedInput schema / properties / dependency
      Added value: +{
      +  "description": "The npm package name on its own, with no version — \"lodash\", \"@types/node\".",
      +  "maxLength": 214,
      +  "minLength": 1,
      +  "pattern": "^(@[^/\\s]+/)?[^@/\\s][^/\\s]*$",
      +  "type": "string"
      +}
    • addedInput schema / properties / dependency_type
      Added value: +{
      +  "default": "runtime",
      +  "description": "Where the dependency goes. Defaults to runtime.",
      +  "enum": [
      +    "runtime",
      +    "development",
      +    "optional",
      +    "peer"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / from_version
      Added value: +{
      +  "description": "The version currently installed, or omitted when adding a new dependency. Supplying it produces a before/after advisory comparison.",
      +  "maxLength": 128,
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • changedInput schema / properties / intent / description
      Previous value: -"Optional free text describing why you are making this change. Advisory only; it changes no verdict. Note this is a plain string here — plan_repo_task takes an object under the same name."New value: +"Optional free text describing why you are making this change. Advisory only; it changes no verdict."
    • addedInput schema / properties / package_manager
      Added value: +{
      +  "description": "Optional. Only affects the commands and lockfile named in the verification plan. Inferred from project.lockfile_path when you send a project snapshot, and assumed to be npm otherwise.",
      +  "enum": [
      +    "npm",
      +    "pnpm",
      +    "yarn",
      +    "bun"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / properties / policy_profile / description
      Previous value: -"Named team dependency policy. Strict requires provenance and denies package install hooks. This is the one key that must be spelled exactly — a near-miss spelling is rejected rather than guessed, because reading it wrong would answer under a policy you did not ask for."New value: +"Named team dependency policy. Strict requires provenance and denies package install hooks. Must be spelled exactly — a near-miss spelling is rejected rather than guessed, because reading it wrong would answer under a policy you did not ask for."
    • changedInput schema / properties / project / additionalProperties
      Previous value: -trueNew value: +false
    • changedInput schema / properties / project / description
      Previous value: -"Optional, source-free facts about the project you are changing. Supplying it adds Node/peer/license compatibility and a command-level verification plan. Omit it entirely and compatibility comes back \"unknown\" — read that as not checked, never as no problem found. If you DO send it, package_manager is the one field you must include: it selects the lockfile and the commands in the verification plan, so guessing it would hand you instructions for the wrong repository. Every other field is optional and any that are missing are defaulted and reported, not rejected. Never send source code."New value: +"Optional, source-free facts about the project you are changing. Supplying it adds Node/peer/license compatibility and a command-level verification plan. Omit it entirely and compatibility comes back \"unknown\" - read that as not checked, never as no problem found. Every field is optional; anything missing is defaulted and reported in input_adjustments, never rejected. Never send source code."
    • removedInput schema / properties / project / required
      Removed value: -[
      -  "package_manager"
      -]
    • addedInput schema / properties / to_version
      Added value: +{
      +  "description": "The version you intend to install: an exact version (\"4.18.1\"), a dist-tag (\"latest\"), or a SemVer range (\"^4.17.0\"). Omit to evaluate the latest published version.",
      +  "maxLength": 128,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • changedInput schema / required
      Previous value: -[
      -  "change"
      -]New value: +[
      +  "dependency"
      +]
  6. Changed13 schema fields changed
    • addedInput schema / examples
      Added value: +[
      +  {
      +    "change": {
      +      "name": "lodash",
      +      "to_version": "latest"
      +    }
      +  },
      +  {
      +    "change": {
      +      "from_version": "4.18.2",
      +      "name": "express",
      +      "to_version": "^5.0.0"
      +    }
      +  },
      +  {
      +    "change": {
      +      "dependency_type": "runtime",
      +      "name": "zod",
      +      "to_version": "3.23.8"
      +    },
      +    "policy_profile": "strict",
      +    "project": {
      +      "direct_dependencies": {
      +        "zod": "^3.22.0"
      +      },
      +      "installed_versions": {
      +        "zod": "3.22.4"
      +      },
      +      "node_version": "20.11.0",
      +      "package_manager": "pnpm",
      +      "scripts": [
      +        "build",
      +        "test"
      +      ]
      +    }
      +  }
      +]
    • addedInput schema / properties / change / description
      Added value: +"The single dependency you are about to add or upgrade. One dependency per call."
    • addedInput schema / properties / change / properties / dependency_type / description
      Added value: +"Where the dependency goes. Defaults to runtime."
    • addedInput schema / properties / change / properties / ecosystem / description
      Added value: +"Always npm. Omit it."
    • changedInput schema / properties / change / properties / from_version / description
      Previous value: -"Version being upgraded from, or null when adding a new dependency. Omit to infer it from the project snapshot. Alias keys \"current_version\", \"old_version\", \"previous_version\", and \"installed_version\" are adopted onto it."New value: +"The version currently installed, or null / omitted when adding a new dependency. Supplying it is what produces a before/after advisory comparison. Alias keys \"current_version\", \"old_version\", \"previous_version\", and \"installed_version\" are adopted onto it."
    • changedInput schema / properties / change / properties / name / description
      Previous value: -"npm package name. Prefer this key; the alias keys \"package\", \"package_name\", \"pkg\", \"dependency\", \"dependency_name\", \"module\", and \"library\" are adopted onto it and reported in input_adjustments."New value: +"The npm package name on its own — \"lodash\", \"@types/node\". Do NOT append a version here; a \"name@version\" spec is split for you and reported in input_adjustments. Alias keys \"package\", \"package_name\", \"pkg\", \"dep\", \"dependency\", \"dependency_name\", \"module\", \"library\", \"npm_package\", \"npm_package_name\", \"package_spec\", and \"dependency_spec\" are adopted onto it, as is any case or separator variant of \"name\"."
    • changedInput schema / properties / change / properties / to_version / description
      Previous value: -"Target version. Accepts an exact version (\"4.18.1\"), a dist-tag (\"latest\"), or a SemVer range (\"^4.17.0\", \"~1.2\", \"4.x\"). Tags and ranges are resolved to the single highest published match, which is what gets evaluated and reported back in input_adjustments. Alias keys \"version\", \"target_version\", and \"new_version\" are adopted onto it."New value: +"The version you intend to install: an exact version (\"4.18.1\"), a dist-tag (\"latest\"), or a SemVer range (\"^4.17.0\", \"~1.2\", \"4.x\"). Omit it entirely to evaluate the latest published version, which is what plain `npm install <pkg>` would give you. Ranges and tags resolve to one exact version — read change.to_version in the response for the version the verdict actually covers. Alias keys \"version\", \"target_version\", \"new_version\", \"desired_version\", and \"requested_version\" are adopted onto it."
    • changedInput schema / properties / change / required
      Previous value: -[
      -  "name",
      -  "to_version"
      -]New value: +[
      +  "name"
      +]
    • addedInput schema / properties / intent / description
      Added value: +"Optional free text describing why you are making this change. Advisory only; it changes no verdict. Note this is a plain string here — plan_repo_task takes an object under the same name."
    • changedInput schema / properties / policy_profile / description
      Previous value: -"Named team dependency policy. Strict requires provenance and denies npm install hooks."New value: +"Named team dependency policy. Strict requires provenance and denies package install hooks. This is the one key that must be spelled exactly — a near-miss spelling is rejected rather than guessed, because reading it wrong would answer under a policy you did not ask for."
    • changedInput schema / properties / project / additionalProperties
      Previous value: -falseNew value: +true
    • addedInput schema / properties / project / description
      Added value: +"Optional, source-free facts about the project you are changing. Supplying it adds Node/peer/license compatibility and a command-level verification plan. Omit it entirely and compatibility comes back \"unknown\" — read that as not checked, never as no problem found. If you DO send it, package_manager is the one field you must include: it selects the lockfile and the commands in the verification plan, so guessing it would hand you instructions for the wrong repository. Every other field is optional and any that are missing are defaulted and reported, not rejected. Never send source code."
    • changedInput schema / properties / project / required
      Previous value: -[
      -  "package_manager",
      -  "direct_dependencies"
      -]New value: +[
      +  "package_manager"
      +]
  7. Changed3 schema fields changed
    • changedInput schema / properties / change / properties / from_version / description
      Previous value: -"Version being upgraded from, or null when adding a new dependency. Omit to infer it from the project snapshot."New value: +"Version being upgraded from, or null when adding a new dependency. Omit to infer it from the project snapshot. Alias keys \"current_version\", \"old_version\", \"previous_version\", and \"installed_version\" are adopted onto it."
    • addedInput schema / properties / change / properties / name / description
      Added value: +"npm package name. Prefer this key; the alias keys \"package\", \"package_name\", \"pkg\", \"dependency\", \"dependency_name\", \"module\", and \"library\" are adopted onto it and reported in input_adjustments."
    • changedInput schema / properties / change / properties / to_version / description
      Previous value: -"Target version. Accepts an exact version (\"4.18.1\"), a dist-tag (\"latest\"), or a SemVer range (\"^4.17.0\", \"~1.2\", \"4.x\"). Tags and ranges are resolved to the single highest published match, which is what gets evaluated and reported back in input_adjustments."New value: +"Target version. Accepts an exact version (\"4.18.1\"), a dist-tag (\"latest\"), or a SemVer range (\"^4.17.0\", \"~1.2\", \"4.x\"). Tags and ranges are resolved to the single highest published match, which is what gets evaluated and reported back in input_adjustments. Alias keys \"version\", \"target_version\", and \"new_version\" are adopted onto it."
  8. Changed1 schema field changed
    • changedInput schema / required
      Previous value: -[
      -  "change",
      -  "project"
      -]New value: +[
      +  "change"
      +]
  9. Changed7 schema fields changed
    • changedInput schema / additionalProperties
      Previous value: -falseNew value: +true
    • changedInput schema / properties / change / additionalProperties
      Previous value: -falseNew value: +true
    • addedInput schema / properties / change / properties / dependency_type / default
      Added value: +"runtime"
    • addedInput schema / properties / change / properties / ecosystem / default
      Added value: +"npm"
    • addedInput schema / properties / change / properties / from_version / description
      Added value: +"Version being upgraded from, or null when adding a new dependency. Omit to infer it from the project snapshot."
    • addedInput schema / properties / change / properties / to_version / description
      Added value: +"Target version. Accepts an exact version (\"4.18.1\"), a dist-tag (\"latest\"), or a SemVer range (\"^4.17.0\", \"~1.2\", \"4.x\"). Tags and ranges are resolved to the single highest published match, which is what gets evaluated and reported back in input_adjustments."
    • changedInput schema / properties / change / required
      Previous value: -[
      -  "ecosystem",
      -  "name",
      -  "from_version",
      -  "to_version",
      -  "dependency_type"
      -]New value: +[
      +  "name",
      +  "to_version"
      +]
  10. Added

TDQS

A4.3/5.0
Behavior5/5

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, yet the description adds real behavioral context on top: everything inferred is recorded in input_adjustments, a missing project snapshot yields "unknown" compatibility which must be read as "not checked, never no problem found", and policy_profile mis-spellings are rejected rather than guessed. That is precisely the extra disclosure annotations cannot carry.

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 trigger and the question it answers, followed by inputs, defaults, and the no-side-effects guarantee. It is dense but nearly every sentence carries a distinct, actionable fact; only the repeated "never nested under a change key" warning overlaps with the schema text and costs a little tightness.

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 mutation-adjacent but read-only tool with a rich nested schema, an output schema, and strong annotations, the description covers the trigger, the shape of the return (blockers, warnings, recommendation, verification plan), the input-resolution behavior, and the no-write guarantee. Nothing an agent needs to invoke it correctly 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 baseline is 3, but the description adds genuine meaning: only `dependency` is required, omitting to_version evaluates the latest published version exactly as npm install would, and a dist-tag or SemVer range resolves to one exact version reported in change.to_version. It also warns that dependency is a bare string and every field is top-level, never nested under a "change" key.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — evaluates an exact dependency change — and scopes it with concrete evidence sources (registry metadata, advisory deltas, provenance, license, repository evidence). It never names the near siblings check_dependency or verify_dependency_change, so the agent must infer which one applies, which keeps it out of the 5 band.

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?

"CALL immediately before adding or upgrading an npm dependency" gives a clear trigger condition, and "Evaluates only; never installs or edits anything" marks the boundary against an install action. There is no explicit when-not or named alternative among the sibling tools, so it is clear context without exclusions.

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.

Resources