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.