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 already declare readOnly/openWorld/non-destructive behavior, so the description had a lower bar but exceeded it substantially. It discloses npm alias following to actualName, resolutionError producing isVulnerable: null rather than false, independent semver max-satisfying resolution per branch, and truncation via truncated/truncationNote. This gives the agent a faithful model of edge-case behavior.

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-loads the core purpose and then systematically covers return fields, edge cases, limits, and alternatives. Every section earns its place given the tool's complexity, and there is no filler or redundant restatement of exact schema text.

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 restate return structures, yet it still names key output fields like summary, vulnerablePaths, nodes, and truncated/truncationNote with enough interpretation to use them correctly. It also covers npm aliases, resolution errors, traversal limits, and when to use a sibling tool, making the description highly 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?

The input schema already covers both parameters with 100% description coverage, including maxDepth default and packages format. The description adds valuable real-world grounding by referencing package.json dependencies, depth defaults and caps, version range semantics, and alias resolution behavior, going modestly 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 states a specific verb-resource pair: recursively resolves dependency graphs and batch-checks resolved packages against OSV.dev. It also distinguishes itself from a flat-list alternative by explicitly mentioning transitive vulnerabilities and naming batch_query_vulnerabilities as the sibling it is not.

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: prefer batch_query_vulnerabilities when you already have a flat list of exact packages, and use this tool when you need graph traversal across transitive dependencies. It also states scope boundaries such as only following the dependencies field and not emulating npm hoisting, which further clarifies when results are appropriate.

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 say readOnly, openWorld, and non-destructive; the description adds extensive behavioral detail: lockfile priority order, default-branch fetching, automatic monorepo detection and merge caps, the 100/10/5 package limits, deep vs light scan distinction, peer-dependency exclusion default, and a detailed cost/fan-out estimate. This goes far beyond the annotations without contradicting them.

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 very long, but it is a complex aggregate tool and the length is mostly dense, non-redundant detail. The lead sentence carries the core purpose, and later sections organize around monorepo handling, scan tiers, cost, and peer deps. It could be broken into cleaner paragraphs, but every sentence adds 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, return values need no description. The description covers input semantics, behavior, limits, defaults, excluded groups, and cost implications, leaving no obvious decision an agent needs to make before invoking 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?

Although the schema already covers all parameters, the description adds critical semantics not in the field docs: the default ref behavior, default policy meaning, lockfile-selection consequences for includeDevDependencies, yarn.lock's inability to distinguish dev deps, and the meaning of peer-dependency exclusion. This is exactly the context an agent needs to set parameters 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-resource pairing (audits a GitHub repository's npm dependencies via URL) and immediately enumerates the exact pipelines it aggregates, naming the sibling tools it subsumes. This makes it unmistakable from analyze_install_script, batch_query_vulnerabilities, etc.

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 frames the tool as a single-call aggregator of the individual sibling pipelines ('no copy-pasting file contents required') and warns it is the most expensive tool, advising against looping across many repos. It does not spell out the inverse direction ('use the individual tool when you need only one check'), but the contrast is strong enough.

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 covered. The description goes far beyond annotations: it discloses chunked querying behind the scenes, npm registry cross-checking with caps, silent-zero pitfalls, unversioned query semantics, signals null behavior, source/identityMismatch tamper detection, alias following, peerDependency exclusion, and advisory over-counting. This is exceptionally 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?

The description is extremely long and dense, with many clauses packed into single sentences. It is front-loaded with the core purpose, but the sheer volume of caveats and edge cases makes it hard to parse. Every sentence earns its place in terms of content value, but the structure is not concise; it reads as a wall of text rather than a scannable 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?

