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?

The annotations already mark this as read-only, non-destructive, and open-world, and the description adds substantial behavioral detail beyond that: independent per-branch semver resolution, non-aborting resolution errors, skipped git/file: dependencies, deterministic summary output, and what vulnerablePaths/nodes contain. No contradiction with annotations exists.

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

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

The description is long but front-loaded: the first sentence establishes the core operation, then output-field guidance, then critical scope limits, then the alternative tool. It is structured logically and nearly every sentence earns its place, though there is minor redundancy around file: dependencies being skipped and the paragraph is dense.

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 output schema exists and the annotations cover safety, the description is remarkably complete. It tells the agent how to read the summary first, what vulnerablePaths answers, what nodes offers for deep inspection, what the resolver does and does not follow, and when to choose a sibling tool instead. Nothing essential for correct invocation 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 and the schema already documents maxDepth defaults and packages ranges, so the baseline is 3. The description adds useful parameter behavior by explaining that each version range is resolved independently per branch via npm's resolver, which can yield multiple versions of the same package, and clarifies that packages are roots for expansion, not a flat list to check.

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

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

The description clearly states a specific verb (recursively resolves), a resource (dependency graphs of direct/root packages), and an action (batch-checks resolved packages against OSV.dev). It also distinguishes itself from the sibling batch_query_vulnerabilities by emphasizing the graph-walk approach and deep, buried vulnerabilities.

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

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

The description explicitly tells the agent when to prefer batch_query_vulnerabilities instead: when checking exact packages already available as a flat list, since that is faster and avoids graph walking. It also documents limitations that affect trust in a 'clean' result, such as only following 'dependencies' and not dev/peer/optional dependencies.

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

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

The description goes far beyond the readOnly/openWorld annotations by detailing lockfile priority, workspace detection, dependency caps, deep-scan prioritization, ownership-check limits, and the large number of downstream network fetches. This is exactly the behavioral context an agent needs before invoking an expensive open-world read tool.

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

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

The description is long, but the tool genuinely has many important caps, priority rules, and cost characteristics that would be dangerous to omit. It is front-loaded with the core action and resource cost, but the dense single-paragraph format with nested clauses could be significantly easier to scan.

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 full runtime behavior: file-fetch strategy, monorepo handling, dependency caps, scan priorities, ownership-risk eligibility, and cost profile. Combined with an output schema, the agent has everything needed to invoke the tool correctly and set expectations about its price.

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?

All four parameters are already documented in the input schema with 100% coverage, so the description does not need to compensate. It adds general behavioral context around policy defaults and lockfile scope, but most of that is either already in the schema or is not parameter-specific.

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 concrete verb and resource: given a GitHub repository URL, fetch its dependency manifests and run a complete npm audit in one call. It explicitly names the sibling pipelines it aggregates, so an agent can distinguish this combined audit tool from the individual check 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?

It clearly states that this is the most expensive tool in the suite and warns not to call it in a loop across many repositories. It also names the individual sibling tools it composes, but it never explicitly tells the agent when to choose those cheaper alternatives instead of this aggregate.

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 this as a read-only, non-destructive operation. The description adds meaningful behavioral context beyond that: input normalization, chunked background queries, the 100-package upstream limit, and that each finding contains severity, summary, CVE aliases, and fixed version. No contradictions with the annotations exist.

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

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

Three dense sentences with no wasted words: the first fronts the core purpose and input options, the second explains the batch behavior, and the third specifies return-value richness. Every sentence earns its place and there is no repetition of schema content.

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 annotations, full parameter descriptions, and presence of an output schema, the description is complete for an agent to select and invoke the tool correctly. It covers both input modes, clarifies the batch limit workaround, and describes what the results contain without needing to restate 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%, so the schema already documents all three parameters and their mutual exclusivity. The description reinforces the distinction between packages and content and adds useful output context, but it does not substantially extend parameter-level meaning beyond what the schema provides, making the baseline 3 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 and resource ('Query OSV.dev for known vulnerabilities across a whole npm dependency inventory at once') and clearly signals batch behavior, distinguishing it from the sibling query_vulnerabilities tool. It also enumerates the two input modes, leaving no ambiguity about what the tool operates on.

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 frames when to use the tool: when auditing a whole dependency inventory or a large SBOM, and it explains that chunking avoids the upstream 100-package limit. However, it does not explicitly name sibling tools like query_vulnerabilities or state when the non-batch variant would be preferable, so the guidance stops just short of full exclusion criteria.

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 annotations, the description discloses important behavior: license classification categories, SPDX expression handling, policy precedence, default policy behavior, family-prefix matching, and the registry-field limitation. This gives agents a realistic model of how the tool will behave without overpromising.

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

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

