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 (for the version itself and for every package in the dependency tree a fresh install resolves to), 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.5/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, and the description aligns exactly by stating it evaluates only and never installs or edits anything. Beyond that, it discloses that every default, repair, and resolution is listed in input_adjustments, that missing project data yields compatibility "unknown" (not "no problem found"), and that to_version ranges resolve to one exact version reported in change.to_version.

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 front-loads the action and purpose in the first sentence, then layer usage, inputs, and behavior. It is mostly dense and purposeful, though the repeated emphasis on top-level fields and the example JSON add some redundancy for an already 100%-covered schema.

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 evaluation tool with 8 parameters, nested objects, and an output schema, the description covers the critical agent-facing behavior: when to call, what is inferred, how omitted project data is handled, that unsupported input shapes are rejected, and that the tool never mutates. With the output schema present, it does not need to enumerate return fields in detail, and its mention of blockers, warnings, recommendation, and verification plan is sufficient orientation.

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?

Schema coverage is already 100%, but the description adds substantial meaning beyond the schema: dependency must be a plain string (not an object or a {"change":{}} wrapper), to_version accepts exact versions, dist-tags, or SemVer ranges, from_version enables before/after advisory comparison, and policy_profile near-misses are rejected rather than guessed. It also explains dependency_type word mappings and that package_manager only affects verification commands and lockfile naming.

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?

The description states a specific verb and resource: evaluate a dependency change, answering "is this exact version safe to take on" from registry, advisory, provenance, license, and repository evidence. It clearly distinguishes evaluation from installation ("Evaluates only; never installs or edits anything"). However, it does not name or contrast with sibling tools such as verify_dependency_change or check_dependency, so sibling differentiation is left implicit.

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?

It gives a clear trigger: "CALL immediately before adding or upgrading an npm dependency." It also clarifies the minimum input ("Only `dependency` is required — omit to_version to evaluate the latest published version"). But it provides no explicit when-not-to-use conditions or named alternatives, so the agent must infer the boundary with check_dependency and verify_dependency_change.

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