Given the tool's complexity (4 params, 100% schema coverage, output schema present, 20 siblings), the description is remarkably complete. It covers input formats, output fields, edge cases, security implications, and cross-tool routing. Nothing an agent needs to call this correctly is missing; the output schema handles return-value 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 description coverage is 100%, so the schema already documents all four parameters. The description adds substantial meaning beyond the schema: it explains the content formats, the packages/version semantics (unversioned queries, range resolution), the includePeerDependencies default behavior, and the includeDevDependencies scope. It doesn't add much about the boolean parameters beyond what the schema says, but the coverage is already complete.

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 ('Query OSV.dev for known vulnerabilities across a whole npm dependency inventory at once') and immediately distinguishes the batch mode from single-package alternatives. It names the two input modes (packages list or raw content) and the sibling tool query_vulnerabilities is implicitly differentiated by the batch/inventory framing.

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: batch inventory scanning vs single-package queries, and repeatedly tells the agent what NOT to do (don't read vulnerabilityCount:0 as clean for unresolved names, don't report unversioned results as vulnerable, don't treat range-resolved as durable). It also names the sibling get_package/get_package_version for confirmation and query_vulnerabilities for single-package queries.

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 establish it as a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=true), yet the description adds substantial depth: the scoring model, damping of single-scope/monorepo clusters, diminishing returns for multiple clusters, and hard limitations (index lag, 250-package relevance cap exposed via resultsTruncated/totalPackagesFound, lastPublished only reflecting latest version). This is genuinely beyond what the 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 and virtually every sentence carries behavioral or interpretive information. It is long and dense, and it spends several sentences explaining output fields (isCurrentMaintainer, avatarUrl, npmscanUrl, npmProfileUrl) that an output schema already covers, which is the main conciseness cost.

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 single-parameter read tool with an output schema present, this covers everything an agent needs: what is scored, what is not a signal, damping rules, index limitations, and the recommended workflow relationship to a sibling. Return values need not be re-explained because 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%, and the single parameter is fully documented in the schema itself (exact npm username, not email/package/scope). The description adds no format or syntax detail beyond 'given an npm username,' so the baseline 3 applies when the schema does the heavy lifting.

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 and scores them for a tight publish-time cluster signalling a compromised-account supply-chain attack. It names the concrete threat shape and distinguishes itself from related siblings by identifying itself 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?

Gives an explicit trigger: after check_maintainer_changes, call this with a newly added maintainer's username to see whether the same account touched other packages. It also advises that a large total package count alone is not a red flag, guiding interpretation. It stops short of naming an alternative to use instead when this tool does not apply.

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 declare readOnly/openWorld/non-destructive, and the description still adds substantial behavior: results are derived from packument snapshots with 'no extra API calls', it enumerates four distinct flag categories, explains the GitHub repo cross-check, and documents null semantics for ownerLogin/ownerAvatarUrl when GitHub wasn't reached. This is far 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?

It is long, but dense with distinct information: mechanism, four flag types, repo cross-check, usage routing, and follow-up. Front-loaded with the core action. The single run-on paragraph makes it harder to scan than it needs to be, and a phrase or two could be trimmed.

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 analysis tool with an output schema already present, the description covers the mechanism, every flag class, the secondary GitHub check, and how it relates to the two neighboring tools. Nothing an agent needs to decide or call 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, and schema coverage is 100% with a clear example ('lodash' or '@scope/name'). The description adds no further naming or format guidance beyond the schema, so the baseline of 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?

