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

With no annotations, the description carries the burden and does reasonably well: it discloses the data source (OSV), the remediation taxonomy (same-line direct upgrade, parent upgrade, override), the deps.dev resolution fallback, and the special GitHub Actions path covering advisories and SHA pinning. It does not mention network/auth requirements (e.g., GitHub token for the Actions check), rate limits, or whether anything is written to disk, which keeps it below 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?

Purpose and remediation behavior are front-loaded in the first sentence, with input modes and supported formats following logically. The supported-file enumeration is long but earns its place as a validity check for fileName; the trailing GitHub Actions sentence is slightly tacked on but is genuinely necessary scope information.

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

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

For a four-parameter audit tool with no output schema, the description covers inputs, data source, fallback resolution, remediation output, and the Actions special case. What it lacks is return-shape detail (per-finding structure, severity counts) that would otherwise be supplied by an output schema, since none exists here.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: it explains why path can be a directory versus a file, and the long supported-format list effectively defines what fileName values are valid. includeDev is left entirely to its schema description, which is the only semantic gap.

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?

"Audits every package in a lockfile (direct and transitive) against OSV" gives a specific verb, resource, and scope, and the explicit "direct and transitive" framing separates it from a single-package check like check-package. It also states what the output delivers (a fix per finding), so an agent knows the shape of the value returned.

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 the input modes — project directory, file path, or content plus fileName — and enumerates which manifests/lockfiles are accepted, plus the deps.dev fallback when no lockfile exists. It does not explicitly name a sibling (check-package, check-packages) or say when to prefer those over this whole-tree audit, so routing is left partly to inference.

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

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

With no annotations, the description carries the behavioral burden and does well: it discloses that the operation is a non-mutating lookup and itemizes the returned verdict components, which is the key behavioral fact for a pre-install check. It does not mention rate limits, auth requirements, or how expensive a call is, leaving a gap for a tool with zero annotation coverage.

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

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

Two sentences, no filler. The verdict contents are front-loaded in a scannable list, and the sibling routing note is placed last as a clean boundary statement.

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

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

For a four-parameter, single-package advisory lookup with no output schema, the description enumerates the return categories and explains the same-release-line logic, which substitutes effectively for a missing output schema. An agent has everything needed to call it correctly and interpret 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?

Schema coverage is 100%, so the baseline is 3; the description earns more by clarifying the intent behind `version` – it reports "the safe version on the same release line as the one you pass," and contrasts the newest safe version with that same-line fix. That adds decision-relevant meaning beyond the schema's plain "Version you intend to install or already use."

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?

"Supply-chain verdict for one package" names a specific verb-and-resource, then enumerates exactly what the verdict contains: advisories (CVE/GHSA, malware), deprecation, license, newest safe version, same-release-line safe version, typosquat lookalikes. It also explicitly distinguishes itself from the batch sibling check-packages, so an agent can route without opening either schema.

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

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

It states the single-package scope ("for one package"), the exclusion ("no docs"), and the alternative with its selection condition: "For several packages use check-packages, one call for the whole list." That is explicit when-to-use plus a named alternative.

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

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

With no annotations, the description carries the full burden and does most of it: it states the batch ceiling, the return shape (verdict, version to pin, short reason, full notice only for problem packages), and the omit-version fallback to installed version. It does not disclose freshness/latency of the supply-chain lookup or whether checks hit the network, which is the main remaining gap for a tool with zero annotation coverage.

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

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

Three tight sentences, front-loaded with what the tool returns, then when to call it, then the version-omission nuance. No filler and nothing repeated from structured fields verbatim.

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 usefully sketches the response (one row per package, full notice only for flagged ones), which is what an agent needs to plan around. Only the ecosystem resolution and any failure/error behavior are unaddressed, a minor gap for a two-parameter read-style tool.

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?

Adds real meaning beyond the schema: the schema only says version can be omitted 'to get the version to use', while the description clarifies that omitting it for packages already in the project means the installed version is checked. It also restates the 50-item cap in prose. The top-level ecosystem default is left entirely to the schema, so not a full 5 at 50% coverage.

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 resource and verb ('supply-chain verdict for up to 50 packages at once') and explicitly scopes the batch nature of the call. It also implicitly contrasts with the single-package sibling by saying 'instead of one check per package', so an agent can route between check-packages and check-package without opening either schema.

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

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

