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

With annotations already covering safety (readOnly, idempotent, non-destructive), the description adds valuable behavioral context: the prerequisite to resolve the library ID, a rate limit (max 3 calls per question), and the fact that it retrieves up-to-date docs and code examples. These details go beyond annotation equivalents and help the agent understand the tool's constraints.

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 well-structured, starting with the tool's core purpose, then proceeding to usage constraints. Every sentence serves a purpose: official status, preferred use cases, prerequisite action, exemption for explicit IDs, and call limit. No redundant phrasing or fluff.

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 2-parameter tool with rich schema descriptions and clear annotations, the description covers all key operational aspects: official nature, prerequisite resolution, alternatives to avoid, and call limits. Even though there is no output schema, the tool's return type (docs/examples) is implicit, and the description provides sufficient context for correct invocation.

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?

The input schema provides 100% coverage with detailed descriptions for both parameters—libraryId includes examples and origin ('resolve-library-id' or user query), and query includes specificity guidance, examples, and security warnings. The tool description adds no extra parameter meaning beyond what the schema already offers, so 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 identifies the tool as the official Context7 documentation query tool with a specific action ('retrieve authoritative docs and examples') and resource ('library documentation'). It distinguishes itself from web_search/web_fetch by stating it should be preferred for library/framework documentation, and references resolve-library-id as the prerequisite tool.

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 instructs to prefer this tool over web_search/web_fetch for library/framework documentation, providing clear when-to-use guidance. It mandates calling 'Resolve Context7 Library ID' first unless the user supplies a library ID, and imposes a hard limit of no more than 3 calls per question—specific, actionable usage rules.

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

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.

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

With no annotations, the description carries the full burden and does well: it discloses URL format requirements, automatic HTTP->HTTPS upgrade, format options with default, response size limit (5MB), and timeout (120s). This goes beyond the minimal and provides useful operational expectations.

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 well-structured with a clear main statement followed by usage notes. It front-loads the core purpose and each bullet adds value without redundant repetition, making it appropriately sized for the tool's complexity.

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?

Despite lacking an output schema, the description covers input requirements, behavior, format options, size/timeout limits, and relationship to sibling tools. This is a self-sufficient explanation for how to invoke web_fetch correctly.

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% and already includes URL, format enum, and timeout range. The description adds extra meaning by explaining the URL must be fully-formed and valid, and that HTTP URLs are upgraded to HTTPS, which supplements the schema.

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 opens with a specific verb+resource: 'Fetches content from a specified URL and converts it to readable format.' It clearly distinguishes itself from searching and sibling tools like web_search by stating 'not for searching.'

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?

Explicit guidance is provided: 'Use this when you have a specific URL to retrieve (not for searching)' and 'Use web_search first to find URLs, then use this tool to fetch their content.' It also mentions preferring Context7 for documentation, giving clear when-to-use and alternative guidance.

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

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

With no annotations, the description carries the transparency burden. It discloses key behaviors: single API call, free/no API key required, supports English and Chinese, returns search result snippets. It does not mention rate limits or potential search restrictions, but covers the main user-relevant aspects.

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 well-structured with bullets and a separate usage notes section, front-loading the core purpose. Some redundancy exists between 'performs real-time web searches' and 'provides up-to-date information', and the bullet list is slightly verbose, but overall it remains focused and readable.

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 two-parameter tool with no output schema, the description provides complete context: what it does, return format (titles, URLs, snippets), usage guidelines, alternative tools, language support, and auth requirements. It is sufficient for an agent to select and invoke the tool correctly.

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 description coverage is 100%, so the baseline is 3. The description does not add further meaning to the query or numResults parameters beyond what the schema already states (e.g., query content and result count with default). It names the tool's output but not parameter-specific 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 clearly states the tool performs real-time web searches using DuckDuckGo and returns titles, URLs, and snippets. It also explicitly distinguishes from siblings by directing URL retrieval to web_fetch and documentation queries to Context7, making the purpose unmistakable.

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 provides explicit guidance on when to use this tool: for general web searches, current information, and queries beyond the model's knowledge cutoff. It also names alternatives: web_fetch for specific URLs and Context7 for API/library documentation, giving clear exclusions.

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