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

The description goes well beyond the readOnlyHint/idempotentHint annotations. It discloses degradation behavior (partial failures, sources_failed field), performance caveats (bundlephobia first measurement can take 5–30s), and the NPM-only limitation. 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?

Though lengthy, the description is tightly structured and front-loaded. The first sentence gives the composite purpose, followed by usage guidance, return fields, ecosystem scope, and failure behavior. Every sentence earns its place with specific, non-redundant 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?

There is no output schema, but the description enumerates the full return block (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable, plus details and alternatives). It also covers error handling, performance, and ecosystem constraints, making the tool fully self-explanatory for an agent.

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 already provides 100% descriptive coverage for both parameters (package and version, including scoped package handling and default-latest behavior). The description adds no new parameter-level meaning beyond what the schema states, 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 uses a specific verb ('check') and clearly defines the composite scope: a one-call evaluation of whether to add an npm package, fanning out to deps.dev and bundlephobia. It names concrete data points (license, advisories, bundle size, tree-shaking) and the intended question ('is X safe / popular / small'), distinguishing it from sibling tools focused on other domains.

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?

Explicit usage trigger: 'Use whenever an agent asks...' with concrete example phrasings. It also gives clear exclusions and alternatives: NPM only in v1, with other ecosystems falling under deps.dev:version directly. This tells an agent exactly when to choose this tool over simpler alternatives.

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