The description is long and dense, but every sentence adds operational detail that would otherwise need to be inferred from examples. It is front-loaded with the core purpose before diving into edge cases, though a bit more whitespace or bullet structure could aid quick scanning.

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 complexity of the tool (nested policy object, expression semantics, default policy, exclusion behavior) and the existing output schema, the description covers all necessary context. An agent can correctly construct inputs and anticipate verdict outcomes without additional external knowledge.

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?

Even though schema coverage is 100%, the description enriches parameter meaning substantially: it explains how semver ranges are interpreted, that deny always overrides allow, how family prefixes and categories match, and what happens when policy is omitted. These are not obvious from the schema alone and directly affect how an agent should build the parameters.

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 action: check a package list against a license policy and report per-package compliance. It clearly identifies the resource (dependency list with SPDX licenses) and the verdict output, and it is distinct from the sibling tools like analyze_transitive_dependencies or query_vulnerabilities.

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

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

The description gives a clear use case: resolve license compliance for packages with an optional allow/deny policy. It also provides a notable exclusion ('does not fetch or parse LICENSE file contents from the source repository'), which helps agents avoid misusing it. However, it does not explicitly name alternative sibling tools or state conditions for choosing them.

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 far beyond the readOnlyHint/openWorldHint/destructiveHint annotations, disclosing that results are relevance-ranked and capped at 250, that lastPublished only reflects the latest version, that scope-shared clusters are dampened, that multiple clusters combine with diminishing returns, and that isCurrentMaintainer may be false because access is often revoked. These are exactly the behavioral quirks an agent needs to interpret results correctly. No annotation contradiction.

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

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

Front-loaded with a crisp purpose and then organized into mechanism, scoring rationale, follow-up, and limitations. It is long, but nearly every sentence carries decision-relevant information; minor redundancy exists around 'not a plain sum' and the chalk/debug example could be shorter, but the structure makes 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 tool with one input, rich output schema, and search-index caveats, the description fully covers invocation, interpretation, output-field semantics (avatarUrl, isCurrentMaintainer, resultsTruncated), and failure modes. An agent has everything needed to know when to call it and how to reason about the result.

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 description already covers the single parameter thoroughly (exact username, example, not email/package/scope), so the description adds no new parameter-level meaning. It consistently reinforces 'npm username' but does not explain formatting, edge cases, or validation 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 action (reverse-lookup every package for an npm maintainer) and a distinctive outcome (flag tight publish clusters) that clearly separates it from siblings like get_maintainer_profile and check_maintainer_changes. The attack-scenario framing gives an agent an immediate mental model of what the tool produces.

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 names check_maintainer_changes as the natural predecessor and instructs exactly when to call this tool: when a maintainer is newly added or fully turned over. It also explains when the tool should NOT be trusted (search-index lag, truncation), giving the agent real decision boundaries rather than vague 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?

The description goes well beyond the read-only/destructive annotations by disclosing the data source (npm packument), the method (diffing snapshots in publish-time order), no extra API calls, edge cases (changes after latest release, GitHub reachability failures), and implementation details like the avatar proxy. It sets correct expectations for when fields will be null and how ownership changes are detected.

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

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

The description is long but information-dense, with major behavioral details front-loaded and a logical flow from mechanism to flags to follow-up guidance. Some historical incident examples and avatar-proxy details could be trimmed, but they add context rather than pure 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?

