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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral detail beyond these: it discloses that on a cache miss it uses bounded live GitHub/OpenSSF evidence with limited confidence and explicit unknowns rather than fabricated certainty. This is honest about limitations and return variability based on cache state.

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, tightly packed with useful information: when to call, what's returned, accepted formats, and behavioral caveats. No wasted words or repetition of annotation content. Front-loaded with the trigger condition.

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?

Tool has an output schema and rich annotations, so description needn't cover return value structure. It covers trigger condition, target format inputs, evidence sourcing behavior, and confidence caveats. For a comparison tool with simple two-string inputs and disclosed fallback strategy, this is complete.

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 both parameters a and b are documented. The description also adds meaning by explaining accepted formats (owner/repo, GitHub URL, npm package name, npm:@scope/pkg) which extends beyond the schema's generic 'repo or npm package target'. However, it doesn't clarify dimensional/ordering semantics (e.g., whether a/b order matters) beyond what the schema provides, so a baseline 3 is appropriate.

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 compares two repository/dependency choices and lists what it returns (preferred candidate per use case, trade-offs, confidence, evidence gaps). It explicitly scopes to 'exactly two' choices, distinguishing it from single-repo analysis siblings. The accepted target formats are enumerated.

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 states when to CALL ('when the user is choosing between exactly two dependencies or repositories') and implies when NOT to (single choice). It describes the fallback behavior: cached analyses preferred, bounded live evidence on miss with explicit unknowns rather than guessing. This provides strong guidance for selection.

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