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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavior beyond that: it explains that partial failures degrade gracefully, that bundlephobia's first measurement can take 5-30s, and that sources_failed will list timeouts. It also reveals the fan-out architecture, which is not in annotations. This is useful context, though some latency expectations are already implied by the read-only nature.

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 paragraph but well-structured, with the primary purpose front-loaded. It includes relevant details on usage, output, and failure modes. While it is longer than typical simple tools, the length is justified by the tool's complexity and every sentence carries useful information. A 5 would require even more brevity, so 4 is appropriate.

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 (two external services, multiple data points) and no output schema, the description is exceptionally complete. It enumerates the exact return fields (is_latest, license, published_at, advisory_count, bundle_kb_min, etc.), per-advisory details, links, alternative versions, and ecosystem limitations. It covers the 'what', 'when', and failure behavior comprehensively.

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 schema already documents both parameters (package and version) with descriptions. The description adds minimal parameter-specific meaning beyond the schema, such as confirming version defaults to latest. It does not introduce new details about parameter formats or interactions, so baseline 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 ('scan') and resource ('npm package dependency'), and clearly defines the purpose as a composite check for adding an npm package. It explicitly lists the data sources (deps.dev and bundlephobia) and the output summary fields, which fully distinguishes it from sibling tools like scan_competitor_ai_presence or deep_research.

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 explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion/alternative for non-NPM ecosystems, noting that PyPI/Maven/Cargo/Go fall under deps.dev:version directly. This is clear, actionable guidance.

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