Given the tool's complexity, the single-parameter schema, and the existence of an output schema, the description covers all necessary context: method, edge cases, null behavior, fallback paths, and sibling connections. An agent can decide when to invoke this tool and what to do with results without needing additional 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?

The input schema already describes the single 'name' parameter fully with exactness requirements and examples, so schema coverage is 100%. The description does not add parameter-level detail beyond the schema, which aligns with the baseline 3; no additional semantics are needed.

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

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

The description states a precise purpose: reconstructing a package's maintainer-change history from the npm packument and flagging specific red flags. It includes concrete patterns (maintainer added then publishing, full list replacement, quiet removal, post-release changes) and explicitly distinguishes itself from sibling tools by framing it as the 'who controls this package, and did that change recently' question.

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: use get_package/check_package_provenance first for general health, use this tool specifically for maintainer control questions, and follow up with check_maintainer_blast_radius when a new or turned-over maintainer is flagged. It clearly states what this tool is not for and what to do next.

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 only declare read-only, non-destructive, open-world behavior; the description adds substantial disclosure: parallel fetching, deterministic weighted scoring, never picking deprecated/typosquat-flagged candidates, unresolved names returned as found:false instead of failing, duplicate rejection, and transparent truncation flags on transitive size. No contradictions 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?

Long but dense; every clause adds a distinct behavioral or output detail relevant to correct invocation (truncation flags, no tarball fetch, scoring exclusions, edge cases). The purpose is front-loaded and the nested clarifications are organized, though the parenthetical-heavy style makes it slightly harder to scan.

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?

Covers usage, edge cases (unresolved, duplicates, truncation), scoring logic, and pointers to deeper tools; with annotations and an output schema present, nothing needed for safe/correct invocation is missing. It even explains what the tool deliberately does not do, such as fetching the tarball.

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 the single packages array with counts and an example; the description adds semantic constraints not in the schema: candidates should be for the same job, duplicate names are rejected, and unresolved names still appear with resolutionError. This goes beyond the baseline, though a 5 isn't warranted because the single parameter is already well covered by 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 specific verb and resource ('Compare npm packages side-by-side') and enumerates the enrichment dimensions (popularity, maintenance, vulnerabilities, etc.). It is clearly distinguished from siblings by the side-by-side comparison intent and explicitly references get_package and analyze_* tools for adjacent functionality.

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 targets 2-5 candidate packages for the same job, which defines the appropriate context. It names analyze_install_script and analyze_transitive_dependencies as alternatives when deeper or full-graph analysis is needed, and references get_package as the single-package computation baseline.

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, and the description adds substantial behavioral context: the 100-package cap, installScriptIntroduced semantics, vulnerabilityDelta value set, presence-only install-script detection, and format-scope differences. 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 description is dense but every sentence carries meaningful guidance: core operation, high-signal output fields, scope caveats, detection limitations, and alternative tool. It is front-loaded with the primary purpose and uses the remaining length for genuinely necessary nuances.

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, and full annotation coverage, the description is complete: it covers format variants, scope limitations, batch behavior, vulnerability reporting style, mixed-format handling, and the recommended next step for flagged results. No critical calling context 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 fully documented in the input schema (100% coverage), including raw content, allowed formats, and auto-detection. The description reinforces the before/after relationship and PR use case, but does not add new parameter-level semantics beyond what the schema already provides.

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

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

The description opens with a specific verb and resource: 'Compares two raw snapshots of ... package.json ... and reports which packages were added, removed, or version-bumped.' It clearly distinguishes this from siblings like analyze_install_script by framing it as a before/after dependency diff tool.

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

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

