NPMScan

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context: it is a heuristic static scan, does not execute code, cannot see runtime-gated behavior, and is not proof of safety. This goes beyond the annotation baseline and manages expectations well.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every clause carries information: scope, rubric, output, limitations, and usage guidance. It is front-loaded with the core scan scope before diving into rubric details, and 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.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and a description that names the return fields (totalScore, riskTier), defines limitations, lists exclusions, and provides usage ordering, nothing needed for correct invocation or interpretation is missing.

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

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

Schema coverage is 100% with clear descriptions for both name and version. The description adds little parameter-specific meaning beyond confirming it fetches from the published tarball, but since the schema already documents the parameters fully, baseline 3 is appropriate.

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

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

States a specific verb ('statically scans') and resource (npm package lifecycle scripts plus referenced files fetched from the tarball), and enumerates the rubric categories. It clearly differentiates from sibling tools by specifying what it analyzes and what it returns (totalScore, riskTier).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly instructs to use get_package/get_package_version first for raw script listings and defines when this tool is needed ('when you need to know what an install script actually does'). It also states what it does not cover (maintainer/ownership history), helping an agent avoid misusing it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description is consistent with both. It adds substantial behavioral context beyond annotations: per-branch semver max-satisfying resolution rather than npm/yarn hoisting/dedup emulation, only the dependencies field being followed, unresolvable git/file/URL deps surfacing as resolutionError instead of being skipped, a total node budget requiring checks of truncated/truncationNote, and a deterministic summary field to read first.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every section earns its place: mechanics with defaults, guidance on which output fields to read first, four material limitations that affect how results must be interpreted, and a routing sentence to the sibling tool. It is front-loaded with the core verb and resource, and the caveats are organized so an agent can parse them in dependency order.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with recursive traversal, semver range resolution, and an external vulnerability-checking service, the description is complete: it covers defaults, caps, unsupported dependency types, truncation behavior, result-field semantics, and the sibling alternative. The output schema exists so return values need not be restated, yet the description still explains the three most important fields (summary, vulnerablePaths, nodes) for correct result interpretation.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value on top by explaining how packages and version ranges actually behave: ranges are "resolved independently per branch via semver max-satisfying against published versions," maxDepth reflects how many levels beyond roots are expanded, and the 0-level meaning is clarified in the schema. It also gives the reason for the maxDepth cap (registry call bounds and timeout), which the schema's bare maximum does not convey.

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

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

The description states a specific verb and resource: it "recursively resolves one or more direct/root packages' dependency graphs" and "batch-checks every resolved package@version against OSV.dev." It also distinguishes itself from siblings by explaining the graph-walking scenario it is uniquely suited for and explicitly naming batch_query_vulnerabilities as the alternative for flat-list checks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description explicitly routes to the alternative: "Prefer batch_query_vulnerabilities instead when you only need to check exact packages you already have a flat list for (faster, no graph walk)." It also states the when-to-use case — surfacing vulnerabilities buried several levels down that direct-dependency checking would miss — and gives concrete scope caveats an agent must know before trusting a clean result.

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

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

The description goes far beyond the readOnly/openWorld annotations: it discloses lockfile priority order, monorepo detection behavior, per-call caps (100 dependencies, 50 workspace members, 10 deep scans, 5 ownership checks), prioritization rules, and the cost profile. It also surfaces limitations such as yarn.lock not distinguishing dev from production dependencies.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single dense paragraph, but the opening sentence front-loads the core action and every subsequent clause adds an operationally important constraint or caveat. It is longer than ideal and could benefit from bullet structure, but no sentence is filler given the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers detection behavior, caps, fallback outputs, result fields (isMonorepo, workspaceNote, deepScanNote, ownershipCheckNote), cost, and limitations, and an output schema also exists. An agent has everything needed to decide whether to call it and what to expect.

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

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

Input-schema coverage is 100%, and the schema already carries detailed descriptions for url, ref, policy, and includeDevDependencies, including defaults and lockfile interactions. The tool description adds broad behavioral constraints like the 100-dependency cap, but it does not materially enrich the meaning of individual parameters beyond the schema.

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

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

The description names a specific verb and resource: audit a GitHub repository by fetching package manifests and lockfiles and running the vulnerability, license, install-script, and ownership-risk pipelines. It explicitly references sibling tools as individual pipelines and frames the tool as the all-in-one repository-level version, so it is clearly distinguishable from them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

