NPMScan

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

Beyond the readOnly/openWorld annotations, the description reveals essential behavioral traits: it fetches directly from the published tarball, performs a heuristic static scan, does not execute code, cannot detect behavior gated on runtime conditions, and returns a weighted score and risk tier. This is substantial added 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 every element earns its place: scope, what it checks, return value, limitations, and usage guidance. The dense red-flag enumeration could be summarized more tightly, but it is informative rather than fluff. Overall, it is well structured and front-loaded with the core action.

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 what the tool does, how it operates, its limitations, its output, and how it relates to siblings. Given that an output schema exists, the description is more than complete for an agent to decide when and how to invoke it.

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% for both parameters (name and version), and the schema already explains their meaning and defaults. The description adds no additional parameter-level details, so the baseline 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?

The description opens with a specific action and resource: 'Statically scans a package's preinstall/install/postinstall/prepare lifecycle scripts AND the file(s) they reference'. It also clearly differentiates itself from sibling tools by stating it does NOT check the raw script listing and explicitly points to get_package/get_package_version for that purpose.

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 direct when-to-use guidance: 'use get_package/get_package_version first for the raw script listing; use this when you need to know what an install script actually does, not just that one exists.' It also states what the tool cannot do, such as not executing code and not seeing runtime-gated behavior, which helps agents decide if this is the right tool.

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 cover the safety profile (readOnly, non-destructive, openWorld), and the description adds genuinely non-obvious behavior: resolutionError nodes are unscanned rather than clean, only 'dependencies' are followed, ranges resolve independently, and a node budget can truncate the walk. One small gap: it doesn't state auth or rate-limit expectations for OSV.dev calls.

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?

Front-loaded with purpose and key caveats, and the bullet list is dense with operational warnings rather than filler. It is longer than average, but nearly every sentence carries a decision-relevant caveat, so little is wasted.

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 graph-walking tool with an output schema, the description points directly at the meaningful output fields (summary, vulnerablePaths, nodes, truncated) and pre-empts the two highest-risk misinterpretations: unscanned nodes and truncation. Nothing needed to call or correctly read it 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%, so the baseline is 3, but the description adds real interpretability: it clarifies that maxDepth bounds registry calls/timeout, that nodes resolve independently rather than mirroring npm's hoisting, and that version accepts ranges. It mostly reinforces rather than extends the schema's own parameter text.

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 (walk dependency trees), resource (root packages), and external action (check against OSV.dev), plus the outcome (vulnerabilities several levels down surface). It explicitly contrasts with batch_query_vulnerabilities, so an agent can distinguish it from siblings 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?

Gives an explicit alternative with the selecting condition: 'Use batch_query_vulnerabilities instead when you already have a flat list of exact versions (faster, no graph walk).' It also directs how to consume results, telling the agent to read summary first and use vulnerablePaths for the 'which dependency pulled this in' question.

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 cover the safety profile (readOnly/openWorld/non-destructive), and the description adds substantial behavior beyond them: fetch order and lockfile fallback, monorepo merging (up to 50 members), concrete caps (3,000 entries, 100 detail packages, 10 tarball scans, 5 high-risk), how 'coverage.complete: false' / 'PARTIAL AUDIT' should be interpreted, and escalation/cost warnings.

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?