It states the intended context ('e.g. before/after a PR'), recommends it as 'Ideal for a CI gate reviewing a dependency-changing PR,' and explicitly directs the agent to analyze_install_script for deep-dives. It also gives format-specific guidance about yarn.lock vs. direct-dependency diffing and the comparisonNote for mixed formats.

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 annotations already signal a safe read-only operation, and the description adds substantial behavioral context beyond that: it performs external GHSA-to-CVE resolution via OSV.dev, depends on CVE-keyed KEV/EPSS data, carries through npm-specific fields like isDirect and fixAvailable/fixTarget, and only uses the first advisory per package. It even discloses a failure mode (silent degradation to severity-only ranking) and warns about multi-advisory packages, which is genuinely valuable for correct invocation and expectation-setting.

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 dense and every sentence carries distinct information: input format, ranking behavior, CVE resolution caveats, npm-specific context fields, multi-advisory limitation, and unsupported formats. It is front-loaded with the core purpose, though the long parentheticals and nested caveats make it less scannable than it could be. The length is justified by the tool's complexity, so it earns a strong score rather than a penalty.

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 tool with an output schema present, the description covers everything an agent needs to call it correctly: accepted input formats, ranking semantics, external resolution behavior, important edge cases (first advisory only, fixTarget naming a different package), and explicit routing to sibling tools for unsupported inputs. No obvious gap remains.

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 fully documents the single `content` parameter and its accepted formats, so the baseline is 3. The description adds semantic value by clarifying that the value is raw stdout from the npm CLI, that no package.json/lockfile re-pasting is needed, and by explaining the npm 7+ vs npm 6 format distinction in the narrative. This elevates the parameter understanding beyond the 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 precise verb-resource pair: parse raw `npm audit --json` output and rank vulnerabilities by patch-now/patch-soon/scheduled/monitor priority. It also distinguishes itself from siblings by explicitly noting it works directly on the raw report rather than hand-built finding lists and by naming unsupported formats (`yarn audit --json`, `pnpm audit --json`).

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 when-to-use condition: when the input is raw npm audit JSON and ranking is desired. It also gives clear exclusions, stating yarn/pnpm audit outputs are not supported and directing the agent to `batch_query_vulnerabilities` with the manifest/lockfile instead, and referencing `prioritize_remediation` for hand-built lists.

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 readOnlyHint/openWorldHint/destructiveHint annotations already establishing a safe read operation, the description adds substantial behavioral nuance: VEX analysis.state is 'in_triage' and unreviewed, not a claim of exploitability; omitted dependency graphs are deliberately not fabricated; includeVulnerabilities/includeLicenses control costly enrichment passes; and format-specific output placement is disclosed.

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 but purposeful: every clause contributes output semantics, format behavior, or parameter interplay. It is front-loaded with the core purpose and the details follow logically, though the single unbroken paragraph could be restructured with line breaks or bullets for easier parsing.

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 9 parameters, nested objects, and format-specific output behavior, the description is remarkably complete: it covers accepted input formats, output format selection, enrichment defaults and toggles, policy integration, VEX semantics, and intentional limitations. Since an output schema exists, the description does not need to separately enumerate return values.

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?

With 89% schema description coverage, the schema already documents most parameters, so the baseline is 3. The description adds real semantic value by explaining that `content` accepts package.json/lockfile/CycloneDX/SPDX JSON, that `packages` is an alternative input, that `policy` mirrors check_license_compliance, and that componentName/componentVersion label the root document.

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 is explicit: it generates a spec-valid CycloneDX 1.6 or SPDX 2.3 SBOM document, naming the concrete output, formats, and embedded vulnerability/license data. It also distinguishes itself from sibling tools like batch_query_vulnerabilities and check_license_compliance by referencing their input/policy shapes while making clear the deliverable is an SBOM.

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

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

The description gives strong contextual guidance: it reuses the batch_query_vulnerabilities input contract, accepts content or packages, points to check_license_compliance for the policy shape, and explains when enrichment passes can be skipped. It does not explicitly state 'use this instead of X when...', so it falls just short of full exclusion-level 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 annotations, the description discloses meaningful behavioral details: KEV and EPSS enrichment semantics, automatic MITRE fallback with a source field, the shared NVD rate limit with retry expectation, and the non-npm-scoped result set. This materially helps an agent interpret outcomes and avoid false failure conclusions.

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: core purpose, enrichment semantics, fallback behavior, ecosystem scope, tool-selection guidance, and rate-limit caveat. It is front-loaded with the primary lookup/search purpose before moving to interpretive guidance and edge cases.

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

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

