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

Beyond the read-only, open-world, idempotent, non-destructive annotations, the description discloses that the tool checks live npm/UNPKG data, returns four classification categories with suggested URLs and an import map, and reports currentUsage as absent rather than falsely 'not detected' when scanning was skipped. This adds meaningful behavioral context not covered by 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?

The description is front-loaded with the main purpose and then covers prerequisites and important edge cases in a logical order. It is somewhat long and repeats some return-category information that is also likely covered by the output schema, but the sentences generally earn their place.

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, nested object parameters, live external data lookup, and the presence of an output schema, the description is complete enough for an agent to call it correctly. It covers data collection, runtime-only dependency filtering, scanning prerequisites, and the key behavioral consequence of not scanning.

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, but the description adds actionable meaning beyond the schema: it specifies that the dependencies map must come from the project's package.json and must contain only runtime dependencies, never devDependencies. It also reinforces the scanned/not-scanned semantics of existingImports and the resulting currentUsage behavior.

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: classify runtime dependencies for conversion to direct UNPKG file lookups, with named output classifications and an import map. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as estimate_migration_impact or generate_importmap.

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 gives concrete pre-call guidance: read package.json yourself, pass only runtime dependencies, and scan HTML/files for existing import maps and CDN URLs before calling. It explains the consequence of not scanning, but it does not name alternative sibling tools or state when not to use this one.

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