It explains this is a combined alternative to the individually exposed pipelines and warns that it is the most expensive tool, stating 'don't call it in a loop across many repos.' This gives an agent a clear cost-based usage boundary and names the operations it replaces.

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

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

Beyond the readOnlyHint annotation, the description discloses meaningful behavior: it normalizes npm dependencies first, chunk-queries OSV.dev behind the scenes, handles large inputs past the upstream 100-package limit, and returns enriched findings with severity, summary, CVE aliases, and fixed versions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded and information-dense, covering purpose, input modes, internal behavior, and output value. It is slightly longer than strictly necessary because some format details are also present in the schema, but every sentence contributes useful decision-making context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the optional mutually exclusive parameters, the external OSV.dev dependency, and the batch behavior, the description covers the key aspects an agent needs: input options, normalization, chunking behavior, and what kind of findings are returned. The output schema handles return-value details, so the description is sufficiently complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context about input formats and normalization, but most parameter meaning is already present in the schema. It does not materially enrich the semantics of `packages`, `content`, or `includeDevDependencies` beyond what the schema states.

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

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

The description clearly states a specific verb and resource: querying OSV.dev for known vulnerabilities across a whole npm dependency inventory. It also distinguishes itself from per-package or single-CVE tools by emphasizing batch operation and that no follow-up call is needed per flagged package.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description gives clear context for when to use this tool: when auditing an entire npm dependency inventory at once, including large SBOMs. It implies the alternative of querying per package, but it does not explicitly name query_vulnerabilities or state when not to use it.

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

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

Beyond the readOnly/openWorld/non-destructive annotations, the description adds substantial behavioral detail: it defines license classification categories, explains how SPDX OR/AND/WITH expressions are evaluated, states that mixed nested expressions are reported as needsReview, and notes that policy.deny always overrides policy.allow. It also exposes the limitation that LICENSE file contents are not parsed. These disclosures meaningfully shape agent expectations and contradict nothing in the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The first sentence is a compact, front-loaded summary of the tool's core purpose, and each subsequent sentence adds a distinct non-obvious behavior: classification categories, SPDX expression interpretation, mixed-expression fallback, deny precedence, and the registry-field limitation. The length is proportionate to the tool's complexity, with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter tool with nested schemas and an output schema, the description covers the input format, optional policy behavior, expression evaluation rules, precedence semantics, and a critical limitation. An agent has enough information to decide whether to invoke the tool and what kinds of results to expect, and the output schema handles return-value details.

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

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

The schema already documents both parameters and their fields at 100% coverage, providing a strong baseline. The description goes further by giving concrete semantics: packages can come 'straight from a package.json dependencies object', version accepts exact or semver ranges, omitted version means latest, deny always wins over allow, and omitted policy means the default policy applies. This adds practical invocation guidance beyond the schema.

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

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

The description opens with a specific action: resolving a list of packages' declared SPDX licenses and reporting a compliance verdict per package, with the title naming the resource and goal. The focus on licensing, policy handling, and per-package verdicts clearly distinguishes it from sibling vulnerability, provenance, and maintainer-focused tools without needing explicit cross-references.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description clearly states when to use the tool: given a list of packages and an optional allow/deny license policy. It also clarifies that omitting the policy uses the default, and it emphasizes the limitation that only the registry-declared license field is read. It does not explicitly name alternative sibling tools or state 'when not to use', so it falls just short of a 5.

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

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

Annotations already mark the tool as read-only and open-world, and the description adds substantial behavioral detail beyond that: it names the exact npm search endpoint, warns that results are capped at 250 and may lag or be truncated, explains how current maintainer membership is cross-checked, and details scoring behavior such as popularity weighting and diminishing returns for multiple clusters. No contradiction with the annotations exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but front-loaded and organized: it begins with the core operation, then explains the threat rationale, scoring behavior, and known limitations. Every section adds useful context, though some details like the qix compromise example and avatarUrl proxy explanation could arguably be trimmed or moved into the output schema without losing invocation guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, the description is complete: it covers data source, limitations, truncation behavior, scoring semantics, output fields, and the natural relationship to sibling tools. The output schema exists, so the description does not need to enumerate return values, and it still names key output fields like resultsTruncated and totalPackagesFound where interpretation matters.

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

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

Schema coverage is 100%, and the schema already fully documents maintainerUsername as an exact npm username, not an email, package name, or scope. The description reinforces this by saying 'Given an npm username' and by explaining how the username is used in the maintainer search, but it does not add new constraints or examples beyond the schema. Baseline 3 is appropriate.

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

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