Given the tool's complexity, the description covers the critical operational facts: single-ID vs search behavior, fallback to MITRE, KEV/EPSS interpretation, ecosystem scope, and retry-on-rate-limit. The presence of an output schema means return-value details do not need to be repeated in the description.

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

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

The input schema already documents all 8 parameters, so the baseline is 3. The description adds value above the schema by explaining the cveId-first behavior, its override of search filters, the fallback when no NVD record exists, and why keywordSearch should be used to narrow the otherwise broad NVD result space.

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

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

The description opens with a specific verb-resource pair: 'Look up ... NIST NVD data' for one exact CVE ID or search NVD by several dimensions. It also explicitly contrasts with sibling tools by noting NVD is not npm-scoped, so an agent can distinguish get_cve from query_vulnerabilities and get_latest_advisories.

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 selection guidance: prefer this for authoritative CVSS/vector/KEV/EPSS data on an already-discovered CVE or when a user pastes a CVE ID/link, and prefer get_latest_advisories for npm-specific browsing. It also tells the agent to pass keywordSearch to narrow open-world results.

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

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

Annotations already mark this as read-only and non-destructive, and the description adds useful behavioral context beyond that: it notes advisories are 'reviewed,' explains the opaque cursor pagination mechanism, and clarifies that nextCursor is passed back as cursor. This gives the agent a practical model of how the tool behaves.

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

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

Three sentences with no filler: the main action is front-loaded, the filtering options are compactly enumerated, and pagination is explained in a single clear sentence. Every sentence 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?

For a read-only query tool with an output schema and fully described parameters, the description covers all major behaviors: browsing, filtering by severity/category/package, exact ID lookup, and pagination. Nothing needed for correct invocation 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 schema already documents every parameter. The description restates filter dimensions and the pagination flow but does not add substantive new meaning beyond what the schema provides. It meets the baseline without compensating for any schema gaps.

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: 'Browse recently published, reviewed GitHub Security Advisories for the npm ecosystem.' It clearly distinguishes this tool from generic vulnerability queries or individual package lookups by scoping to npm security advisories. The stated filtering and exact-lookup capabilities make its 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?

The description implies when to use the tool by listing its capabilities, but it never explicitly contrasts it with siblings like get_cve or query_vulnerabilities, nor states when to prefer one of those instead. The usage context is inferable but not spelled out.

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

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

Annotations already establish readOnlyHint, openWorldHint, and non-destructive behavior. The description goes further by explaining the data source, the absence of a dedicated registry endpoint, the derived avatar behavior, and the null condition. This adds meaningful behavioral context beyond the annotations.

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

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

The description is long and dense, especially the first sentence with multiple parenthetical caveats. However, nearly every detail earns its place because it clarifies data provenance, aggregates, and avatar behavior. It is more verbose than strictly necessary but not wasteful.

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 one well-documented parameter and an output schema present, the description covers the important contextual gaps: what the search index returns, what the aggregates mean, what avatarUrl is derived from, and when it is null. It also provides the cross-tool routing needed for correct selection.

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 describes maintainerUsername with strong guidance: exact npm username, not email, not package name or scope, with an example. Schema description coverage is 100%, so the description's 'Given an npm username' adds little beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states a specific verb and resource: given an npm username, it returns all packages from npm's maintainer search plus computed aggregates. It also distinguishes itself from check_maintainer_blast_radius, so an agent can immediately tell what this tool is for.

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 this is a plain info lookup and does NOT run compromised-account detection. It names the alternative tool, check_maintainer_blast_radius, and gives the condition for choosing that instead: when the goal is a security read on whether a maintainer looks risky.

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 provide readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the agent knows this is a safe, read-only operation. The description adds significant behavioral context beyond these: it discloses that topPackagesRank comes from a "periodically-refreshed snapshot — not live", explicitly states that popularityTier/maintenanceTier are "deterministic rule-based labels, not model-generated", and warns that a long gap since last release "can mean either a stable/finished package or a slowing one" — a critical interpretive caveat. It also flags the possibleTyposquatOf signal and the need to check deprecated and maintenanceSummary. This is rich behavioral context that complements the annotations rather than repeating them. A small deduction: the description does not explicitly describe the output schema's structure (e.g., whether findings are in an array, or the exact field names for each vulnerability), but the output schema exists and is not nested, and the description gives enough field names to be useful. No contradiction with annotations.

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

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

