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

Annotations already declare readOnlyHint and openWorldHint, so safety and network access are covered. The description adds non-obvious execution behavior: it runs as an MCP Task with live progress and orders results BLOCK/REVIEW first with a reason and safe version. It stops short of describing rate limits, registry auth, or what a fully clean result looks like.

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 compact sentences, purpose and scope first, then execution/return characteristics. No filler, and the distinctive detail (newest match for range today) is front-loaded.

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, no-output-schema tool, the description covers purpose, trigger scenario, async task mode, and result ordering. It leaves the shape of a non-BLOCK/REVIEW result and any polling/lifecycle expectations for the task mode unstated, but nothing critical to invoking 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% (both parameters fully described, including includeDev), so the baseline is 3. The description goes slightly beyond the schema by explaining the version-resolution semantics applied to packageJson ('the newest match for its range today'), which is the behaviorally important part of the input.

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 ('Checks every dependency in a package.json') and pins down the version resolution rule ('the version npm would install for its range today (the newest match)'), which separates it semantically from a single-package check. It never names a sibling like bouncer_check_package explicitly, so the differentiation is inferable rather than stated.

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

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

Provides a concrete triggering scenario: 'before running `npm install` in a cloned repo'. That gives clear context for when to reach for this tool, but there are no explicit exclusions and no routing guidance against the six sibling tools (e.g. check_upgrade or check_package).

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

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

Annotations only declare readOnlyHint and openWorldHint; the description goes well beyond that by disclosing the output shape (ALLOW/REVIEW/BLOCK with evidence), the fact that it cross-references npm audit/OSV, and that it recommends a safe alternative version when blocked. It omits latency/rate-limit or data-source freshness caveats, but the behavioral disclosure is substantially richer than the annotations alone.

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 dense sentences, front-loaded with the imperative trigger before the mechanism and return values. Every clause contributes (trigger, comparison basis, verdicts, evidence, audit cross-check, fallback suggestion); the parenthetical signal list is long but information-bearing rather than padding.

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 no output schema, the description correctly carries the burden of explaining returns — verdict categories, supporting evidence, audit results, and a suggested safe version. Combined with the 100%-covered input schema and the read-only annotation, an agent has enough to call and interpret the tool correctly; only sibling disambiguation is missing.

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

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

Schema description coverage is 100% — both `name` and `version` are documented in the schema, including format examples and the "latest" default. The description adds no parameter-level detail (e.g., how a range behaves vs. a dist-tag), so the baseline 3 applies.

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

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

