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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description is consistent with both. It adds substantial behavioral context beyond annotations: per-branch semver max-satisfying resolution rather than npm/yarn hoisting/dedup emulation, only the dependencies field being followed, unresolvable git/file/URL deps surfacing as resolutionError instead of being skipped, a total node budget requiring checks of truncated/truncationNote, and a deterministic summary field to read first.

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 every section earns its place: mechanics with defaults, guidance on which output fields to read first, four material limitations that affect how results must be interpreted, and a routing sentence to the sibling tool. It is front-loaded with the core verb and resource, and the caveats are organized so an agent can parse them in dependency order.

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 complex tool with recursive traversal, semver range resolution, and an external vulnerability-checking service, the description is complete: it covers defaults, caps, unsupported dependency types, truncation behavior, result-field semantics, and the sibling alternative. The output schema exists so return values need not be restated, yet the description still explains the three most important fields (summary, vulnerablePaths, nodes) for correct result interpretation.

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 baseline is 3; the description adds value on top by explaining how packages and version ranges actually behave: ranges are "resolved independently per branch via semver max-satisfying against published versions," maxDepth reflects how many levels beyond roots are expanded, and the 0-level meaning is clarified in the schema. It also gives the reason for the maxDepth cap (registry call bounds and timeout), which the schema's bare maximum does not convey.

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 specific verb and resource: it "recursively resolves one or more direct/root packages' dependency graphs" and "batch-checks every resolved package@version against OSV.dev." It also distinguishes itself from siblings by explaining the graph-walking scenario it is uniquely suited for and explicitly naming batch_query_vulnerabilities as the alternative for flat-list checks.

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 routes to the alternative: "Prefer batch_query_vulnerabilities instead when you only need to check exact packages you already have a flat list for (faster, no graph walk)." It also states the when-to-use case — surfacing vulnerabilities buried several levels down that direct-dependency checking would miss — and gives concrete scope caveats an agent must know before trusting a clean result.

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