The description is comprehensive but somewhat long and dense. It front-loads the core purpose and key data fields, which is good, but then includes a long parenthetical about topPackagesRank and a second parenthetical about rule-based labels, making the text feel packed. The mention of "Also checks the LATEST version against OSV.dev" and the advisory to "read deprecated and maintenanceSummary" are valuable, but the description could be more concise by trimming redundant phrasing like "(preinstall/postinstall are a key risk signal)" which, while useful, adds length. The structure is a single paragraph with several clauses chained, which is acceptable but not optimally scannable. It's informative but could be tightened without losing meaning.

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 (it returns a rich set of fields, including vulnerability data, popularity metrics, and a possible typosquat signal) and the presence of an output schema, the description covers almost everything an agent needs to call it correctly. It explains the return fields, the caveats about the data's freshness and label types, how to interpret maintenance gaps, and directs to alternative tools for specific older version checks. The only missing piece is an explicit note about required authentication or rate limits, but the annotations (readOnlyHint) and openWorldHint suggest no destructive effects, and no auth is mentioned for the sibling tools either—this seems consistent. The description is substantial and covers the key decision points, warranting a 4 rather than a 5 due to the lack of explicit instructions on pagination or why one might prefer this tool over search_packages when searching, but for its purpose, it's nearly 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 has 100% coverage for its single parameter, `name`, with a description including examples and validation constraints. The tool description does not add parameter-specific semantics beyond what the schema already conveys; the parameter is straightforward (a package name string). The description does provide additional context about how the `name` is interpreted (exact npm package name), but this is already in the schema. Since schema coverage is high, the baseline is 3, and the description doesn't need to compensate. There's no additional field-level detail in the description that would elevate the score.

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 clear, specific statement of the tool's purpose: "Fetch npm registry metadata for a package..." immediately enumerating the concrete data fields returned (latest version, install scripts, maintainers, license, etc.). This goes well beyond a simple verb+resource, distinguishing it from siblings like get_package_version and query_vulnerabilities. The explicit mention of "preinstall/postinstall are a key risk signal" and "direct safe/not-safe answer" establishes a clear functional identity, and the later inclusion of "topPackagesRank" and "downloadTrend" further separates it from other package-related tools.

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

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

The description provides partial usage guidance. It implicitly establishes when to use this tool (for a broad package health assessment) and explicitly mentions alternatives: "use get_package_version or query_vulnerabilities to check a specific older version instead" when needing to check a specific older version's vulnerabilities. However, it does not explicitly state when NOT to use this tool (e.g., when only a CVE lookup is needed, or when searching for packages — sibling search_packages). The guidance is implied through the mention of alternatives but lacks a clear 'when-not' clause. The conditional instruction to "read deprecated and maintenanceSummary before recommending a package" is useful and effectively guides usage, earning a 3 rather than a 2.

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

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

Beyond the annotations, the description discloses compound behavior: metadata fetch plus vulnerability check, and specifies the response fields (isVulnerable/highestSeverity, severity, summary, fixedVersion). It correctly aligns with readOnlyHint=true and destructiveHint=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?

Two sentences carry the full purpose, usage, and output meaning with no filler. The operation is front-loaded before the usage guidance.

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

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

With annotations, complete input schema, and an output schema, the description covers what remains: when to use it, what data it returns, and how findings are represented. Nothing needed for a correct call 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 fully documents name and version, including length constraints and an example. The description repeats 'exact version' but adds no new semantic detail for either parameter, 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?