It is long, but the first sentence front-loads the purpose and the key architectural fact, and the remaining detail is organized under a 'What it checks' heading. The density is justified by the tool's complexity, though a few clauses about output fields could be trimmed since an output schema exists.

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 high-complexity, multi-parameter tool with a nested policy object and an output schema, the description is complete: it explains coverage semantics, cap behavior, overflow handling, and cost so an agent can call it and interpret results responsibly even though return structure itself is delegated to the output schema.

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 schema already documents ref, policy, includeDevDependencies and includePeerDependencies in detail. The description largely restates these (default branch vs ref, peer skip, default policy), adding only a small amount of meaning such as the pointer to warnings for excluded peers, so the 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 (audit) and resource (a GitHub repository's npm dependencies) with a defining constraint — it works from a URL with 'no pasted files needed'. This clearly distinguishes it from file-based and lower-level sibling 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?

Gives strong usage context ('no pasted files needed', use a repo URL) and an explicit when-not ('the most expensive tool here — do not call it in a loop across many repos'). It references check_license_compliance for policy shape but never names an alternative tool for narrower single-concern queries, so routing guidance is clear but not exhaustive.

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?

Goes well beyond the readOnly/openWorld/non-destructive annotations: automatic chunking, deduplication via uniqueVulnerabilityCount, npm alias resolution, and explicit warnings that 0-counts can mask unresolved packages, nonexistent versions, deprecated/abandoned/typosquat packages, and lockfile tampering (nonRegistryHost, identityMismatch). This is exactly the extra context annotations cannot carry.

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

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

Front-loads purpose, then a tightly scoped bullet block; each caveat addresses a specific false-positive risk, so most sentences earn their place. Minor redundancy remains, e.g. enumerating finding fields (severity, summary, CVE aliases, fixedVersion, isMalware) that the output schema already documents.

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 high-complexity batch tool with two mutually exclusive input modes and subtle failure modes, the description covers input selection, chunking behavior, and the interpretation pitfalls an agent would otherwise misread as clean results. An output schema exists, so its coverage of return values is a bonus rather than a necessity.

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 already 100%, so the baseline is 3, but the description adds real meaning: an entry with no version is checked against every historical version, ranges/tags cost an extra lookup, and includePeerDependencies surfaces ignoredPeerDependencyNames. It enriches rather than merely restates 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?

States a concrete verb, resource and scope: 'Check a whole npm dependency inventory against OSV.dev in one call.' The batch framing plus 'no per-package follow-up is needed' implicitly distinguishes it from query_vulnerabilities, but the sibling is never named, so the routing contrast is left to inference.

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?

Gives clear operational context: use `packages` OR `content` (not both), large inventories are chunked automatically, and peerDependencies are skipped unless opted in. However it never explicitly says when to prefer this over query_vulnerabilities for a single package, and the 'Before calling anything clean' block is output-interpretation guidance rather than selection 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 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 cover the safety profile (readOnly, openWorld, non-destructive), and the description goes well beyond them: it explains the scoring model (cluster weighted by count and downloads, dampened for single-scope monorepos, diminishing returns for multiple clusters), discloses hard limitations (index lag, 250-package relevance-ranked cap, resultsTruncated/totalPackagesFound, lastPublished only covers latest version), and interprets output fields.

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?

Front-loaded with the core action and the attack pattern it detects, then limitations. Every sentence carries information, though the density is high and some field explanations (avatarUrl proxying) are marginal for tool selection.

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 heuristic-scoring tool, the description is thorough: it defines the detection model, the caveats that affect interpretation, and the auxiliary output URLs. An output schema exists, yet the added interpretation of scores and truncation flags is exactly the context an agent needs to act on results.

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 parameters are self-documenting, so baseline is 3. The description adds real value by clarifying that results are 'capped at 250 packages ranked by relevance, not recency' and that the limit is 'most-downloaded first' while totals still cover everything found — semantics the schema alone 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?

States a specific verb and resource ('lists the packages npm's maintainer:<username> search index returns') plus the analytical goal (detecting a tight publish-time cluster). It explicitly distinguishes itself from the sibling check_maintainer_changes by naming it as the natural predecessor, so an agent can route between them 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?

Gives clear context for use ('Natural follow-up to check_maintainer_changes: call this with a newly added maintainer's username') and names the alternative tool and trigger condition. It stops short of explicit when-not-to-use guidance, but the operational trigger is 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?

Annotations already cover the read-only, non-destructive, open-world profile, but the description goes well beyond them: it enumerates the four specific red-flag patterns, explains why the post-release change case is more urgent, covers the GitHub repository checks, and honestly caveats that findings are 'signals to verify, not proof of compromise'.

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?

Front-loaded with purpose and routing in the first two sentences, then a numbered flag list that is genuinely informative rather than padding. It is on the long side for a single-parameter tool, but each section (flags, repo checks, follow-up, caveat) earns its place.

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 needn't explain return values, and it doesn't try. Given the open-world security domain and the ambiguity of the findings, the description supplies exactly the framing an agent needs: what signals mean, how to chain tools, and the verification caveat.

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?

Only one parameter and schema coverage is 100%, so the schema already carries the name format and constraints. The description adds the data-source context (packument) but no additional syntax or edge-case meaning for the parameter itself; 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?

States a specific verb ('Reconstruct who has controlled an npm package and when') and the exact data source (the packument, per-version maintainer lists). It explicitly separates itself from siblings get_package and check_package_provenance by naming the question it answers ('who controls this package, and did that change recently').

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?

Gives an explicit when-to-use framing ('the who controls this package, and did that change recently question') and names the alternatives for the adjacent questions (get_package, check_package_provenance). It also prescribes a concrete follow-up workflow with check_maintainer_blast_radius when a maintainer flag fires.

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 readOnlyHint/destructiveHint, the description discloses the heuristic nature, the three check strategies, the exact limitation that Sigstore is not cryptographically re-verified, and the anomaly logic. There is no contradiction with 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 front-loaded and every sentence contributes, but it is a dense, long paragraph that could be tightened or bulleted for quicker scanning. No filler, yet it is heavier than the minimum viable definition.

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 annotated read-only behavior, an output schema, and fully described parameters, the description still adds the missing edge cases: no-provenance versions, best-effort tag matching, and what counts as an anomaly. Nothing needed for correct invocation is absent.

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 the exact package name and the optional version with 'omit to use the latest published version'. The description adds context about source-repo fetching and tarball diffs but no additional parameter-level syntax or format details.

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 enumerates three distinct checks, making the tool's job unmistakable. It also differentiates it from get_package/get_package_version by positioning those as basic-info prerequisites and this tool as the publish-integrity-risk assessment.

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 instructs the agent to use get_package/get_package_version first and says to use this tool specifically for publish-integrity risk. It also states when a result should not be interpreted as malice ('bare absence is never scored on its own'), giving clear when-to-use and when-not-to-conclude 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 cover safety (readOnly, non-destructive, open-world), and the description still adds substantial behavioral context: rejection semantics, the weighted scoring inputs, the rule that deprecated/typosquat-flagged candidates can never be picked, and confidence derived from score gap. The main caveat section on vulnerabilityCheckFailed and found:false further qualifies trust in results. It falls short of 5 only because failure/auth/rate-limit conditions beyond those two flags are not addressed.

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?

Front-loaded with purpose, constraints, and the sibling pointer in the first sentence, then organized by output concern. It is dense but each sentence carries information; the long per-candidate enumeration is the one place that could be tightened.

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?

Output schema exists, yet the description still orients the agent on the shape and trustworthiness of results (differentiators, recommendation.pick, rationale, confidence, partial installSize sums). For a single-parameter comparison tool this is more than sufficient.

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 single parameter is fully documented in the schema, so baseline is 3. The description adds meaning the schema does not: duplicate names are rejected and names that cannot be resolved stay in candidates with found:false and resolutionError, which clarifies what values are acceptable and how they behave.

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 ('Compare 2-5 candidate packages ... side by side and get a deterministic pick') with scope (same job) and an example. It is clearly distinguishable from search_packages, which it explicitly routes to for shortlist building.

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?

Gives explicit preconditions and exclusions: 2-5 names, more than 5 rejected rather than truncated, duplicates rejected, and 'Use search_packages first if you have no shortlist.' It also names analyze_install_script as the deeper alternative for install scripts.

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 read-only/non-destructive, yet the description adds substantial behavioral depth: transitive-only changes are caught via full resolved graph, npm aliases are followed, only up to 100 added/changed packages are inspected in detail, and each flagged field (installScriptIntroduced, sourceIntegrityChanged, identityMismatch, vulnerabilityDelta) is explained with its semantics. This goes well 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?

Front-loaded core purpose followed by clearly scoped bullet points for each reported field, each sentence carrying real semantic content. It is dense and re-explains some return fields despite an output schema existing, but the structure keeps it navigable.

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-snapshot diff tool, the description covers formats, edge cases, per-field meaning, project-level checks, and the comparisonNote caveat, while the output schema handles return structure. An agent has everything needed to invoke and interpret 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 coverage is 100%, so the schema already documents both params; the description adds the practical framing that the two snapshots represent before/after (e.g. a PR) and that formats are auto-detected and may differ. This is modest added meaning over the schema's own text.

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?

Opens with a specific verb+resource: compare two snapshots, listing all supported formats (package.json, package-lock v1-v3, yarn.lock, pnpm-lock.yaml) and stating the output (added, removed, changed packages). This is unmistakable against siblings like analyze_transitive_dependencies or compare_packages.

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?

'Ideal for a CI gate' names a concrete usage context, and it routes the agent to analyze_install_script for script-body inspection, clarifying the boundary of this tool. It stops short of explicit when-not conditions, but the alternative reference 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 cover the safety profile (readOnly, non-destructive, openWorld), and the description adds substantial behavior beyond them: GHSA→CVE resolution via OSV.dev before KEV/EPSS scoring, automatic malware detection (MAL-* / CWE-506) forcing remove-now, carry-through of `isDirect`/`fixAvailable`/`fixTarget`, and the limitation that only the first advisory per package is ranked. It also explains the consequence of skipping resolution ('would silently degrade most findings to severity-only ranking'), which is exactly the kind of non-obvious trait an agent needs.

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 purpose is front-loaded in the opening clause, and the dense parentheticals (malware detection rules, fixTarget semantics, unsupported package managers) each carry information an agent would otherwise lack. The cost is a single unbroken paragraph of run-on sentences, which hurts scanability even though little of the content is redundant.

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 input, a full output schema, and rich annotations, the description covers everything material: supported and unsupported input formats, the enrichment pipeline, the ranking buckets, the multi-advisory caveat, and fallback tools. Output values (e.g. `ghsaResolvedToCveCount`) are appropriately left to the output schema.

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?

Single required parameter with 100% schema description coverage, so the schema already documents the accepted JSON shapes and the description does not need to restate them. The description does add useful framing (the content is raw stdout, and no manifest/lockfile content is required), which is slightly more than the baseline for a fully-documented single-param tool.

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+resource (parse raw `npm audit --json` output and rank findings for remediation) and explicitly scopes the accepted input formats (npm 7+ `{vulnerabilities}` vs legacy npm 6 `{advisories}`). It draws a precise boundary against `prioritize_remediation` ('the same ranking prioritize_remediation exposes for hand-built finding lists') and against the yarn/pnpm case, so an agent can distinguish it from every relevant sibling.

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?

Gives explicit when-to-use (you have raw npm audit JSON and do not want to re-paste package.json/lockfile) and when-not-to-use with the named alternative ('`yarn audit --json` and `pnpm audit --json` ... are not supported — use batch_query_vulnerabilities'). It also routes the multi-advisory-per-package case to `query_vulnerabilities`. Nothing about tool selection is left to inference.

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?

Adds substantial behavior beyond the readOnlyHint/openWorldHint/destructiveHint annotations: discloses that OSV.dev and registry calls occur, clarifies VEX analysis.state 'in_triage' is an unreviewed automated finding (not an exploitability claim), explains SPDX 2.3 has no vulnerabilities array so externalRefs are used, and states the transitive dependencies[] graph is intentionally omitted rather than fabricated. 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?

Front-loaded with the core purpose and format details in the first sentence, and every subsequent sentence carries behaviorally meaningful information. However, it is a dense wall of text across four long paragraphs that could benefit from structural separation; the density is justified by tool complexity but the length is at the upper edge.

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?

Highly complete for a complex 10-parameter tool with nested objects and an output schema: it explains output-format differences (CycloneDX vulnerabilities[]/licenses vs SPDX externalRefs/licenseDeclared), enrichment and policy options, intentional omissions, and cross-tool parameter reuse. 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?

Schema coverage is high (90%), but the description still adds value: enumerates the content formats (package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, CycloneDX/SPDX JSON) beyond the schema, documents the 100-item cap on packages when includeLicenses is on, cross-references the policy param shape to check_license_compliance, and explains peerDependencies exclusion default and includeDevDependencies ignoring behavior — details the schema omits.

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: 'emits a spec-valid CycloneDX 1.6 or SPDX 2.3 JSON document' with an explicit format choice and default. No sibling tool generates SBOMs (siblings cover vulnerability queries, license checks, remediation), so it is cleanly distinguished from all alternatives.

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?

Gives clear contextual guidance: references the shared input shape with batch_query_vulnerabilities, explains when to skip enrichment passes (includeVulnerabilities/includeLicenses=false for speed), when to set includePeerDependencies (when an SBOM must be complete), and the content-vs-packages exclusivity. It lacks an explicit 'don't use when' exclusion, but for a generation tool the usage contexts are well covered.

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?

Despite annotations (readOnlyHint=true, openWorldHint=true, destructiveHint=false) already covering the read-only profile, the description adds substantial behavioral disclosure: the automatic MITRE fallback for unscored CVEs (`source: "mitre"`), the precise nullable-field semantics (`kev`/`epss` null means 'unknown' via `kevCheckFailed`/`epssCheckFailed`, not 'confirmed absent'), the distinction between batch EPSS failure vs per-CVE KEV failure, and the shared NVD rate limit prompting retries. This goes well beyond what annotations convey.

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 core purpose is front-loaded in the first sentence, and the dense follow-on sentences earn their place given the tool's complexity: dual lookup/search modes, nullable-field error semantics, fallback routing, and rate limiting all need explanation. It is verbose, and the educational aside about CVSS measuring impact vs likelihood is slightly extraneous to tool invocation, preventing a 5, but nothing is 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, 0 required, an output schema, and annotations, the description covers every operational concern an agent needs: mode selection, sibling routing, fallback behavior, null/error-flag interpretation, rate-limit handling, and ecosystem scope. With the output schema present, the description rightly does not need to explain return values. Nothing material 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 adds value beyond the schema by explaining parameter interplay: that cveId supersedes search filters, that keywordSearch (e.g. a package name) should be used to narrow broad ecosystem-wide search results, and that severity filtering alone is a weaker prioritization signal than the returned EPSS score. This crosses the baseline into genuinely helpful parameter guidance.

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: 'Look up authoritative NIST NVD data for one exact CVE ID... or browse/search NVD by keyword, CVSS severity, CWE, or a publication-date range.' It explicitly distinguishes itself from siblings: 'NVD is NOT npm-scoped — unlike query_vulnerabilities/get_latest_advisories' and 'prefer get_latest_advisories for npm-specific browsing.' An agent can tell exactly what this tool does and how it differs from its siblings.

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 and when-not-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 names the alternative (query_vulnerabilities/get_latest_advisories) and explains the ecosystem-scope reason for choosing the sibling.

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?

Adds substantial behavior beyond the annotations: withdrawn 'Duplicate Advisory' records are excluded from browse results so a page may hold fewer than 30 entries, yet an exact GHSA/CVE lookup still returns them with withdrawnAt set and they should be treated as retracted. It also discloses the ID-scheme split (MAL-/OSV vs GHSA) and the opaque-cursor pagination contract.

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?

Front-loaded with the browse summary before the source breakdown, and nearly every sentence carries new information (source distinctions, returned-flag behavior, pagination). It is a single dense paragraph with some run-on phrasing, keeping it from a 5.

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, return values needn't be described, and the description still covers source selection, filter applicability, withdrawn-record handling, and pagination. An agent has everything needed to invoke this 8-parameter tool 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 coverage is 100%, so baseline is 3, but the description adds real meaning: which sources each filter applies to (category and severity reviewed-only, malware/osv carry no CVE or meaningful CWE), and that ghsaId/cveId perform an exact single-advisory lookup. This goes beyond the per-field schema text.

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: 'Browse recently published npm security advisories and known-malicious-package findings,' and breaks that down into three named source types. It is very clear on scope, but never explicitly contrasts itself with overlapping siblings such as get_cve or query_vulnerabilities, so an agent must infer the boundary.

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?

Gives strong selection guidance for the type parameter and the reviewed/malware-only constraints on category, severity, and ID lookup, plus when a result may be withdrawn. It stops short of explicit when-to-use-this-vs-alternative routing against siblings like get_cve, which also does advisory lookup.

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 read-only/open-world safety, but the description adds substantive behavior: the reliance on an undocumented search index endpoint, that counts distinguish currently-maintained vs. revoked packages, that avatarUrl is a proxied Gravatar and can be null, and that npmProfileUrl is the authoritative record. This is context an agent could not get from annotations or 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?

Dense but front-loaded, leading with the core behavior before the sibling disambiguation. Some clauses (e.g., the parenthetical about the missing registry endpoint) are lengthy, but each sentence carries distinct information rather than restating structured 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?

Even though an output schema exists, the description proactively explains the aggregate fields and null behavior, and it covers scope, source, and sibling routing. Nothing needed to call the tool 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 coverage is 100%, so baseline is 3. The description adds value by explaining that limit affects only the returned list ('totals still cover every package found'), clarifying the interaction between the limit parameter and the reported aggregates.

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+resource ('given an npm username, returns every package...') plus the exact data source (the maintainer:<username> search index) and what aggregates come back. It explicitly differentiates itself from check_maintainer_blast_radius, so an agent can route correctly 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?

Explicit when/when-not: it states it does NOT run the publish-cluster/compromised-account detection and names check_maintainer_blast_radius for security reads. It also describes a concrete workflow pairing with check_maintainer_changes, covering the main alternative.

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?

Goes well beyond the readOnly/openWorld annotations: it discloses the vulnerabilityCheckFailed failure-mode trap (false boolean is not confirmation), that topPackagesRank is a periodic snapshot not live data, that tiers are deterministic rule-based labels, and that typosquat flagging only applies when the name is obscure. These are non-obvious behavioral traits an agent could not infer from structured fields.

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?

Front-loaded with the core purpose and field list before caveats, and every clause ties to a real output signal. It is a single dense block that is somewhat hard to scan, but given the breadth of return fields the length largely earns its place.

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?

An output schema exists, yet the description still adds interpretive context (vulnerability failure semantics, snapshot staleness, maintenance interpretation). Combined with annotations covering the safety profile, 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?

Only one parameter (name) at 100% schema description coverage, so the schema already documents that it must be an exact package name including scoped names. The description adds no format or syntax detail beyond the schema, so 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 (Fetch) and resource (npm registry metadata for a package) and enumerates the returned signals. An agent can clearly distinguish this broad package-profile tool from narrower siblings like get_package_version without opening either 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?

Provides explicit routing: 'use get_package_version or query_vulnerabilities to check a specific older version instead.' It also advises reading deprecated/maintenanceSummary before recommending, and notes the vuln check targets only the latest version. It does not cover when to prefer siblings like compare_packages or search_packages, so it falls short of full when/when-not coverage.

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 the safe read-only, open-world profile, yet the description goes further: it explains the meaning of isVulnerable, highestSeverity, severity, summary, and fixedVersion, and critically discloses a failure mode most tools hide — that vulnerabilityCheckFailed:true means the OSV query failed and the answer is unknown, not confirmed clean. That is exactly the kind of nuance structured fields cannot convey.

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 with what the tool returns, then the when-to-use guidance, then the failure-mode caveat. It is dense but every sentence carries information an agent needs; the only slight redundancy is restating field names already visible in the output schema.

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 explain return values, yet it crisply maps the key fields and closes the loop on the ambiguous failure case. For a read-only, open-world lookup tool, nothing an agent needs to call it correctly or interpret its output 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%: both name (exact npm package name) and version (exact version or dist-tag, semver ranges unsupported) are fully documented in the schema. The description reinforces 'exact version' but adds no syntax or format detail beyond what the schema already provides, so the 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?

The description states a specific verb and two distinct resources: fetches registry metadata for one exact version AND checks that version against OSV.dev for vulnerabilities. It explicitly scopes the tool to 'one exact version' and contrasts it with 'the latest release', which separates it from get_package and the bulk query siblings.

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?

'Use this to check a version pinned in a lockfile rather than the latest release' gives a clear when-to-use condition and implies the alternative to get_package. It stops short of naming a sibling tool explicitly or stating when NOT to use it (e.g. for ranges), though the schema note about unsupported semver ranges partially covers that.

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?

Annotations cover the safety profile (readOnly, non-destructive), and the description adds substantial behavior the annotations cannot: the full tier taxonomy (remove-now/patch-now/patch-soon/scheduled/monitor), the inputs that drive each tier (KEV, EPSS ≥10%, malware detection via MAL-*/CWE-506), and a failure-mode output (malwareCheckFailedAdvisoryIds). This is unusually rich behavioral disclosure.

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?

Front-loaded with purpose, then a clearly labeled 'How the tier is decided' block, then caveats. Structure is excellent. It is somewhat long and the malware/remove-now rule is restated in both the tier bullets and the schema, but no sentence is wasted relative to 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?

For a tool with an output schema (so return shape needn't be explained) and full schema coverage, the description supplies everything an agent needs: what it consumes, how each tier is derived, the meaning of the output tiers, and explicit guidance on how NOT to interpret them. Nothing material 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%, so the per-field baseline would be 3. The description goes beyond the schema by explaining how fields interact with outcomes — findingType/advisorId triggering remove-now, EPSS being the primary signal and severity the fallback, and the 200-item cap. That cross-field semantic layer is real added value over the schema's per-property text.

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 (rank) and resource (vulnerability findings) with explicit scope: it consumes output other tools already returned, and it names those siblings (batch_query_vulnerabilities, query_vulnerabilities, etc.). An agent can tell it apart from the query tools it depends on without opening either 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?

Explicitly says this operates on findings 'other tools already returned' and lists them, so the agent knows not to call it for fresh scanning. It also gives a strong when-NOT-to-use caveat: the tier is a fix-order across a backlog, not a severity verdict or merge gate, with concrete misuse warnings (don't call monitor findings 'low severity').

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?

With readOnlyHint/openWorldHint already declaring the safety profile, the description still adds real behavioral context: it enumerates the response fields (isVulnerable, highestSeverity, severity, summary, CVE aliases, fixedVersion), discloses the npm-registry cross-check and the packageExists/existenceCheckNote flag, and explicitly documents the non-obvious non-error behavior when a package is unpublished/yanked. This is richer than the annotations and prevents a plausible misreading of isVulnerable:false.

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 purpose and return shape are front-loaded well, but the middle passage about registry misses is long and restates the same point twice ('does NOT discard already-fetched OSV data' vs. 'data must still be reported, not hidden behind a 404'). It reads as defensive prose rather than tight specification.

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 four-parameter read tool with annotations and an output schema, nothing needed to call it correctly is missing: scope, version semantics, registry cross-check, and the not-found edge case are all covered. Return-value details are summarized rather than required, which is acceptable given the output schema exists.

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 schema already documents name/packageName aliasing, version format rules, and the ecosystem default. The description adds the motivating intent for the version parameter (lockfile safety check) but no format or behavioral detail beyond the schema, so the 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?

States a specific verb+resource (query OSV.dev for known vulnerabilities) and the exact scope (npm package, optionally one exact version), which cleanly separates it from siblings like batch_query_vulnerabilities and get_cve. The parenthetical about lockfile version checks makes the intended granularity unambiguous.

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 says when to use it: 'Use before recommending, installing, or upgrading a package,' and gives a concrete scenario for the version parameter. It does not name the alternative sibling tools (e.g. batch_query_vulnerabilities for multi-package sweeps, get_cve for a direct CVE lookup), so routing is clear but not fully disambiguated.

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 state readOnly/openWorld/non-destructive; the description adds substantial behavioral context beyond them — the exact result fields, that topPackagesRank is a non-live snapshot, that popularityTier/maintenanceTier are deterministic rather than model-generated, and how to interpret 'very-low'/'stale'/zero-dependents packages. It also flags the possibleTyposquatOf red flag and warns against silently filtering, which is genuinely operational guidance.

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?

Purpose is front-loaded in the first sentence and every subsequent clause carries interpretive value. It is dense and runs long as a single block, with the get_package follow-up advice buried mid-paragraph, so it loses a point on structure rather than on waste.

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?

An output schema exists, so return values need not be explained, yet the description still supplies the interpretation layer an agent actually needs (how to read tiers, dependents, typosquat flags). For a two-param search entrypoint, nothing required to call or use it 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 query and limit are already documented in the schema (including the default 20 / max 50 for limit). The description only paraphrases 'by name or keywords' and adds no extra syntax, format, or edge-case meaning, so the 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?

Opens with a specific verb+resource: 'Search the npm registry by name or keywords.' It is clearly distinguishable from siblings like compare_packages or get_package, and it explicitly frames itself as the candidate-discovery step that feeds get_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?

Gives clear usage context: use the returned tiers/dependents/typosquat signals rather than name recognition to judge candidates, then 'call get_package on your shortlist for install-script risk, TypeScript support, and GitHub stars before recommending one.' It also advises calling out typosquat hits instead of filtering them. It stops short of naming an explicit alternative search tool or a when-not-to-use condition.

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 readOnly/openWorld/non-destructive; the description adds substantial behavior beyond that: batch failure semantics (a name that can't resolve returns `fetchError` rather than failing the batch), the six-value riskTier vocabulary, what triggers `do-not-upgrade` (known malware or npm delisting a release OSV still flags), and nuances like a new `prepare` script never running on a registry install.

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?

Front-loaded call instructions in the first paragraph, then a clearly headed 'What it checks' list and a result summary — well organized and scannable. It is on the long side and some registry-signal detail borders on documentation rather than selection guidance, keeping it just short of a 5.

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?

Despite a rich output schema, the description still names the single result field (riskTier), its enum values, and the accompanying `reasons`, so an agent knows what to expect. Combined with the check list and failure mode, nothing needed to invoke or interpret the 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?

Schema coverage is 100% and the schema already documents aliases, ranges, dist-tags and mutual exclusivity, so the baseline is 3. The description still adds value the schema lacks: the prioritize_remediation field mapping, the 1-100 batch size rationale, and 'omit target for latest' framing in the entry sentence.

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: simulate whether upgrading a package from current to target version is safe before running npm install. It explicitly distinguishes itself from siblings by framing it as a fast pre-check ('not a substitute for release notes on a major bump') and naming prioritize_remediation as the upstream tool it complements.

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?

Gives explicit invocation conditions (before npm install), tells the agent how to feed prioritize_remediation output straight in (packageName/currentVersion/fixedVersion), and documents both the single-item and batch forms with their mutual exclusivity. It also states the boundary of applicability — no changelog or source diffing.

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 and non-destructiveness, but the description goes far beyond that. It discloses critical behavioral nuances: unverifiable candidates are excluded rather than defaulting to safe, the source's vulnerabilityCheckFailed flag is the real signal (since isLatestVersionVulnerable returns false as a placeholder), and the ranking/filtering criteria. This is essential for an agent to interpret results correctly.

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 opens with the core purpose, then explains the methodology, then the best-use case, and finally a crucial caveat about vulnerability-check failure. The structure is logical and front-loaded with the primary action, making it easy for an agent to parse and apply.

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?

Despite the tool being read-only and having an output schema, the description covers exceptional cases like OSV check failures and candidate exclusion. It explains what the output contains (short list with whySuggested notes) and why certain candidates are never suggested. For a tool with this complexity, the description is exceptionally complete and leaves no critical gaps 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 description coverage is 100%, so the baseline is 3. The description does not add much parameter-specific detail beyond what the schema already provides. It references the 'name' parameter as the source package and mentions the 'limit' implicitly in 'Max suggestions,' but these are already in the schema. The description's value is in process explanation, not parameter meanings.

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 the exact purpose: given a problematic package, suggest better-maintained alternatives in the same category. It clearly distinguishes this from sibling tools by highlighting the category-matching and safety-filtering behavior, and explicitly frames it as turning a 'don't use' warning into a replacement 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?

The description includes 'Best for turning a ... warning into an actionable replacement shortlist,' which gives clear usage context. It also explains the internal decision logic but does not explicitly name alternative sibling tools or say when NOT to use it (e.g., when you just want to search packages). Still, it provides enough situational guidance for an agent.

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