Gives a concrete trigger ('Call it once with every dependency you plan to add, before writing the manifest') and a concrete anti-pattern ('one check per package'). The alternative is described rather than named, so the agent must infer that the single-package path is check-package, which stops this short of a 5.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: it resolves a human name to a registry id, selects the newest version without known advisories labeled "safe," and returns a verdict. It does not say what happens when a name is ambiguous or unknown, or whether the advisory check is live, which keeps it short of 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?

Two sentences, front-loaded with purpose and resolution examples, then the skip condition with alternatives. Parenthetical examples are load-bearing rather than filler; nothing could be cut without losing routing information.

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

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

For a three-parameter lookup with no output schema, the description covers what comes back (ids, safe version, verdict) and when to bypass the tool. Missing is failure behavior for unresolvable or ambiguous names, which an agent would want before calling.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by showing how libraryName is normalized into a registry-qualified id and by implying the ecosystem is inferred when omitted. It stops short of explaining how query influences resolution beyond the schema's own note about language guessing.

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 ("finds the registry package for a library name") and immediately concretizes it with mappings like "next.js" -> npm:next and "pytorch" -> pypi:torch. It also names what it produces (ids for get-docs, newest advisory-free version, verdict), so it is clearly distinguishable from get-docs and check-packages.

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

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

Gives an explicit exclusion rule: "Skip it when you know the registry name," and explains that get-docs accepts "npm:next" directly while check-packages takes plain names. Both the when and the when-not are stated with the alternative tools named.

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

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

With no annotations, the description carries the full burden and does well: it discloses the security-notice prefix, the fallback to the safe version on the same release line, and the sources consulted. It omits failure behavior (unknown package, no matching sections) and any rate or auth constraints, keeping it below 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 what is returned and immediately followed by the version-dependent behavior. Every clause carries distinct information with no repetition of schema or title text.

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

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

Seven optional parameters with full schema descriptions and no output schema; the description supplies the one thing the schema cannot, namely the version-resolution and security behavior. An agent has enough to call this correctly without further explanation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning for the version parameter: absence means newest advisory-free version, and a vulnerable version triggers a security notice plus safe-version docs. That clarifies semantics beyond the schema's terse 'Version the project uses or pins'.

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 documentation sections that answer your question') plus the exact source basis (published files, repo at release tag, project site). This clearly separates it from check-package, find-library, and upgrade-guide, which do not return documentation content.

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 establishes the context of use (you have a question about a package's API) and conditional behavior for missing or vulnerable versions, but never states when to prefer this over siblings like upgrade-guide or to call find-library first. Usage routing is implied rather than explicit.

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

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

With no annotations, the description carries the full load, and it does disclose the evidence sources (changelogs, GitHub release notes, migration guides, and an npm .d.ts API diff) plus the fallback to the pinright-recommended version when 'to' is omitted. It does not cover auth requirements, rate limits, or the shape of the response, leaving some behavioral gaps.

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

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

It is front-loaded with the content the tool returns, followed by sources and then call conditions, in roughly the right order with no filler sentences. The 'Sources:' clause is dense and adds length, but each element is informative rather than redundant.

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

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

For a seven-parameter, zero-required read tool with no annotations and no output schema, the description covers what is returned, where it comes from, and the defaulting behavior well enough to invoke it correctly. Only the concrete response format and any size-pagination expectations (beyond the 'tokens' param) are left implicit.

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 every parameter is already documented in the schema, including the 'to' default and the libraryId version-as-'from' convention. The description restates the 'to' default and adds no syntax or interaction detail beyond the schema, so the baseline of 3 applies.

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

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

The description names a specific resource and scope: breaking changes, removed/renamed APIs, config and default changes, split-off packages, deprecations, and fixed advisories between the project's current version and its target. That enumeration distinguishes it clearly from siblings like get-docs and check-package without needing to name them.

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

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

It gives three concrete trigger conditions: before crossing a major, when a SECURITY NOTICE recommends a new major, and to fix a Dependabot PR. It also states the no-argument default behavior. It stops short of saying when NOT to use it or explicitly pointing at a sibling alternative, so it is not a full 5.

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