The description names the exact operation: fetch registry metadata for one package version and check it against OSV.dev. It makes the resource ('one exact version of a package') and the dual behavior explicit, and separates this tool from any latest-release package lookup.

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 a direct usage directive: use this for a version pinned in a lockfile rather than the latest release. It lacks a named alternative tool, so it doesn't fully route the agent to a sibling, but the when/when-not guidance 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 declare readOnlyHint=true and destructiveHint=false, and the description adds significant behavior beyond that: duplicate rules are deduplicated, each matched rule gets a distinct situationNote, batch results avoid boilerplate, and unmatched inputs return matched:false with a note instead of throwing. This is rich disclosure of runtime 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 and dense, but nearly every sentence adds necessary operational detail. It is front-loaded with the tool's core purpose and output. A little more paragraph structuring could improve scannability, but the length is justified by the behavioral nuances.

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 fully covers input sources, batching, deduplication, unmatched findings, output content, and link-to-docs context. Combined with the output schema and annotations, an agent has everything needed to invoke this tool correctly and interpret responses.

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%, but the description enriches both parameters: `rules` are exact values from specific sibling tool outputs, batchable up to 10 with deduplication, and `id` is a playbook slug lookup. It clarifies constraints and relationships that 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?

The description names a specific verb ('maps', 'returns'), a resource (playbooks derived from analyze_install_script, check_maintainer_changes, check_package_provenance), and the concrete output (ordered steps, severity tier, references, prevention tips). It clearly differentiates this from sibling tools by stating it returns the 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 gives explicit input guidance: pass exact `rule` strings from prior findings, batch up to 10, or use an `id` slug. It also explains the edge case where an unrecognized rule/id is not an error, which tells the agent when a matched:false result is acceptable. This is direct, actionable usage 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?

The description discloses substantial behavior beyond the annotations: CISA KEV acts as an automatic top-priority override, EPSS is the primary ranking signal, severity is fallback, and the result is a composite score with tiers. It also exposes deduplication behavior for shared CVE IDs, which is valuable operational context not present 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 description is front-loaded with the core purpose and then builds outward into signals, exclusions, and deduplication behavior. Each sentence adds meaningful guidance, and the length is justified by the complexity of the ranking logic and the need to differentiate from sibling tools.

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

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

For a tool with one parameter, full schema coverage, and an output schema, the description is complete: it explains input provenance, ranking inputs, what enrichment is added, what is not done, and the output tier concept. No critical invocation detail 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 schema already documents the fields including cveId's enrichment role and severity's fallback role. The description adds some clarifying context about passing through existing findings and deduplicating shared CVE IDs, but this is largely behavioral rather than genuinely new parameter-level semantics.

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

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

The description states a specific verb and resource: it takes a batch of already-flagged vulnerability findings and ranks them by fix priority. It also distinguishes itself from siblings by explicitly saying it does NOT re-query OSV/NVD and that findings come from tools like batch_query_vulnerabilities or query_vulnerabilities.

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

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

The description explicitly says when to use it (after other tools have flagged findings) and what it does not do (no OSV/NVD re-query), naming concrete alternatives. It also clarifies the data flow: pass in severity/CVE findings and receive KEV/EPSS enrichment plus ranking.

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 adds meaningful behavioral context beyond annotations: it queries an external service, returns a distilled answer rather than raw data, and specifies the output fields including fixedVersion, CVE aliases, and plain-language summaries. This is substantial transparency for a read-only tool.

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

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

The description is two sentences with no filler. It front-loads the core action and scope, then delivers high-value output and usage context. Every sentence 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?

Given the rich schema, existing output schema, and annotations, the description adds exactly what is missing: when to use it, what the returned answer looks like, and the key distinction that it is not a raw advisory dump. Nothing needed for safe invocation 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 parameter semantics are already fully documented in the schema. The description adds a helpful real-world example (lockfile pin check) and reinforces that version is optional, but it does not carry the parameter-documentation burden. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: querying OSV.dev for known vulnerabilities affecting an npm package. It further distinguishes itself from a raw advisory dump by promising a direct isVulnerable/highestSeverity answer, and its exact-version scoping differentiates it from broader advisory tools like get_latest_advisories.

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

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

