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

Annotations already declare readOnly (no mutation), idempotent, openWorld, non-destructive. Description adds extra context: fans out to external services (deps.dev, bundlephobia), timed delays (5-30s for first bundlephobia measurement), and partial failure behavior (sources_failed listed). Rate limits or auth not mentioned, but overall good transparency.

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?

Well-structured: begins with core function, then details what's covered, usage guidance, and limitations. Every sentence adds value. Slightly long but justified by richness of information. Not overly verbose.

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?

Despite no output schema, description enumerates return fields (summary block, per-advisory detail, links, alternative versions). Also explains partial failure behavior, ecosystem limitation, and timing. Covers all key aspects needed for the agent to understand what to expect.

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% (both parameters documented). Description adds value by explicitly stating scoped packages are accepted for 'package' and that 'version' defaults to latest when omitted. This goes beyond the schema baseline.

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's purpose: a composite check for whether to add an npm package, covering license, advisories, version history, bundle size, and ESM/tree-shake support. It distinguishes from siblings by specifying the NPM-only scope and directing other ecosystems to deps.dev directly.

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?

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides guidance on NPM-only limitation and points to deps.dev:version for other ecosystems. Mentions graceful degradation on partial failures.

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