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.