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

The description leads with 'Read', implying a read-only operation, and detailed what it reports on (archived, advisories, source-available licenses, stale repos). However, with no annotations provided, it does not disclose any side effects, authentication requirements, rate limits, or behavior for large lists. The description carries the full burden but only partially satisfies it.

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?

Two sentences, no redundancy. The first sentence precisely states the action and outputs; the second gives the usage context. Every word earns its place, making it a model of concise, front-loaded documentation.

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 tool with no output schema, the description does explain the return categories (archived, advisories, license, staleness). It also covers the use case and the type of input. However, it does not specify the format or acceptable values for the 'registry' parameter, and it omits any mention of error handling or prerequisites, leaving minor gaps in completeness.

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 0%, so the description must compensate. It maps 'names' to 'a whole dependency list' and implies registry via the mention of package manifests (npm, PyPI, Cargo, Composer, Gemfile), but it never explicitly defines what the 'registry' parameter should contain (e.g., name, URL, ecosystem). The description is ambiguous about the exact values expected for 'registry'.

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 the specific verb 'Read' and identifies the exact resource: a whole dependency list. It lists four specific outputs: archived state, advisories, source-available license, and stale (not pushed in a year). This clearly distinguishes it from sibling tools like 'check_package' (single package) and 'audit_manifest'.

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?

It explicitly states 'Use when reviewing a package.json, requirements.txt, Cargo.toml, composer.json or Gemfile.' This gives concrete context for when to use the tool, though it does not explicitly mention alternatives or when not to use it. Still, the use case is clear and actionable.

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