NPMScan

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds value by naming the external source (OSV.dev) and the batch limit (up to 100, also in schema), but does not disclose return format, error behavior, or rate limits. With annotations present, this is acceptable but not exceptional.

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

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

The description is a single, front-loaded sentence that states the function, scope, and use case efficiently. Every phrase earns its place, with no redundancy or 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?

This is a simple one-parameter tool with rich schema, clear annotations, and a focused description. The description fully covers purpose, scale, and ideal usage scenario, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, with a clear description of the 'packages' array ('1-100 packages to check'). The description adds domain context (npm, package.json/lockfile) but does not provide additional syntax or format details. Baseline 3 is appropriate since the schema handles parameter documentation.

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 identifies the action ('Query OSV.dev for known vulnerabilities'), the resource ('npm packages'), and the batch scope ('up to 100 at once'). It distinguishes itself from likely sibling 'query_vulnerabilities' by emphasizing batch processing and the specific use case of scanning a package.json/lockfile.

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 clear usage context ('ideal for scanning a whole package.json/lockfile in one call') that implies this tool is for batch queries. However, it does not explicitly state when to use a single-query sibling or when not to use this tool, so it falls short of a 5.

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

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

Annotations already declare the tool as read-only (readOnlyHint=true) and non-destructive, so the description's job is lighter. It adds context about the source being GitHub Security Advisories and that advisories are 'reviewed', but does not disclose additional behaviors such as pagination limits or result formatting. 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?

A single, 18-word sentence effectively communicates the tool's purpose and filtering capability. It is front-loaded with the action and resource, with zero 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 simple read-only list tool with two optional, well-documented parameters and no output schema, the description covers the essential purpose and main filter. It does not explain next steps or return shape, but that is unnecessary given the schema and annotations. It might benefit from mentioning pagination behavior, but page is documented in 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?

Both page and severity parameters are fully described in the input schema (100% coverage), including default values and allowed enums. The description only mentions the severity filter, not the page parameter, so it adds no additional meaning beyond the schema. This meets the baseline for a schema-covered set of 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 clearly states the tool browses the most recently published, reviewed GitHub Security Advisories for the npm ecosystem, with optional severity filtering. It uses a specific verb ('browse') and resource ('GitHub Security Advisories'), and distinguishes itself from sibling tools like query_vulnerabilities by focusing on '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 establishes a clear use case: browsing the latest advisories, optionally filtered by severity. However, it does not explicitly contrast this with sibling tools like query_vulnerabilities or batch_query_vulnerabilities, nor does it mention negative conditions when not to use this tool. Thus, the usage guidance 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?

Annotations already indicate this is a safe read-only operation (readOnlyHint=true, destructiveHint=false). The description adds useful context about the returned metadata (including install scripts as a risk signal) and the inclusion of a link to the npmscan.com analysis page, which goes 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 two concise sentences. The first sentence front-loads the main verb and resource, then lists specific metadata fields. The second sentence mentions the link to the analysis page. No redundant or filler content exists.

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

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

With a single parameter, clear schema, and annotations confirming read-only safety, the description is quite complete. It lists the key return fields and the external link. However, because there is no output schema, the description could be slightly more explicit about the response format or pagination, though it's adequate for this simple 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?

The schema provides a clear description of the single 'name' parameter with examples and length constraints (100% coverage). The description does not add additional meaning about the parameter beyond what is in the schema, so the baseline score 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 uses a specific verb ('Fetch') and resource ('npm registry metadata') and lists concrete fields (latest version, install scripts, maintainers, license, version history). This clearly differentiates it from sibling get_package_version, which focuses on a specific version.

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 usage for inspecting package metadata and highlights install scripts as a risk signal, which suggests a security analysis context. However, it does not explicitly state when to use this tool over siblings like get_package_version or search_packages, so the guidance remains 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?

Annotations already declare readOnly=true and non-destructive. Description adds behavioral context by enumerating the registry metadata fields returned (dependencies, install scripts, tarball), which complements the annotations without contradicting them.

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

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

Two concise sentences: first states the action and return contents, second provides usage context. No redundant wording, all details earn their 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 simple two-parameter, read-only tool with strong annotations, the description fully captures purpose, return contents, and appropriate use case. No output schema exists, but the metadata listing gives adequate return expectations.

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?

Input schema descriptions already cover both parameters with exact names and examples (schema coverage 100%). Description adds minimal extra meaning beyond emphasizing 'exact version' and lockfile context, but the schema carries the semantic load.

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?

Clearly states it fetches registry metadata for one exact package version, listing specific metadata (dependencies, install scripts, tarball). Distinguishes from sibling tools by explicitly contrasting with the latest release use case.

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

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

Provides explicit when-to-use guidance: checking a version pinned in a lockfile. Contrasts with fetching the latest release, implying an alternative tool. This satisfies the 'when/when-not' criterion.

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, openWorldHint=true, and destructiveHint=false. The description adds that the tool queries OSV.dev (an external service) and can be version-scoped, which is useful context. However, it does not describe the response format, potential rate limits, or behavior beyond what annotations already cover.

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, front-loaded with the key action and resource, followed by a concise usage note. Every word earns its place—no redundancy, fluff, or unnecessary detail.

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 tool is simple and well-covered by schema and annotations. The description provides the essential purpose and usage context. There is no output schema, but the return type ('known vulnerabilities') is implied, and for a read-only query this is sufficient. It could mention the batch alternative, but that is a minor 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%: the schema already documents name, version, and ecosystem with descriptions. The description's references to 'npm package' and 'one version' simply restate the schema. No additional semantic meaning is provided beyond the structured definitions.

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 specifies the exact action ('Query OSV.dev'), the resource ('known vulnerabilities affecting an npm package'), and the optional scope ('optionally scoped to one version'). It clearly distinguishes from sibling tools like batch_query_vulnerabilities by focusing on a single 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?

Provides explicit usage guidance: 'Use before recommending or installing a package.' This gives clear context for when to invoke the tool. However, it does not mention alternatives (e.g., batch_query_vulnerabilities for multiple packages), so it lacks the exclusions needed for a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context by stating it returns matching packages with a link to a full risk/analysis page, which is beyond the annotations. It does not detail pagination or sorting, but given the simple tool and annotation coverage, this is adequate.

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 succinct sentences with front-loaded action. The first sentence states the core purpose, the second adds valuable return-behavior detail. No wasted words.

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 simple search tool with no output schema, the description adequately covers what it does, what it returns (matching packages and a link), and the resource (npm registry). Annotations cover safety, and siblings are differentiated. No significant gaps 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?

Schema description coverage is 100%, so the baseline is 3. The description's phrase 'by name or keywords' adds minimal value beyond the schema's parameter description for 'query'. The 'limit' parameter is not mentioned, but the schema fully documents it. Thus no significant additional meaning is provided.

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 ('Search') and resource ('npm registry'), and clarifies scope ('by name or keywords'). It clearly distinguishes from sibling tools like get_package and query_vulnerabilities by focusing on package search rather than exact lookup or vulnerability queries.

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 usage context: search for packages by name or keywords. It does not explicitly state when not to use it or name alternatives, but the context is clear and distinct from siblings. No exclusions are mentioned, which is acceptable for a straightforward search tool.

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