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

The description adds significant behavioral details beyond annotations: file returns content inline, directory saves to disk and returns localPath. It discloses limits (300KB max, branch naming), input constraints (mutually exclusive params), and mode-specific behaviors. No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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 uses a well-organized structure with headings (<when>, <fromTool>, etc.) that front-load the main purpose and allow quick scanning. While lengthy due to necessary detail (gotchas, examples), every section adds value and the conciseness is appropriate for the 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?

The description covers all aspects for effective use: when to use, how to use (modes, params), pitfalls (gotchas), examples, and integration with siblings. It mentions prerequisites for directory mode (ENABLE_LOCAL, ENABLE_CLONE) and the file size limit. The output schema exists separately, so return values are omitted by design.

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 already has 100% description coverage, but the description adds value by explaining the three mutually exclusive file modes (matchString, startLine+endLine, fullContent) and the pagination parameters (charOffset, charLength) in the <gotchas> and <modes> sections, enhancing practical usage understanding.

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 reads a GitHub file or downloads a directory, with specific verbs ('read', 'download') and resource ('GitHub file or directory'). It distinguishes from siblings like githubSearchCode (search) and githubViewRepoStructure (structure), and the title 'GitHub File Content Fetch' reinforces the purpose.

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 <when> section provides clear contexts (e.g., read from known path, download directory). The <fromTool> and <toTool> sections guide use in conjunction with other tools. However, it lacks explicit 'when not to use' guidance, though the modes and gotchas imply exclusions (e.g., directory mode requires specific flags).

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 declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds substantial behavioral detail beyond annotations, including strict prefix matching for 'path', pagination parameters, match type behavior, and filtering 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 long but well-structured with clear sections (<when>, <fromTool>, <toTool>, <gotchas>, <examples>). It is front-loaded with essential usage context, though some redundancy exists (e.g., repeating 'match' behavior in multiple places).

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 with nested queries and multiple parameters, the description is remarkably complete. It covers when to use, how to chain with other tools, gotchas, and examples. The presence of an output schema reduces the need to explain return values.

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?

Input schema covers all parameters with descriptions, and schema coverage is 100%. The description enriches parameter understanding with contextual advice like 'Start lean: single filter -> verify -> add filters' and explicit examples, adding meaning beyond 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 clearly states that the tool searches GitHub code, with explicit directives to 'Find code patterns' and 'Locate files by path'. It distinguishes between match=file and match=path, and mentions cross-repo usage. Sibling tools like githubSearchRepositories and githubGetFileContent are differentiated through usage guidance.

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 <when> section defines appropriate contexts, and <fromTool> and <toTool> sections provide explicit sequencing with sibling tools. The <gotchas> section offers critical do's and don'ts, such as avoiding combining extension+filename+path and preferring owner+repo for precision.

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 and idempotentHint=true. The description adds critical behavioral details in the <gotchas> section, such as 'prNumber ignores ALL other filters' and 'Avoid fullContent on large PRs (token expensive)', which go beyond annotations. No contradiction.

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 clear sections (<when>, <fromTool>, <toTool>, <gotchas>, <examples>) and is front-loaded with the title and external API note. While comprehensive, it is relatively long, but each section earns its place given 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?

Given the tool's complexity (many parameters, nested query objects, relationships to siblings) and the presence of an output schema (not shown), the description covers usage patterns, gotchas, and integration with other tools comprehensively. It provides enough context for an agent to use it effectively.

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% with detailed descriptions for each parameter, so baseline is 3. The description adds value through concrete examples showing parameter combinations and the gotcha about prNumber. However, the description does not elaborate on parameter semantics beyond what the schema already provides, so it does not fully compensate for the high schema coverage.

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's purpose: 'Search GitHub Pull Requests'. The <when> section provides specific use cases like code archaeology and implementation history, and the fromTool/toTool sections differentiate it from sibling tools by showing how they relate.

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 <when> section explicitly outlines when to use this tool (code archaeology, implementation history) and suggests a workflow (metadata first, then partialContent). The fromTool and toTool sections provide clear guidance on alternatives and sequencing, e.g., using githubSearchCode first, then this tool.

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, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds valuable behavioral context: gotchas like pushedAt vs updatedAt distinction, stars filter noise, archived auto-exclusion, and synonym suggestions. Adds significant value beyond 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 moderately long but well-structured with clear sections (<when>, <fromTool>, <toTool>, <gotchas>, <examples>). Every section adds value and the front-loading of purpose is good. Slightly verbose but acceptable given 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?