Names a specific verb and resource ('reconstructs a package's maintainer-change history straight from the npm packument') and immediately distinguishes itself from siblings by scoping to maintainer/ownership change rather than general health or publish integrity. An agent can tell exactly which question this tool answers.

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 routes: use get_package/check_package_provenance for general health first, use this for 'who controls this package, and did that change recently', and follow up with check_maintainer_blast_radius for the cross-package blast-radius question. It even states the limitation ('the question this tool can't answer on its own'), which is unusually strong 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 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?

Even though annotations already declare readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral detail: parallel fetching, deterministic pick that never selects deprecated or typosquat-flagged candidates, the vulnerabilityCheckFailed fallback semantics, truncation behavior for transitive install size (with truncated/sizeUnknownCount flags), and the 'found:false plus resolutionError' handling for unresolved names. These extend far beyond the annotation surface and align with the openWorldHint.

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 the core purpose and selection context, and every sentence carries information — no filler. However, it is a single dense paragraph with many nested clauses and technical caveats, which could hamper quick skimming. Breaking it into bullets would improve scannability without losing content. The density is justified by the tool's complexity, but the structure is not optimal.

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 the tool's core behavior, output highlights (downloads, tiers, install size, differentiators, recommendation), error handling (vulnerability check failures, unresolved names), and boundary conditions (duplicate rejection, truncation). Given the presence of an output schema and only one well-described parameter, an agent has everything needed to invoke it correctly. It is complete for a tool of this complexity.

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 beyond the schema by explaining that the packages should be candidates for the same job, that duplicate names are rejected, and how unresolved names are represented (found:false with resolutionError). It also links the packages parameter to the parallel enrichment and decision logic. Slightly more could be said about the exact format of names, but the description already meaningfully augments 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 states a specific verb and resource: 'Given 2-5 candidate packages for the same job ... fetches the same ... enrichment ... and returns a structured side-by-side plus a deterministic, reasoned pick.' It clearly distinguishes from siblings by referencing get_package for the underlying enrichment and explicitly naming deeper alternatives (analyze_install_script, analyze_transitive_dependencies). An agent can understand the tool's role 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?

It explicitly says when to use the tool: 'Given 2-5 candidate packages for the same job.' It also provides 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.' Additional usage rules like duplicate name rejection and unresolved name handling are clearly stated, making the boundary between this tool and its siblings 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 only convey read-only/non-destructive hints, so the description carries the full burden of behavioral disclosure. It exposes alias-following semantics, installScriptIntroduced boolean behavior, sourceIntegrityChanged, format scope differences, presence-only script detection, comparisonNote, projectLifecycleChanges, and overridesChanges, plus null-case caveats. This far exceeds what annotations provide and never contradicts them.

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 of several hundred words with no bullet points or sectioning. It front-loads the core purpose and every sentence does carry useful edge-case detail, but the lack of structure makes it hard to scan and would benefit from bullets or short sections. Acceptable for the complexity, but not concise.

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 is exhaustive for a tool of this complexity: supported formats, attack shapes, scope differences, output semantics, counters, null cases, and alternative routing are all covered. With an output schema present, return values need not be described, and even the 100-package cap is mentioned. Nothing an agent needs to invoke it correctly is missing.

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

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

Both parameters are already fully documented in the schema with their format list and auto-detection behavior, reaching 100% coverage. The description adds only marginal parameter-level meaning (e.g., before/after PR context, scope notes), most of which is tool behavior rather than parameter semantics. 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 opening sentence names the exact resource (two raw dependency snapshot files) and the specific verb (compares), and lists concrete outputs (added/removed/version-bumped). It also explicitly distinguishes itself from siblings like analyze_install_script, batch_query_vulnerabilities, and generate_sbom, 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?

The description explicitly states it is 'Ideal for a CI gate reviewing a dependency-changing PR' and gives concrete when-to-use/alternatives guidance: use analyze_install_script for deep-dive on flags, and notes that batch_query_vulnerabilities/generate_sbom exclude peerDependencies by default while this tool includes them. It even explains why a root postinstall change would be invisible without this 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 already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds rich behavioral detail: direct parsing, malware auto-detection, GHSA-to-CVE resolution via OSV.dev, and the consequence of skipping that step, plus carrying isDirect/fixAvailable/fixTarget fields. It also discloses the limitation of using only the first advisory per package.

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 first, then mechanisms, then limitations, then alternatives. It is front-loaded and well-organized. It could arguably be a 5, but the length (though justified) makes it slightly less concise than the crispest examples.

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 (two input formats, external resolution, extra fields, edge cases), the description covers all critical aspects: parsing, ranking, resolution, field semantics, limitations, and alternatives. An output schema exists, so return values are not required. 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 100%, so the parameter is already documented. However, the description adds meaningful format details (npm 7+ vs legacy npm 6 structures) beyond the schema's generic description, which helps the agent prepare valid input. Baseline 3 would be acceptable, but the extra format specificity earns a 4.

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 ('rank') and resource ('raw npm audit --json output'), and immediately contrasts it with prioritize_remediation for hand-built lists, and batch_query_vulnerabilities for yarn/pnpm. It leaves no ambiguity about what this tool does and how it differs from 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?

It explicitly says when to use (raw npm audit output) and when not (yarn/pnpm audit), naming alternatives (batch_query_vulnerabilities) and also points to query_vulnerabilities for cases where a package has multiple advisories. This is exemplary 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?

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?

Annotations cover read-only/open-world; the description adds significant context beyond annotations: the disjoint dataset semantics, different ID schemes (MAL-/OSV vs GHSA), absence of CVE/CWE in malware/osv feeds, and pagination via opaque cursor.

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 and source breakdown, then filters and pagination. Dense but each sentence carries distinct, decision-relevant information; 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?

With an output schema present, return format needn't be explained. The description compensates fully for the tool's inherent complexity: three heterogeneous datasets, ID formats, filter applicability, and pagination semantics.

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 raises it by clarifying default values, mutual applicability (category reviewed-only, severity not applicable to malware/osv), and the cursor round-trip contract ('pass nextCursor back as cursor').

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 ('Browse recently published npm security advisories and known-malicious-package findings') and immediately explains the three disjoint sources, which distinguishes it from siblings like query_vulnerabilities or get_cve.

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?

Clearly explains when each source type applies and that lookups by GHSA/CVE are reviewed/malware only. Does not explicitly name alternative sibling tools, but the source semantics provide strong usage context.

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), but the description adds meaningful context beyond them: it discloses the upstream data source (registry.npmjs.org /-/v1/search), the absence of a dedicated maintainer-list endpoint, the revoke-vs-current distinction in currentlyMaintainsCount, and the null case for avatarUrl. It stops short of describing pagination or result caps on the search index, which would matter for completeness.

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 behavior and the sibling disambiguation in the first two sentences, which is the right ordering. It is dense and long, with several parenthetical asides that cost readability, but no sentence is truly 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 single-parameter read tool with annotations covering safety, a 100%-covered schema, and an output schema, the description supplies everything an agent needs: what is returned, the data source, caveats, and when to prefer a sibling. Return-value detail is present but not required, so nothing 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 single parameter is fully documented (exact username, not email/package/scope). The description adds nothing beyond "Given an npm username," 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 (returns packages and aggregates for an npm maintainer) and explicitly distinguishes itself from check_maintainer_blast_radius, which it names. An agent can tell this is a profile/info lookup, not a security scan, 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?

Gives explicit when-not guidance ("does NOT run the publish-cluster / compromised-account detection... use that tool instead") and a concrete when-to-use trigger via its pairing with check_maintainer_changes. It routes the agent among siblings rather than leaving selection 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool's safety is clear. The description adds valuable behavioral context: explains that the topPackagesRank is from a periodically-refreshed snapshot not live, that vulnerabilityCheckFailed distinguishes unknown from clean, and that maintenanceTier and popularityTier are rule-based not model-generated. This goes beyond annotations without contradicting them.

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 front-loads the core purpose, but it is overly long and includes many enumerated details that could be summarized without losing critical guidance. The sentences are long and packed with information, making it less scannable. It earns a 3 because it does convey necessary context but lacks brevity and clear separation of ideas.

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 (returns many fields, has output schema, and handles failure modes), the description is thorough: it covers return values implicitly via field enumeration, explains failure signals, and provides guidance on interpretation. The presence of an output schema reduces the need to describe return structure, and the description fills in the nuanced behaviors.

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 coverage is 100% with a clear description of the 'name' parameter (exact package name, with examples). The description reinforces the importance of the package name but does not add further parameter-specific details beyond what the schema states, so a slight deduction is reasonable.

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 npm registry metadata and enumerates a comprehensive list of fields, including version, install scripts, maintainers, license, download trends, vulnerability status, and more. It distinguishes itself from siblings like get_package_version by explicitly pointing to alternative tools for specific older version 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 provides explicit guidance on when to use this tool vs alternatives: it says to use get_package_version or query_vulnerabilities for specific older versions, and it warns to read deprecated and maintenanceSummary before recommending. It also explains the behavior of vulnerabilityCheckFailed, setting clear expectations for failure conditions.

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 set readOnlyHint, openWorldHint, and destructiveHint=false. The description goes further by detailing the failure mode of the OSV.dev query: when the query fails, isVulnerable is forced to false and vulnerabilityCheckFailed:true is the real signal. This is critical behavioral disclosure beyond annotations and prevents misinterpretation of a false negative.

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 longer than average but every sentence carries weight: purpose, key outputs, usage guidance, and failure-mode caveat. It is front-loaded with the core action and ends with the most nuanced edge case. No filler or redundancy.

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 (registry metadata + vulnerability check), the description covers the essential return fields (isVulnerable, highestSeverity, findings with severity/summary/fixedVersion) and explicitly addresses the failure case. The output schema exists, so full enumeration isn't needed. An agent has everything necessary to call it correctly and interpret results accurately.

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 both name and version are fully described in the schema. The description adds context about the use case (lockfile pins) but doesn't add parameter-specific meaning beyond what the schema already provides. 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 states a specific verb ('Fetch registry metadata') and resource ('one exact version of a package'), then adds the secondary action of checking against OSV.dev. It distinguishes itself from siblings like get_package (latest release) and query_vulnerabilities by explicitly targeting exact pinned versions. No ambiguity.

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 when-to-use: 'Use this to check a version pinned in a lockfile rather than the latest release.' This clearly routes the agent away from using it for latest versions, implicitly pointing to alternatives. It also explains how to interpret edge-case failure behavior, adding operational 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 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?

The description goes far beyond the sparse annotations (readOnlyHint, openWorldHint, destructiveHint). It discloses the full ranking logic: combination of CISA KEV, EPSS, and severity; the malware override to remove-now; the fallback to severity alone when EPSS is absent; and the deduplication of shared CVE IDs. These behavioral details are exactly what an agent needs to predict side effects and edge cases.

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 serves a purpose: it is front-loaded with the core purpose, then details the ranking signals, edge cases, and exclusions. While it is verbose, the complexity of the tool justifies the length. It could be tightened slightly by trimming explanatory asides, but overall structure is logical and easy to parse.

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 presence of an output schema (which covers return structure), and the rich annotations, the description is complete. It covers input expectations, all ranking scenarios, the malware special case, the EPSS fallback, and what the tool does not do. 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?

Although schema descriptions cover 100% of parameters, the description adds deeper semantic meaning by explaining how each parameter influences ranking (e.g., cveId 'enables CISA KEV + FIRST.org EPSS enrichment', findingType 'forces the remove-now tier regardless of score', severity 'used as a fallback/secondary signal'). It also explains the interaction between parameters, such as EPSS unavailability causing severity to become the sole signal, which is not evident from schema alone.

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 clear, specific purpose: rank a batch of vulnerability findings by fix priority. It names the input sources (batch_query_vulnerabilities, analyze_transitive_dependencies, query_vulnerabilities) and explicitly differentiates itself from siblings by stating it does NOT re-query OSV/NVD. This makes the tool's role 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?

It explicitly states when to use it: 'Given a batch of vulnerability findings already flagged elsewhere... ranks them by what to actually fix first.' It also clarifies what it does not do ('does NOT re-query OSV/NVD itself') and what the caller must supply ('pass in the severity/CVE id findings other tools already returned'). This gives clear operational guidance and excludes misuse cases.

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 hints. The description adds critical non-obvious behavior: it cross-checks the npm registry and exposes packageExists/existenceCheckNote to distinguish a nonexistent package from a genuinely clean result. It also explicitly says that a registry 404 does not discard OSV data or become an error, covering the malicious-unpublished-package edge case.

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 longer than average, but each item earns its place: core query behavior, result shape, registry cross-check, edge-case handling, and a usage directive. It is front-loaded with the primary purpose and output contract before nuanced caveats. It is dense but not 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?

For a read-only query tool with an output schema and helpful annotations, the description covers the full call context: what it checks, what it returns, how to interpret isVulnerable:false, and when to use it. The registry edge-case explanation is especially valuable and hard to discover otherwise. 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?

The input schema already covers all three parameters, so the description does not need to repeat basics. It adds useful semantic context, such as checking a lockfile-pinned version, the npm default for ecosystem, and the fact that name/version feed the registry cross-check. This is a meaningful bonus over the schema 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 first sentence states a specific verb and resource ('Query OSV.dev for known vulnerabilities affecting an npm package') and adds an explicit scope qualifier ('optionally scoped to one exact version'). The description also contrasts itself with 'a raw advisory dump,' helping an agent distinguish it from sibling tools like get_cve or batch_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 gives an explicit trigger: 'Use before recommending, installing, or upgrading a package,' which tells an agent the decision context. It also describes what the tool is not for ('not a raw advisory dump') and explains the registry cross-check behavior. It does not explicitly name sibling alternatives for bulk queries, but the context is clear enough.

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 discloses important behavioral nuances beyond the annotations: topPackagesRank is not live, labels are deterministic rather than model-generated, low-popularity/stale results are likely abandoned or squatted, and possibleTyposquatOf should be called out rather than silently filtered. This gives the agent critical interpretation guidance that readOnlyHint/openWorldHint do not 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 long but high-density: every sentence adds interpretive or routing value. It front-loads the core search action and then layers result-signal meaning, warning signs, and follow-up recommendations in a logical order. No sentences are 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 search tool feeding into a security-analysis workflow, the description covers result interpretation, caveats, red flags, and the recommended next step (get_package). The output schema handles structural return details, so the description does not need to restate them. An agent has enough context to use the tool correctly and act on its output.

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 input schema already documents query and limit, including defaults and constraints. The description only restates the query semantics ('by name or keywords') and adds no meaningful parameter-level detail beyond what the schema provides. 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 a specific action and resource: searching the npm registry by name or keywords. It goes beyond a tautology by explaining what each result contains and how the tool differs from follow-up tools like get_package. An agent can immediately understand this is the entry-point search tool among the sibling set.

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 guidance on when to use the results: use the popularity and maintenance signals rather than name recognition or READMEs, treat possibleTyposquatOf as a red flag, and call get_package on the shortlist for deeper vetting. This actively routes the agent to the correct next tool and prevents misuse.

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

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

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

Front-loaded with the core promise ('tells you whether that specific upgrade is safe ... before you run npm install') and every sentence carries signal. It is dense and long, and the batch/param guidance repeats what the schema already documents, so some trimming is possible, but the length is justified by the tool's complexity.

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

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

For a complex, zero-required-param, batch-capable tool with an output schema, the description covers the classification logic, the riskTier output, the per-entry fetchError behavior, and the cost model without needing to restate return fields. An agent has everything required to select and invoke it correctly, including the choosing between single and batch forms.

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

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

Schema coverage is 100%, so the baseline is 3 and the description must add value to earn more. It does: it spells out the mutual exclusivity of packages vs packageName/currentVersion ('not both'), clarifies that targetVersion is optional and defaults to the registry latest dist-tag, and links the fields to prioritize_remediation's output shape. This largely mirrors schema text, so it lands at 4 rather than 5.

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

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

States a precise verb+resource (simulate a dependency upgrade) and goes further to enumerate exactly what it classifies (semver jump type, deprecation, lifecycle scripts, engines.node, prerelease, OSV vulnerabilityDelta) and what it explicitly does NOT do (read changelog/source diff). It distinguishes itself from siblings both by naming prioritize_remediation as the upstream pairing and by defining its boundary as a fast deterministic pre-check rather than a full review.

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

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

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

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

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.