Resolve Context7 Library ID

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, but the description goes beyond by detailing result fields (Library ID, Name, Description, Code Snippets, Source Reputation, Benchmark Score, Versions), the selection process, and the response format. It also discloses the limit of 3 calls and the instruction to suggest query refinements if no matches. No contradiction with 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 long but well-structured with sections for intro, usage, result fields, selection process, and response format. It is front-loaded with the primary purpose and usage rule. Some redundancy exists between the result fields list and the selection criteria (e.g., code snippets and reputation are mentioned twice), but overall it earns its length without being wasteful.

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?

There is no output schema, so the description carries full responsibility for explaining return values—and it does comprehensively, listing all result fields and their meanings. It also covers edge cases: ambiguous queries, multiple matches, no matches, and version handling. Given the tool's central role in the workflow, the description is complete and self-sufficient.

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 baseline is 3. The description adds extra meaning by giving examples for libraryName ('Next.js' instead of 'nextjs', 'Customer.io' instead of 'customerio') and a security warning for query (do not include sensitive info). It also explains that query is used for ranking relevance, which the schema only partially implies. These enrichments justify a score above 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 it is an 'Official Context7 library resolver' that 'Resolves a package/product name to a Context7-compatible library ID and returns matching libraries.' It specifies a concrete verb and resource, and explicitly differentiates from siblings by stating 'Prefer this over web_search for software documentation tasks.' This makes the tool's purpose distinct.

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 explicit usage guidance: 'Use this first when the user asks about a library...' and 'Prefer this over web_search for software documentation tasks.' It also mandates a sequence: 'You MUST call this function before the Query Documentation tool' unless the user provides a library ID. It further provides exclusion rules (max 3 calls) and handles ambiguous queries with clarification.

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