Given the complexity of the tool (multiple query parameters, pagination, interaction with other tools), the description is complete. It covers usage context, tool flow, gotchas, and examples. Output schema exists, so return values are not needed.

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% with detailed parameter descriptions (e.g., stars filter format, match enum). The description itself doesn't add much beyond schema for individual parameters but provides examples that illustrate usage. Baseline 3 is appropriate as schema does the heavy lifting.

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 'Search GitHub repositories' and distinguishes from sibling tools like packageSearch (faster for known packages) and githubSearchCode (code search). The purpose is specific and unambiguous.

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 includes explicit <when> usage context (external research, finding repos) and <fromTool>/<toTool> sections that guide the flow between tools. It also names alternatives like packageSearch for known packages, providing clear when-to-use 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds crucial behavioral details in '<gotchas>': depth=2 slowdown, auto-filtering of noisy dirs (e.g., .git, node_modules), maximum 200 items, and the need to check summary.truncated. No contradictions.

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 clear sections (<when>, <fromTool>, <toTool>, <gotchas>, <examples>) that are front-loaded and efficient. Every sentence provides actionable information with no redundancy, making it easy for an agent to parse and apply.

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 complexity, output schema existence, and full schema coverage, the description covers all necessary aspects: use cases, workflow, gotchas, examples, and tool interactions. It leaves no critical gaps 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 coverage is 100%, so baseline is 3. The description adds value through examples (e.g., path='', depth=1; path='src', depth=2) and gotchas that clarify parameter usage (starting from root, depth constraints). While not exhaustive, it enhances understanding beyond 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 clearly states 'Display GitHub repo structure' and positions it as an entry point for understanding layout and discovering paths. It explicitly distinguishes from sibling tools like githubSearchCode and githubGetFileContent via the 'toTool' section, ensuring no ambiguity.

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?