The description states a precise operation: given an npm username, enumerate packages via npm's maintainer search and detect tight publish-time clusters. It clearly names the underlying API source and the threat pattern it detects, and it distinguishes itself from related tools by positioning it as a follow-up to check_maintainer_changes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description gives an explicit trigger condition: call this when check_maintainer_changes flags a newly added or fully turned-over maintainer. It also warns that a large total package count is not a red flag, preventing misuse of the tool as a volume metric, and explains the compromised-account scenario it is designed for.

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

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

The description goes far beyond the readOnlyHint and destructiveHint annotations by revealing the internal method (diffing maintainer-list snapshots from the npm packument), the guarantee of no extra API calls, the exact red-flag heuristics, and the GitHub repository cross-checks including what the ownerAvatarUrl proxy does. It even discloses null behavior ('both null whenever the repo check itself didn't reach GitHub'). This is exemplary transparency for a read-only analysis tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but information-dense; nearly every sentence adds a distinct fact or behavioral guarantee. It is front-loaded with the mechanism and flags before moving to GitHub checks and usage guidance. A minor grammar issue ('repository.ownerLogin/ownerAvatarUrl name and show the CURRENT owning account') and a somewhat long tail about avatar proxying prevent a perfect score, but overall the structure serves an agent well.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, the description covers the essential input, methodology, flags, output semantics, and follow-up workflow. The output schema exists and would provide the full field list, so the description need not enumerate every return value; it nonetheless clarifies candidate-specific fields like repository.ownerLogin and ownerAvatarUrl. No critical operational context is missing for correct invocation and interpretation.

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

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

The input schema already documents the single 'name' parameter with a clear description and examples ('lodash' or '@scope/name'), so schema coverage is 100%. The tool description adds nothing beyond the tool's overall scope, which is acceptable because the parameter is trivial and fully documented in the schema. Baseline 3 is appropriate; no additional guidance is needed.

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

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

The description opens with a specific verb ('Reconstructs') and resource ('a package's maintainer-change history'), then enumerates four concrete flags that define the tool's unique value. It clearly distinguishes itself from siblings like get_maintainer_profile and check_package_provenance, and even names check_maintainer_blast_radius as a different follow-up tool. An agent can confidently know what this tool does and what it does not do.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description explicitly states when to use this tool: 'Use get_package/check_package_provenance first for the package's general health and publish-integrity signals; use this specifically for the who controls this package, and did that change recently question.' It also gives a concrete follow-up instruction to run check_maintainer_blast_radius when a specific flag condition is met. This is model usage guidance with both alternatives and exclusions.

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

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

Annotations only declare readOnlyHint=true and openWorldHint=true, so the description carries the burden of behavioral disclosure. It fully discloses that this is a heuristic structural check, does NOT cryptographically re-verify the Sigstore bundle, trusts the registry's prior verification, and treats results as anomaly signals rather than proof of malice. This is rich, accurate behavioral context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured with numbered checks, a clear limitations section, and front-loaded purpose. Each sentence adds meaningful guidance, though a few parenthetical examples (event-stream/ua-parser-js) are illustrative rather than strictly necessary. Overall it is detailed without being padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, the description fully explains the three checks, the meaning of their results, the heuristic limitations, and how to sequence it with sibling tools. An output schema exists, so not describing return values is acceptable. Nothing an agent needs to decide when and how to call this tool is missing.

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

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

Input schema coverage is 100%, with both 'name' and 'version' already described (exact name, optional version defaults to latest). The description adds context about commit/tag matching but does not add much parameter-level meaning beyond the schema. Baseline 3 is appropriate because the schema fully carries parameter documentation.

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

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

The description opens with a specific verb+resource: 'Checks whether a package version was published with npm's own Sigstore-backed publish provenance' and then enumerates three concrete checks. It clearly distinguishes this tool from sibling tools by framing it as a publish-integrity risk assessment rather than a general package info or vulnerability query.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly instructs to 'Use get_package/get_package_version first for basic package info; use this specifically to assess publish-integrity risk.' It also clarifies when not to over-interpret results: bare absence of provenance is never scored alone, only an org-norm anomaly or source mismatch is. This gives an agent clear routing and interpretation guidance.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses substantial behavior: fetches happen in parallel, installScriptRisk does NOT fetch the tarball, installSize transitive rollup is truncated with explicit flags, unresolved names appear with found:false rather than failing, and duplicate names are rejected. It also explains the deterministic scoring and exclusion of deprecated/typosquat candidates. This far exceeds annotation coverage and contradicts nothing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense and heavily nested, with long parentheticals and dash-separated caveats (e.g., the installSize transitive rollup explanation). It is front-loaded with the core purpose and every clause carries information, but the prose would benefit from shorter sentences and better paragraph breaks for readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, the description is remarkably complete: it covers error handling for unresolved names, duplicate rejection, dependency-tree truncation behavior, scoring weights, exclusions, and routing to deeper tools. Since an output schema exists, the lack of specific return-value details is acceptable. An agent has enough context to invoke this tool correctly in most scenarios.

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

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

The single parameter 'packages' already has a descriptive schema comment with examples, so baseline is 3. The description adds extra semantic nuance: candidates should be 'for the same job' and duplicate names are rejected. These details are not present in the schema and help the agent use the parameter correctly.

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

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

The description opens with a specific verb and resource: it compares 2-5 npm packages side-by-side and returns a structured comparison plus a reasoned pick. It distinguishes itself from siblings like analyze_install_script and analyze_transitive_dependencies by explicitly scoping its purpose to comparison rather than deep single-package analysis.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

It provides clear context by stating it is for candidates 'for the same job' and explicitly points to alternatives: 'call analyze_install_script on a specific candidate for that deeper scan' and 'call analyze_transitive_dependencies on a specific candidate for the full graph'. However, it never explicitly says when NOT to use this tool, such as 'use get_package for a single package', so it lacks a full when-not dimension.

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

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

Annotations only declare readOnlyHint, openWorldHint, and non-destructive. The description adds significant non-obvious behaviors: 100-per-call cap, presence-only install-script check (not tarball scan), direct-vs-transitive diff scoping per format, vulnerabilityDelta granularity, and comparisonNote for mixed formats. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence carries meaningful information—supported formats, limit, signal explanation, scope differences, and alternatives. It is well-structured but dense; could be trimmed slightly without losing value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and that an output schema exists, the description amply covers all critical operational nuances: what it reports, the limit, format-specific scope, how install scripts are checked, and when to delegate to a sibling. Nothing essential is missing.

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

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

Schema coverage is 100% and both before/after already have detailed descriptions in the schema (raw content, supported formats, auto-detection, may differ). The tool description repeats that but adds no new parameter-level meaning beyond contextualizing the diff workflow. Baseline 3 applies.

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

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

Clearly states the verb 'Compares' and the resource: two raw snapshots of package manifests, listing supported formats and the add/remove/version-bump report. It also distinguishes itself from sibling analyze_install_script by explicitly naming it as the deep-dive alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly identifies its primary use case ('Ideal for a CI gate reviewing a dependency-changing PR') and gives an alternative ('use analyze_install_script for a deep-dive'). It also provides scope caveats for yarn.lock and mixed-format comparisons, so the agent knows what to expect.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't contradict them. It enriches the safety profile by explaining that it resolves GHSA IDs to CVEs and that skipping this step would silently degrade findings. It also discloses the multi-advisory handling (only first advisory used) and the fixTarget caveat (may name a different package). This level of behavioral disclosure goes well beyond what annotations alone encode.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is comprehensive but verbose, running several sentences packed with caveats and alternatives. It is well-structured and front-loaded with a clear purpose, but not concise; a shorter version could convey the same essential facts. Every sentence earns its place, but a tighter edit would improve scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with one parameter, no nested objects, but an output schema, the description covers input formats, transformation logic, edge cases (multiple advisories), and alternatives. It even warns about the silent degradation if CVE resolution is skipped. 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.

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

The sole parameter, content, is described in the schema with 100% coverage of its format (npm 7+ vs npm 6). The description adds that it is parsed directly (no re-pasting of package.json) and explains why the GHSA resolution matters, which clarifies the purpose of the input beyond the literal schema. Since schema coverage is complete, the description adds value without being essential.

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

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

The description opens with a specific verb-resource pair: 'Rank raw npm audit --json output by what to fix first'. It immediately distinguishes itself from prioritize_remediation (which works on hand-built findings) and from query/batch_query_vulnerabilities, and explicitly lists unsupported formats (yarn/pnpm) with a pointer to the alternative. Purpose is unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description explicitly states when to use this tool (given raw npm audit output) and when not to (yarn/pnpm audit), naming batch_query_vulnerabilities as the alternative. It also describes a fallback: if a package has multiple advisories, call query_vulnerabilities on it. These usage rules are explicit and unambiguous.

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

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

The description goes well beyond the read-only/non-destructive annotations by disclosing important behavioral nuances: VEX findings are marked in_triage and are not exploitability claims, SPDX has no vulnerability array so externalRefs are used, and the transitive dependency graph is intentionally omitted rather than fabricated. This is exactly the kind of non-obvious behavior an agent needs to know.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long and dense, but it earns its length by packing in format-specific behavior, caveats, and parameter effects. It is not front-loaded with the output first, but the title and opening input framing still orient the agent quickly. There is no filler, and every clause adds operational value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with 9 parameters, nested objects, and an output schema, the description covers the essential operational details: inputs, formats, vulnerability/license embedding differences, omission of dependency graphs, policy integration, and performance-related flags. The presence of an output schema means return-structure details do not need to be repeated, and nothing critical is missing.

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

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

Schema description coverage is already high at 89%, so the baseline is 3. The description adds meaningful extra semantics: packages/content are framed as the same accepted inputs as batch_query_vulnerabilities, includeVulnerabilities/includeLicenses are tied to faster execution by skipping OSV/registry calls, and componentName/componentVersion are clarified as naming the root component. This is a solid enhancement without being fully redundant.

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

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

The description clearly states the tool's function: generate a spec-valid CycloneDX 1.6 or SPDX 2.3 SBOM document from a package list or raw dependency content. It also differentiates itself by naming the specific enrichment data (OSV.dev vulnerabilities and registry licenses) and how they are embedded per format, which distinguishes it from the sibling query/compliance tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description gives strong usage context: it explains the two accepted input modes, references sibling tools for shared input/policy shapes, and notes when to disable enrichment passes for speed. It does not explicitly state when not to use this tool versus alternative siblings, but for an SBOM-generation tool the intended use case is clear.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, and the description adds significant behavioral context beyond that: results are enriched with KEV and EPSS, single-ID lookups fall back to MITRE records with source: 'mitre', and NVD has a shared rate limit that may require retries. This gives the agent practical expectations about data provenance, urgency semantics, and transient failures.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence earns its place: purpose, enrichment semantics, fallback behavior, scope warning, routing guidance, and rate-limit caveat. The core action is front-loaded in the first sentence, and the additional caveats are each relevant to avoiding incorrect agent behavior. Nothing reads as filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 8 parameters, two operating modes, and cross-ecosystem scope, the description covers all critical decision points: exact ID lookup vs search, non-npm scope, fallback source, priority signals, rate limiting, and sibling-tool routing. The output schema exists, so the absence of return-field detail is not a gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context on top of the schema: it explains that keywordSearch should carry a package name to narrow the cross-ecosystem NVD results, clarifies that cveId mode ignores search filters, and explains the purpose of EPSS/KEV fields. This goes beyond the raw schema but not exhaustively for every parameter.

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

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

The description opens with a specific verb and resource: 'Look up authoritative NIST NVD data' for one exact CVE ID or as a search/browse tool. It clearly distinguishes itself from sibling tools by stating that NVD is NOT npm-scoped, unlike query_vulnerabilities/get_latest_advisories. This makes the tool's purpose immediately identifiable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description gives explicit when-to-use guidance: 'Prefer this for the authoritative CVSS score/vector/KEV/EPSS data on a CVE already found via another tool, or when a user pastes a CVE ID/link directly; prefer get_latest_advisories for npm-specific browsing.' It also tells the agent to pass keywordSearch to narrow results because NVD covers all ecosystems. This is strong routing guidance with named alternatives.

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

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

Annotations already mark the tool as read-only, non-destructive, and open-world, so the safety profile is covered. The description adds genuine behavioral detail beyond annotations by explaining pagination with an opaque cursor and the notion of 'reviewed' advisories. This is useful runtime context that the annotations alone do not provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences cover the resource, filtering options, exact lookup, and pagination mechanics with no filler. The most important capability is front-loaded, and every sentence contributes actionable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and no nested objects, the description covers the key operational aspects an agent needs: what is returned conceptually, how to paginate, what filters exist, and how to do an exact lookup. Nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds value by explaining how the cursor relates to a previous response's nextCursor and by summarizing the filter dimensions (severity, category, package, exact ID). It complements rather than repeats the schema.

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

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

The description explicitly names the resource ('npm security advisories'), the action ('browse', 'filter', 'look up'), and the scope ('recently published, reviewed'). It also distinguishes the exact-lookup behavior from browsing, making the tool's purpose unmistakable even without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description gives clear context for when to use the tool: to browse recent advisories, filter by severity/category/package, or look up by GHSA/CVE. It does not explicitly name alternatives or exclusion criteria, leaving some sibling differentiation to inference, but the intended use cases are well stated.

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

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

Beyond the readOnly/openWorld/destructive annotations, it discloses that this is a plain info lookup, does NOT run compromised-account detection, depends on npm's current search index, and defines what currentlyMaintainsCount and avatarUrl mean. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is heavily front-loaded and every clause adds context, but it is a long single run-on paragraph with dense parentheticals. It is efficient in content, not in structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description need not re-explain return shape; it covers the data source quirk, aggregate semantics, avatar null behavior, and routing to sibling tools. Nothing essential is missing for correct invocation.

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

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

Schema coverage is 100% and the schema already documents maintainerUsername as an exact npm username with exclusions. The description only says 'Given an npm username,' so it adds no additional parameter meaning beyond the schema baseline.

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

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

The description states a specific verb and resource: 'Given an npm username, returns every package npm's own maintainer:<username> search index currently returns for that account,' then enumerates the aggregates. It also contrasts itself with check_maintainer_blast_radius, making the tool's scope unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

It explicitly tells the agent to use check_maintainer_blast_radius instead when the intent is a security/takeover read, and it names the natural workflow with check_maintainer_changes. This is direct when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate readOnly, openWorld, and non-destructive behavior, so the bar is lower, but the description adds significant behavioral context: topPackagesRank is from a periodically-refreshed snapshot and not live; popularityTier/maintenanceTier are deterministic rule-based labels, not model-generated; possibleTyposquatOf has a specific definition; and the vulnerability fields are described as giving a 'direct safe/not-safe answer.' No contradictions with annotations exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long, but nearly every clause adds decision-relevant information, such as install scripts being a key risk signal, snapshot staleness, and tier derivation. It is front-loaded with the core resource and risk signal, and the length is justified by the tool's rich output. It loses a point only for being dense and somewhat run-on.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with one parameter and a rich output schema, the description covers all the non-obvious semantics an agent needs: interpretability of downloadTrend, staleness of ranking data, how to interpret last-publish gaps, typosquatting detection, and where to find the full analysis page. The output schema already exists, so the description does not need to restate return types. Nothing critical is missing.

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

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

Schema description coverage is 100% and the sole parameter, name, is already well-defined in the schema as an exact npm package name with examples. The tool description repeats that it fetches package metadata but adds no parameter semantics beyond the schema. Baseline 3 is appropriate because the schema carries the full burden.

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

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

The description opens with a specific verb and resource: 'Fetch npm registry metadata for a package' and enumerates concrete returned fields (latest version, install scripts, maintainers, license, downloads, vulnerability check). It also explicitly distinguishes itself from get_package_version by clarifying it checks the LATEST version against OSV.dev while older versions require a different tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description gives explicit routing guidance: 'use get_package_version or query_vulnerabilities to check a specific older version instead.' It also instructs the agent to read deprecated and maintenanceSummary before recommending a package, and explains the interpretation nuance of long gaps since last publish. This clearly communicates when to use this tool versus alternatives.

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

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

Annotations already declare readOnly and non-destructive, and the description adds rich behavioral context: the tool performs an external OSV.dev check, returns a direct vulnerability verdict, and details each finding. This goes well beyond annotations and tells the agent exactly what side effects and outputs to expect.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, with the core action front-loaded and the vulnerability-checking behavior described concisely. Every phrase earns its place, and the lockfile guidance is a valuable addition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a dual-purpose tool (registry fetch + vulnerability check) with an output schema and annotations, the description is complete: it explains the direct answer fields, the nature of findings, and the intended use case. No critical information is missing for an agent to call it correctly.

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

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

Schema description coverage is 100%, with both name and version well-documented in the schema. The description repeats that it's an 'exact version' and clarifies the purpose, but adds no new semantic information about the parameters themselves. Baseline 3 is appropriate.

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

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

The description clearly states the tool fetches registry metadata for a specific version and checks that version against OSV.dev for vulnerabilities, listing the exact outputs (dependencies, install scripts, tarball, isVulnerable, highestSeverity, findings with severity, summary, fixedVersion). This is precise and distinguishes it from siblings like get_package or query_vulnerabilities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description explicitly says 'Use this to check a version pinned in a lockfile rather than the latest release,' providing a clear when-to-use condition and a when-not-to-use (latest release). It doesn't name specific alternative tools but gives enough context to route an agent correctly.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: batching with deduplication, situationNote per rule to avoid repeated boilerplate, and the matched:false behavior for unrecognized inputs. It also discloses that the content matches /docs/playbooks, giving the agent a confidence anchor.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence earns its place: it explains the mapping, the return payload, batching, deduplication, situationNote behavior, and error semantics. It is front-loaded with the core purpose and then layers in usage details. No filler or repetition of schema fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 2 optional params and no required params, the description is remarkably complete. It covers input source, batching limits, deduplication, per-rule output nuance, unmatched behavior, and references the published playbook location. The output schema exists, so return values don't need to be spelled out.

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

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

Schema coverage is 100% and the schema descriptions already explain both id and rules well. The description adds meaning by explaining how the two parameters relate (id for direct slug lookup, rules for batch lookup from findings), and clarifies that duplicates resolving to the same playbook are deduplicated. This goes beyond the schema's basic field descriptions.

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

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

The description precisely identifies the tool's function: it maps rule values from specific sibling analysis tools to human-authored playbooks and returns ordered steps, severity tier, references, and prevention tips. It clearly distinguishes itself from siblings like prioritize_remediation and query_vulnerabilities by saying it returns actual playbook content, not just a link.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description explicitly says when to use this tool: after a finding from analyze_install_script, check_maintainer_changes, or check_package_provenance, and how to batch up to 10 rules. It also explains what is not an error (unrecognized rule/id returns matched:false) and gives a concrete example of an id lookup. Alternatives are implicitly covered by naming the exact source tools, and the description clarifies the 'not just a link' distinction.

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

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

Beyond the annotations readOnlyHint, openWorldHint, and destructiveHint, the description discloses meaningful behavior: KEV is an automatic top-priority override, EPSS is the primary signal, severity is a fallback, and CVE lookups are deduplicated within a call. This aligns with the annotations and adds useful detail about ranking logic.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but densely informative; each sentence contributes distinct guidance about tool selection, ranking signals, input provenance, or deduplication behavior. It is appropriately front-loaded with the core purpose, though slightly more verbose than strictly necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's algorithmic complexity and the presence of an output schema, the description covers the important invocation context: where findings come from, how scores are composed, how tiers are derived, what happens for GHSA-only findings, and the deduplication behavior. No significant missing context remains for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds additional param-level guidance: findings without a CVE alias (e.g. GHSA advisories) are still ranked using severity alone, and the input should be previously-flagged findings rather than raw package data. This goes beyond the schema's basic field definitions.

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

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

The description states a specific verb ('ranks') and resource ('a batch of vulnerability findings already flagged elsewhere'), and clearly defines the outcome ('what to actually fix first'). It also distinguishes itself from siblings by naming upstream tools such as batch_query_vulnerabilities, analyze_transitive_dependencies, and query_vulnerabilities, and by explicitly saying it does NOT re-query OSV/NVD.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

It gives explicit when-to-use context: pass in findings that other tools have already returned, not raw package data. It also states an explicit exclusion ('does NOT re-query OSV/NVD itself') and names an alternative (get_cve returns the same per-CVE enrichment), so an agent can decide between tools.

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

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

Annotations already mark it read-only and non-destructive; the description adds useful behavioral context beyond annotations by specifying it returns a summarized 'direct answer' and 'not a raw advisory dump,' while noting the external source (OSV.dev). No contradiction with the readOnlyHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences cover purpose, return shape, and usage timing. The most decision-relevant information is front-loaded with no filler or repetition of schema details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 3-parameter read-only tool with 100% schema coverage and an output schema, the description fully covers what the tool does, what it returns, and when to use it. Nothing an agent needs to select and invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the version parameter's purpose via the lockfile example, but it does not add new meaning beyond what the input schema already provides.

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

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

States a specific verb and resource ('Query OSV.dev for known vulnerabilities affecting an npm package') with an optional exact-version scope. This clearly distinguishes it from siblings by promising a direct isVulnerable answer for a single package, not a raw advisory feed.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly directs use 'before recommending, installing, or upgrading a package,' giving clear decision context. It does not explicitly name when-not-to-use or alternatives such as batch_query_vulnerabilities, so it falls just short of a 5.

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

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

Annotations already indicate a harmless read-only search, but the description goes well beyond them by disclosing that topPackagesRank is from a snapshot and not live, that labels are deterministic rather than model-generated, and that certain result signals indicate likely abandoned or squatted packages. It also defines the possibleTyposquatOf field semantics and how the agent should react, which is valuable behavioral context not visible in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence carries operational value, especially the caveats about abandoned packages and typosquatting. It is front-loaded with the primary action and then layers interpretation and workflow guidance, though a slightly more structured format would improve scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and the presence of an output schema, the description fully covers what the agent needs: what results include, how to interpret unreliable signals, how to handle typosquat flags, and what to do next (call get_package). No critical guidance is missing.

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

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

Schema coverage is 100% — both query and limit are already documented with constraints and defaults. The description adds only minor context ('by name or keywords'), which does not materially exceed the schema, so the baseline score of 3 is appropriate.

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

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

Description states a specific verb ('Search') and resource ('the npm registry'), and defines what the results include. It clearly distinguishes from sibling get_package by framing search as the discovery step and get_package as the deep-dive on a shortlist.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Provides explicit workflow guidance: use download counts, dependentsCount, and popularityTier/maintenanceTier instead of name recognition or README, and call get_package on the shortlist before recommending. It also tells the agent how to treat possibleTyposquatOf results, effectively specifying when to flag versus silently filter.

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

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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint=false, and the description is fully consistent with them. Beyond the annotations, it discloses the complete signal set (deprecation, lifecycle script introduction, engines.node tightening, prerelease status), the vulnerabilityDelta semantics against OSV.dev, the 0.x-as-breaking semver convention, multi-major jump handling, the deduped/parallelized cost model, and per-item fetchError isolation instead of whole-batch failure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long (~300 words) but every sentence carries non-redundant information for a genuinely complex tool, and it is front-loaded with the core contract before diving into signals, exclusions, and batch behavior. Its structure flows logically, though it is slightly wordy in spots (repeated 'not both', dense parenthetical-heavy sentences) — dense but earned.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with two invocation forms, a rich output schema, and multiple analysis signals, the description covers everything needed to call it correctly: single vs batch inputs, output contract (riskTier, vulnerabilityDelta, reasons, fetchError), explicit non-goals, cost characteristics, and error behavior. Nothing critical is left to inference.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine value beyond the schema: mutual exclusivity of packages vs packageName/currentVersion, the default of targetVersion to the 'latest' dist-tag when omitted, mapping fixedVersion from prioritize_remediation findings directly, and the batch cost note (one deduped call vs N single calls). This elevates it above baseline, though the schema already documents each field's format precisely.

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

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

The opening sentence states a specific verb and resource with a concrete outcome: 'tells you whether that specific upgrade is a safe patch/minor bump or a likely-breaking major bump, before you actually run npm install.' It differentiates itself from siblings immediately by scoping to pre-install upgrade simulation and explicitly names prioritize_remediation as its natural predecessor, so an agent can distinguish it without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description names the exact workflow context ('Natural follow-up to prioritize_remediation: pass its packageName/currentVersion/fixedVersion straight in') and states explicit exclusions: 'This does NOT read the package's changelog/release notes... not a substitute for reading the release notes on a flagged major bump.' It also gives precise when-to-use guidance for batch vs single-item invocation, including the 'not both' rule.

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

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

Annotations already mark the tool read-only and open-world; the description adds real behavior beyond that: it checks the source package's health, combines maintainer deprecation hints with npm search category matching, filters out typosquats and stale contenders, and returns whySuggested reasons. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description packs the purpose, workflow, filtering logic, output format, and when-to-use into one focused paragraph. The main purpose is front-loaded and every sentence carries operational detail for an agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 3-parameter tool with an output schema and read-only/open-world annotations, the description covers the decision path, ranking/filtering behavior, and expected output shape. An agent can correctly select and invoke it without needing further documentation.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaningful context by explaining how the source package health check and category-overlap ranking use the name, and how the reason parameter biases filtering and ranking. This pushes it above baseline without being redundant.

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

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

The description opens with a specific verb–resource pairing ('suggest better-maintained alternatives in the same category') and explains the multi-step health-check-and-search process, which clearly distinguishes it from sibling tools like search_packages or get_package. It even frames the use case as turning a 'don't use this package' warning into a shortlist.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

It gives an explicit trigger ('Given a package that looks deprecated, vulnerable, abandoned, or suspicious') and a 'Best for' sentence, so an agent knows when to invoke it. It does not explicitly name sibling tools or state when not to use them, which keeps it just below the strongest possible guidance.

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