The description gives clear context for when to use the tool: 'Use before recommending, installing, or upgrading a package,' and provides a concrete use case for checking a lockfile-pinned version. However, it does not explicitly mention the sibling batch_query_vulnerabilities or state when not to use this tool, so it stops short of full exclusion 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?

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 already declare readOnlyHint/openWorldHint/destructiveHint, so the description's extra behavioral detail is genuinely additive: semver classification rules including pre-1.0 breaking-risk convention, multi-major jump flagging, registry signal checks (deprecated, lifecycle scripts, engines.node, prerelease), OSV.dev vulnerabilityDelta, riskTier output, batch deduplication/parallelization, and per-item fetchError handling. It also explicitly disclaims what it does not do (changelog/source-diff analysis). No contradiction with annotations.

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

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

The description is long but highly structured: purpose first, then follow-up use case, semver classification, registry signals, OSV integration, riskTier output, explicit exclusions, batch instructions, and error handling. Every sentence adds a distinct piece of information; there is no filler or tautology. The front-loaded first sentence alone captures the core function.

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 parameters, no required fields, 100% schema coverage, an output schema, and batch mode), the description is remarkably complete. It covers input forms, optional behavior, output fields (riskTier, reasons list, vulnerabilityDelta, fetchError), integration with a sibling tool, cost characteristics of batch calls, and known limitations. Nothing essential is missing for an agent to select and invoke it correctly.

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

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

Although schema coverage is 100%, the description goes far beyond repeating parameter names. It explains that targetVersion is optional and defaults to the registry's 'latest' dist-tag, that packages array items mirror the single-item fields, that the array is 1-100 items, and that prioritize_remediation's fixedVersion can be passed directly. It also clarifies the mutual exclusivity of the single-item and batch forms, which the schema alone does not convey as effectively.

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

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

The description opens with a specific verb-resource pair: 'Given a package and a current/target version, tells you whether that specific upgrade is a safe patch/minor bump or a likely-breaking major bump.' It distinctly differentiates itself from siblings like prioritize_remediation (a ranking pre-check) and get_package (single metadata lookup) by framing itself as a pre-install upgrade risk simulator. The scope is unmistakable.

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

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

Explicitly positions the tool as the natural follow-up to prioritize_remediation, naming the exact field mapping (packageName/currentVersion/fixedVersion). It provides clear when-not guidance ('not a substitute for reading the release notes on a flagged major bump') and distinguishes single-item vs batch invocation with a hard constraint (use packages OR packageName/currentVersion, not both).

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

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

The description goes well beyond the readOnlyHint annotation by disclosing the internal pipeline: health checks, combination of deprecation hints, deterministic npm category matching, ranking by category overlap and popularity, filtering of typosquats and weak contenders, and output with whySuggested notes. This fully sets expectations for how the tool behaves.

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 information-dense but each sentence contributes: trigger conditions, method, ranking/filtering behavior, and output format. It is front-loaded with the purpose and follows with the process, making it easy for an agent to quickly grasp when and how to invoke the tool.

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 a multi-step internal algorithm and an output schema, the description covers the inputs, processing logic, ranking criteria, exclusions, and the shape of the result. The presence of an output schema means the return format is already defined, and the description fills the remaining behavioral context.

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?

Parameter schema coverage is 100%, so the schema already documents name, limit, and reason clearly. The description adds contextual meaning around the reason parameter by mentioning 'deprecated, vulnerable, abandoned, or suspicious' and typosquat filtering, but it does not add significant semantic detail 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 uses a specific verb ('suggest') and resource ('better-maintained npm alternatives') and clearly defines the triggering conditions: packages that look deprecated, vulnerable, abandoned, or suspicious. It differentiates the tool's role from sibling tools like search_packages by emphasizing alternative ranking rather than raw search.

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 states this is best for converting a 'don't use this package' warning into an actionable replacement shortlist, giving clear contextual guidance. It does not explicitly name sibling tools or say when not to use it, but the intended scenario is well implied.

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