Provides explicit <when> section describing use cases (Understand layout, Discover paths, Entry point) and a workflow (Root depth=1, then Drill path+depth=2). Also includes 'fromTool' and 'toTool' sections that guide the agent on tool chaining, offering clear when-to-use and when-to-alternate 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?

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds valuable behavioral context: performance note ('Faster than content search due to metadata indexing'), default exclusion directories, time format examples, and pagination details (filesPerPage, charOffset). No contradictions 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 well-structured with clear sections (when, fromTool, toTool, gotchas, examples) and front-loads the core purpose. However, it is relatively verbose; could be more concise by removing redundant phrases. Still easily scannable.

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 (many parameters and pagination), the description provides comprehensive context: usage workflow, examples, performance characteristics, and exclusion defaults. An output schema exists, so return value explanation is not needed.

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% with individual parameter descriptions. The description enhances understanding via examples (e.g., time formats '7d', '2h') and gotchas (e.g., excludeDir defaults), but does not add new meaning for each parameter beyond what schema already provides.

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 finds files by metadata (name, time, size, permissions) on the local filesystem. It explicitly distinguishes from sibling tools: 'NOT for content - use localSearchCode' and fromTool section links to localViewStructure, making differentiation unambiguous.

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 <when> section provides explicit guidance on when to use (metadata search, scope narrowing, recent changes) and when not to (content search, directing to localSearchCode). The <fromTool> and <toTool> sections further specify workflow ordering with other tools.

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 and destructiveHint=false. The description adds significant behavioral context beyond annotations, such as the ability to read specific lines, match patterns, pagination via charOffset/charLength, and token efficiency warnings for large files. There is 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 well-structured with clear sections (<when>, <gotchas>, <examples>) that are front-loaded. Despite length, every section earns its place by providing essential context, guidelines, or examples. No redundant information.

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 (multiple parameters, pagination, batch queries) and the presence of annotations and output schema, the description is complete. It covers when to use, how to use, pitfalls, examples, and alternatives, leaving no ambiguity for the agent.

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 baseline is 3. The description adds value beyond the schema through examples and gotchas that illustrate parameter combinations (e.g., using startLine/endLine for known ranges, fullContent for small configs). It clarifies pagination parameters and the batch nature of queries, which enhances understanding.

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 'Read file content [LOCAL: filesystem]' and lists specific use cases in the <when> section, such as reading implementation after locating with search/LSP and reading configs/docs directly. It also distinguishes from sibling tools by stating 'Direct read OK for: configs, docs, .json, .md, .yaml' and providing alternatives like LSP tools for certain tasks.

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 extensive usage guidelines through sections like <when>, <fromTool>, <flow_questions>, and <gotchas>. It explicitly tells when to use the tool, when to prefer alternatives (e.g., LSP tools for flow analysis), and best practices (e.g., use matchString for large files, startLine/endLine for known ranges).

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 indicate read-only, non-destructive, idempotent behavior. The description adds gotchas like lineHint being 1-indexed, filesOnly for fast discovery, and type filter efficiency, providing additional behavioral context beyond annotations. No contradictions.

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 clear sections (<when>, <fromTool>, <toTool>, <gotchas>, <examples>), front-loaded with a summary. Each section is concise and serves a distinct purpose without redundancy.

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 (many parameters) and the presence of an output schema, the description provides sufficient context with examples, workflows, and gotchas. It covers usage beyond the schema, making it complete for an agent to use effectively.

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 parameters are well-documented. The description adds value through examples and gotchas (e.g., filesOnly, type filter), but does not elaborate on each parameter since the schema already does. Baseline 3 is elevated to 4 due to practical usage tips.

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 searches code patterns using ripgrep, listing specific use cases like function finding, symbol lookup, and pattern matching. It distinguishes from sibling tools like localFindFiles and localViewStructure by referencing them in the <fromTool> and <toTool> sections.

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 <when> and <toTool> sections provide explicit guidance on when to use this tool and how it fits into workflows with LSP or alternative tools (e.g., lspGotoDefinition, lspFindReferences). It also suggests self-refining patterns.

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, destructiveHint, and idempotentHint. The description adds valuable behavioral context: auto-excludes (node_modules, .git, dist), performance warnings (depth=2 slow on large dirs), and pagination behavior. This goes beyond annotations without contradiction.

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 clear sections (<when>, <fromTool>, <toTool>, <gotchas>, <examples>). It is front-loaded with the core action and usage context. While comprehensive, it remains concise and each section earns its 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 (local filesystem, many parameters, sibling tools) and the existence of an output schema, the description covers all necessary contexts: usage scenarios, workflow guidance, pitfalls, sibling differentiation, and examples. It is fully complete for AI agent understanding.

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 mentions key parameters (path, depth, pattern, filesOnly) in examples and gotchas but does not add significant semantic detail beyond what the schema descriptions provide. Some parameters like 'charOffset' have empty descriptions in schema, but the description does not address them.

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 'View directory structure' and provides explicit examples and usage patterns. It distinguishes itself from siblings by outlining when to use this tool versus localFindFiles, localSearchCode, etc., making the purpose unambiguous.

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 <when> block explicitly describes when to use the tool, including workflow steps (start depth=1, drill depth=2, then search). It also contrasts with sibling tools in <fromTool> and provides situational advice like monorepo checks.

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 indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds useful context: requires lineHint (1-indexed), works cross-file, traces imports automatically, and is semantic. No contradictions. Could mention cost/expense in description itself, but schema covers that.

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?

Description is lengthy but well-structured with clear sections (when, prerequisite, fromTool, etc.) and front-loaded purpose. Every section adds value, but could be slightly more concise without losing clarity.

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 and the presence of output schema, the description covers all necessary aspects: prerequisites, alternatives, flow patterns, gotchas, and examples. No gaps in understanding how the tool works or how to use it.

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% with detailed descriptions for each parameter. The description adds examples and usage patterns but does not significantly enhance parameter semantics beyond what the schema already provides, meeting the baseline of 3.

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?