The description names a specific action (compare a release against the package's own history) and enumerates the exact signals inspected — publisher, provenance, install scripts, new dependencies, code diff, name. It clearly positions itself as the broad entry-point check, which implicitly distinguishes it from narrower siblings like bouncer_diff_release and bouncer_review_install_scripts, though it never names them.

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

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

"Call this BEFORE `npm install <pkg>` or adding a dependency" gives an explicit, unambiguous trigger for when to invoke the tool. It does not, however, contrast itself with the sibling bouncer_check_upgrade or say when the granular tools (diff_release, review_install_scripts) are preferred over this aggregate check.

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 (readOnlyHint, openWorldHint), so the bar is lower. The description still adds real behavioral value by promising a "verdict" and enumerating the change categories surfaced (publisher, provenance, install scripts, dependencies) — exactly the kind of context an agent needs before a version bump.

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, both earning their place: the first gives the call trigger, the second the return content. The most actionable instruction (when to call) is front-loaded with no preamble.

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 no output schema, the description carries the return-value burden and does describe the result (verdict + changed fields). It leaves the verdict's possible values or thresholds undefined, which is a modest gap for a gate-style tool but not a fatal one.

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 every parameter (name, from, to) is documented in the schema itself. The description restates the from→to relationship but adds no syntax, format, or constraint detail beyond what the schema already provides, so the baseline 3 applies.

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

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

The description states a specific verb (check) and a specific resource (a dependency upgrade from one version to another), and the from→to framing distinguishes it from sibling bouncer_check_package, which presumably inspects a single version. It never names the siblings explicitly, so the differentiation is implied rather than stated.

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?

"Call this before bumping a dependency from one version to another" gives an explicit trigger point (pre-upgrade gate), which is clear operational guidance. It does not say when NOT to use it or name alternatives such as bouncer_safe_version or bouncer_check_package, so it stops short of full routing 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 openWorldHint=true, so the safety profile is covered. The description adds that output is 'raw evidence for humans' and lists the data categories returned, which is useful, but it discloses nothing about cost, rate limits, or bulk/verbosity behavior for a tool that fetches a full package diff.

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?

A single tight sentence, front-loaded with the 'Raw evidence for humans' framing followed by the enumerated contents and the usage call-to-action. No filler, though the parenthetical list 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?

With no output schema, the description carries the return-value burden and does so by enumerating the diff's contents. Combined with annotations covering the safety profile, an agent has enough to call and interpret it, though the human-vs-machine output distinction could be clearer.

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

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

Schema description coverage is 100%, with name/from/to all documented in-schema (including the npm scoped-name example), so the baseline of 3 applies. The description adds no syntax, ordering, or range guidance 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?

States a specific verb+resource (diff two versions of a package) and enumerates the exact dimensions covered: publisher, provenance, install scripts, dependencies, file changes, risky code patterns. It is distinguishable from generic checks, though it never names an overlapping sibling like bouncer_check_upgrade or bouncer_check_package.

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

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

The closing clause 'Use it to explain a REVIEW or BLOCK' gives a real usage context tied to sibling outputs, but there is no when-not guidance and no explicit alternative named among the six siblings that could also surface version-change data. Usage is implied rather than prescribed.

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 disclose readOnly and closed-world behavior, and the description adds meaningful context beyond them: the data is a labelled reconstruction with benign stand-in code because the real malicious versions were pulled from npm. It does not cover latency, auth, or exactly what is returned, so not a 5.

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, front-loaded with the core purpose, and the reconstruction caveat is well placed at the end where it is most relevant. The incident enumeration overlaps the schema enum but the appended years give it enough extra value to be defensible.

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 one-parameter read-only tool this is mostly sufficient, and the simulation framing is clear. However with no output schema the description never indicates what a replay returns, which an agent would reasonably want to know 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?

Schema description coverage is 100% and one enum governs the single parameter, so the baseline is 3. The description restates the enum values and adds years (axios 2026, keyv 2026, chalk 2025, nx 2025, tinycolor 2025), which is contextual flavor but does not change how the parameter is supplied.

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 action (replays a real npm hijack) and the exact artifacts involved, and its scenario/simulation nature cleanly separates it from the check_* siblings. The verb 'replays' is slightly ambiguous about what the caller actually receives, keeping it out of 5 territory.

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 framing 'as an agent would have met it 30 minutes after publication, before any advisory existed' implies the intended scenario (seeing pre-advisory behavior), but there is no explicit when-to-use, when-not-to-use, or pointer to the check_* siblings for real-world verdicts.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description usefully adds that the tool returns the actual scripts, the reasoning behind each verdict, and a tri-state decision value — meaningful behavioral context given there is no output schema.

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

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

Two sentences, front-loaded with the npm 12 rationale before the action and the npm 11 fallback use. The npm context sentence is justified because it explains why the tool exists, and nothing is wasted.

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

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

For a single-parameter, read-only tool with no output schema, the description covers the workflow trigger, what it returns, and an alternate use case. It leaves minor gaps around output shape and limits (max 15), but those are handled by the 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 the `packages` array with name/version fields. The description only echoes this ('pass the packages it lists') without adding format or selection guidance, so 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: it reviews dependency install scripts and returns scripts, rationale, and APPROVE/REVIEW/DENY verdicts. It differentiates from siblings by narrowly scoping to install-script approval rather than general package checks, though it never names those siblings explicitly.

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 triggering context — use it on the packages npm 12's `approve-scripts` lists, and note it works on npm 11 to reveal which deps run install-time code. It does not name alternative sibling tools or state exclusions, so it stops short of a full when/when-not guide.

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 openWorldHint, so the safety and network-touching profile is covered. The description adds genuinely new behavioral detail: it reports which newer versions were skipped and the reason, which an agent could not infer from annotations or schema.

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

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

Two tight sentences with no filler, and the core behavior (what is returned) is front-loaded before the usage hint. Nothing is redundant or buried.

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 no output schema, the description carries the burden of explaining returns and does so well (newest passing version plus skipped versions and reasons). It stops short of specifying the exact return shape or how version ordering/range edge cases are handled, which is a minor but real gap.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the semver range example and the default of any stable version. The description merely echoes the range concept, adding little 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?

States a specific verb and resource (returns the newest version of a package) and a precise scope (only versions passing every Dep Bouncer check, optionally constrained by a semver range). This is clearly distinguishable from sibling check-style tools because it resolves to a concrete installable version rather than a verdict.

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

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

"Use it to pick what to install instead of a blocked release" gives explicit context for when this tool is the right choice. It does not name a specific alternative sibling (e.g. bouncer_check_upgrade) or state exclusions, so it stops short of full when/when-not guidance.

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