Description clearly states 'Trace function call relationships [LOCAL: LSP]' and distinguishes between incoming/outgoing directions. It also includes a dedicated section comparing with sibling lspFindReferences, making the purpose unambiguous.

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?

Provides explicit when-to-use scenarios via <when> tags (e.g., 'Who calls this?' for incoming), prerequisite requirements (lineHint from localSearchCode), and alternatives (lspFindReferences for non-call usages). Also includes flow patterns and examples.

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 specify readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds useful behavioral details such as the requirement for lineHint, case-sensitivity of symbolName, and that includeDeclaration defaults to true, but does not contradict 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 well-structured with clear sections, bullet points, and examples. It is somewhat lengthy but each section is informative and front-loaded with the core purpose, making it easy to scan.

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 with multiple parameters and nested queries, the description covers prerequisites, common pitfalls, integration with other tools, and provides examples. An output schema exists, so return values are not required. The description is complete and actionable.

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% with detailed descriptions for each parameter. The description adds value by highlighting critical constraints like 'lineHint required (1-indexed)' and providing examples, enhancing understanding beyond the schema alone.

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 'Find all usages of a symbol' and provides examples like 'Where is X used?'. It distinguishes itself from siblings like lspCallHierarchy, which focuses on call relationships.

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 includes explicit <when> section, prerequisites from localSearchCode, <fromTool> and <toTool> dependencies, and a comparison with lspCallHierarchy, providing comprehensive guidance on when to use this tool vs alternatives.

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, destructiveHint=false. The description adds behavioral details: requires lineHint (1-indexed from localSearchCode), symbolName must be exact, tool searches +/-2 lines, batching support (1-5 per call), and pagination parameters. 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?

Well-structured with markdown sections, front-loaded with purpose. Every section (when, prerequisite, fromTool, toTool, gotchas, examples) provides essential information without redundancy. Concise yet comprehensive.

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 output schema exists, return values need no explanation. The description covers prerequisites, gotchas, relationships with siblings, and examples. For a tool with complex parameter dependencies and batching, this is complete and self-contained.

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?

Input schema has 100% description coverage, so baseline is 3. The description adds value by explaining cross-tool dependencies (lineHint from localSearchCode), exactness of symbolName, and default values for orderHint/contextLines, which helps the agent construct correct parameters beyond schema definitions.

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 'Navigate to symbol definition' with specific verb and resource. The <when> section delineates exact use cases (find definition, trace import) and the <fromTool>/<toTool> sections distinguish this from siblings like lspFindReferences and lspCallHierarchy.

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 <when> and <prerequisite> sections state when to use and that lineHint from localSearchCode is required. The <toTool> section lists alternatives (e.g., lspFindReferences for usages) and <gotchas> note when to fall back to external search (packageSearch -> githubGetFileContent).

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, idempotentHint, and non-destructive behavior. The description adds critical behavioral details: searchLimit defaults (1 for known, 5 for alternatives), Python returns only 1 result, naming conventions (dashes vs underscores), and the need to check deprecation warnings. No contradictions.

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 clear sections (titles, when, fromTool, toTool, vsGitHub, gotchas, examples). It is comprehensive without being overly verbose. Slightly more concise could be achieved, but it is appropriate 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?

Given the complexity of the tool (multi-parameter array, two ecosystems), the description covers all essential aspects: external APIs, behavior differences, pagination, deprecation, and integration with sibling tools. The schema and output schema handle the rest, leaving no gaps.

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% with detailed property descriptions. The description adds value through <gotchas> (e.g., Python always returns 1, naming conventions) and <examples> (concrete usage of name and ecosystem). This exceeds the baseline but not by a large margin.

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?

Title and description clearly state 'Find NPM/Python packages' and specify that it provides repository URLs. The <vsGitHub> section explicitly distinguishes from githubSearchRepositories, making the purpose specific and unambiguous.

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 <when> section lists clear use cases: lookup by name, get repo URL, compare alternatives, check deprecation. The <fromTool> and <toTool> sections provide chaining guidance, and <vsGitHub> advises using this tool first for known names versus githubSearchRepositories for broad discovery.

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