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

Annotations already mark it as read-only; description adds specifics about returned data (documentation, types, JSDoc, code actions) without contradicting annotations. Discloses additional behavioral traits beyond the read-only hint.

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, no redundant information. Front-loaded with verb and resource, then details. Every sentence serves a purpose.

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?

No output schema, but description compensates by listing return values (documentation, type signature, etc.). For a 4-param tool with 100% schema coverage, the description provides sufficient context for an agent to invoke 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 covers all 4 parameters with descriptions; description adds minimal extra meaning (confirms multiple entries via entryNames). 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?

Description clearly states the tool retrieves full details for completion entries, explicitly lists included information (documentation, type signature, JSDoc, code actions), and distinguishes itself as a follow-up to completionInfo.

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?

Description positions it as a follow-up to completion_info, implying sequential usage. It does not explicitly mention when not to use or list alternatives, but the context is clear enough for an AI agent.

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, so the description's claim of returning completions adds limited behavioral context. It does not mention error handling, performance, or scope of input, making it adequate but not outstanding.

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 with no extraneous words. The first sentence front-loads the core action and resource, and the second adds useful detail about return values.

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 5 parameters, no output schema, and many siblings, the description adequately explains the return content and purpose. However, it could mention the output structure (array of completions) or edge cases like no completions.

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 description adds no additional meaning to the parameters. It restates the overall purpose without enriching any parameter details.

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 verb 'Get' and the resource 'autocomplete suggestions at a position', and lists the returned fields (kinds, sort text, insert text). This precisely distinguishes it from sibling tools like completionEntryDetails.

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?

It explains the tool is useful for understanding available symbols at a location, but does not explicitly mention when not to use it or name alternatives (e.g., completionEntryDetails). This leaves some ambiguity for the agent.

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?

The description adds the 'fundamental query' context but doesn't detail behavior beyond what annotations (readOnlyHint) already convey. It doesn't mention multiple definitions, error handling, or output format. With annotations covering safety, minimal extra value.

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?

Extremely concise: two sentences, no redundant words. The question format in the second sentence front-loads the core query intent. Every word 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?

Despite good annotations and full schema, the description lacks completeness given the complex sibling toolset and absence of output schema. It doesn't explain the return format (e.g., array of locations) or edge cases (symbol not found). More context would improve decision-making.

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?

All three parameters are fully described in the schema (100% coverage). The description adds nothing about parameters; schema already defines file, line, and offset, including their types and meanings. Baseline of 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 it returns file location(s) where a symbol is defined, using the simple question 'where is this thing declared?' This distinguishes it from siblings like definitionAndBoundSpan and findSourceDefinition, making the purpose immediately understandable.

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?

No guidance on when to use this tool over alternatives like definitionAndBoundSpan or findSourceDefinition. In a toolset with many similar navigation tools, explicit usage context is missing, leaving the agent to guess.

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, so the tool is read-only. The description adds that it returns definition locations and the textSpan, which is useful but not extensive. No contradictions exist between description and 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 very concise with three short sentences. It front-loads the key comparison to 'definition', then adds usage context, and finally states the return values—all without unnecessary words.

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 adequately explains the tool's purpose and its difference from 'definition'. However, since there is no output schema, more details about the exact structure of the returned textSpan would improve completeness.

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% for all 3 required parameters, so baseline is 3. The description does not provide any additional information about the parameters beyond what the schema already documents.

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 'Like 'definition', but also returns the span of the symbol at the cursor.' It names the specific verb 'returns' and resource (definition locations and textSpan), distinguishing it from the sibling 'definition' 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 references the sibling 'definition' and explains the added value ('also returns the span'), implying when to use it. It also states 'Useful for understanding exactly which characters constitute the symbol,' providing clear context. However, it does not explicitly state when not to use it or mention alternatives beyond 'definition'.

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, indicating no side effects. The description adds the detail that the returned text can be inserted above the function declaration, but does not provide further behavioral insights. Minimal additional value.

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 two sentences long, front-loading the purpose and adding a usage hint. No wasted words; every sentence 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?

For a simple tool with 3 required params, full schema coverage, no output schema, and read-only annotations, the description is sufficient. It communicates the core function and return value. Could mention that the function must be parseable, but not critical.

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 description has low burden. It mentions 'at a position' but offers no extra meaning beyond the schema definitions for file, line, and offset. Baseline score applies.

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 generates a JSDoc comment template for a function, method, or class, specifying the verb 'Generate' and resource 'JSDoc comment template'. It also mentions the output includes @param and @returns tags based on function signature, distinguishing it from sibling tools like signatureHelp.

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?

No guidance on when to use this tool versus alternatives. There is no mention of prerequisites or situations where this tool should not be used, leaving the agent to infer usage context from the description alone.

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, confirming no mutation. The description adds behavioral nuance by stating it distinguishes between read and write references, which is valuable beyond annotations. No side effects or destructive behavior are present, so a score of 4 is appropriate.

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 two sentences long with no fluff. Critical information (purpose, differentiation, efficiency) is front-loaded. Every sentence serves a clear purpose.

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 no output schema, the description does not explain the return format (e.g., positions with read/write kind). While the purpose is clear, the absence of output details leaves the agent partially uninformed about what to expect.

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 coverage is 100%, so the schema already documents all parameters with descriptions. The description mentions 'file (or set of files)' which aligns with the file and filesToSearch parameters, but adds no extra semantic value beyond what the schema 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 occurrences of a symbol within files, distinguishes between read and write references, and explicitly differentiates from a similar tool (find_all_references) by noting efficiency for local occurrences.

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 when-to-use guidance: 'More efficient than find_all_references when you only need local occurrences within specific files.' It also implies when not to use (avoid for broad searches) and distinguishes read/write references.

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?

The description adds some behavioral context beyond annotations: it mentions TypeScript infers the type and that the response includes rename info. However, the destructiveHint annotation already indicates modification, and the description does not elaborate on the effect on the file or other side effects.

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 two sentences, concise and to the point, with no unnecessary words. It efficiently communicates the tool's purpose and a key follow-up detail.

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 the essential purpose and a crucial output detail (rename info) for follow-up. Since there is no output schema, the description compensates reasonably well. However, it could mention where the constant is placed or any default naming behavior.

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% (all parameters have descriptions). The description does not add additional meaning to the parameters beyond what the schema already provides, so a baseline score of 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 action ('Extract') and the resource ('selected expression into a named constant'). It distinguishes from sibling tools like extractFunction and extractType that extract into different constructs.

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 explains when to use this tool (to extract an expression into a constant) and suggests a follow-up action (rename_symbol). While it does not explicitly exclude other tools, the clear purpose implicitly differentiates it from siblings.

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 mark destructiveHint=true, but the description adds value by mentioning auto-detection of parameters and return type, and the response includes renameFilename/renameLocation for follow-up. This informs the agent about side effects and response structure.

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 concise sentences: first states the primary action, second provides key follow-up information. No redundant or unnecessary words.

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 tool with 6 required params and no output schema, the description covers the core action, behavioral notes, and follow-up steps. It could mention that the original code is replaced with a function call, but the destructive hint implies that.

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 descriptions for all 6 parameters. The description does not add additional semantics beyond what is already in the schema; it only reiterates the purpose in general terms.

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 verb 'Extract' and resource 'selected code range into a new function'. It distinguishes from sibling tools like extractConstant and extractType by specifying 'function'.

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 follow-up guidance to use rename_symbol for naming, which helps the agent understand the workflow. However, it does not explicitly contrast with other extraction tools or indicate when function extraction is preferred over constant/type extraction.

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 indicate destructiveHint=true, and the description adds that the response includes renameFilename/renameLocation, explaining the output behavior beyond the annotation.

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 concise sentences that efficiently convey purpose, usage, and follow-up steps with no superfluous 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?

The description covers the core functionality and response content, and the annotation fills in the destructive nature. It is sufficiently complete for a tool with six required parameters.

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 mentions selecting the type span but does not add significant extra meaning beyond the schema's parameter descriptions.

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 extracts an inline type annotation into a named type alias, distinguishing it from sibling tools like extractConstant or extractFunction.

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?

It tells when to use ('Select the type span to extract') and suggests a follow-up action with rename_symbol, providing clear usage context without explicit exclusions.

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. Description adds specific behavioral context (finding importing/referencing files). 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?

Single sentence, no filler, front-loaded with purpose. Every word is informative.

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?

Adequate for a simple one-parameter tool with annotations. Does not describe output format but implies a list of files. Could be more complete but 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 the schema fully documents the 'file' parameter. Description does not add further meaning beyond what is in 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?

Clearly states the verb 'finds' and resource 'every file that imports or references a given file'. Distinguishes from sibling 'references' by specifying it is the reverse dependency graph.

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 clear context ('reverse dependency graph') but does not explicitly state when to use this tool versus alternatives like 'references'. No exclusions mentioned.

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, so no contradiction. The description adds that the tool navigates to source instead of .d.ts, which is a key behavioral detail beyond the annotation.

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, front-loaded with the main purpose. No unnecessary words; every sentence adds value.

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 simple lookup tool with three fully documented parameters and no output schema, the description sufficiently explains purpose and usage. Could optionally mention behavior when source maps are unavailable, but not necessary.

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% and each parameter (file, line, offset) has clear descriptions. The description does not add extra meaning beyond what the 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 verb 'Navigate' and the resource 'actual TypeScript source instead of .d.ts declaration files', distinguishing it from sibling tools like 'definition' which target declaration files.

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 context ('when working with libraries that have source maps or when you want to see the implementation rather than just the type declarations') but does not explicitly state when not to use it or name specific alternative 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 destructiveHint=true and idempotentHint=true. Description adds context about applying consistent indentation/spacing/line breaks and preview mode. 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?

Two concise sentences front-loading purpose and usage. No redundant information; every sentence adds value.

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 (7 params, nested options, destructive behavior), description is adequate but not exhaustive. Lacks details on return value (no output schema) and effects beyond format, but schema and annotations cover much.

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 already documented. Description adds some context (range vs full file, preview behavior) but does not significantly enhance understanding beyond 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 the verb 'Format' and resource 'a range of code according to TypeScript's formatting rules.' It specifies the scope (range or full file) and distinguishes from sibling tools like 'organizeImports' or 'rename' by focusing on formatting behavior.

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 clear usage hint: specify a range or use full file length. Does not explicitly mention when not to use or alternatives, but the sibling list includes no other formatting tool, so omission is acceptable.

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. The description adds behavioral context by detailing the return value: 'list of available refactors with their actions, descriptions, and reasons why certain actions may not apply'. 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?

Two sentences, front-loaded with purpose, no fluff. Every sentence adds value: first states purpose, second provides usage guidance and output description.

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?

No output schema, but description sufficiently explains the return value. Given the sibling tools, the description provides enough context for an agent to understand this is a read-only discovery tool.

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 schema already documents all parameters. The description does not add any additional parameter semantics beyond what is in the schema, meeting the 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 uses the verb 'Discover' and specifies 'refactorings available at a position or selection', clearly identifying the tool's purpose. It distinguishes from sibling refactoring tools like extractConstant by being the preliminary discovery step.

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?

States 'Use before attempting a refactor to see what's possible', providing clear when-to-use guidance. Does not explicitly mention alternatives, but the context of sibling tools implies this is the discovery step.

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?

Adds context beyond readOnlyHint annotation by specifying it returns 'raw list of code actions' from tsserver and is for TypeScript/JavaScript. 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?

Two sentences with no wasted words. Front-loaded with the core action and immediately follows with usage guidance.

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 no output schema, it adequately describes the return as a 'raw list of code actions'. Could mention structure or format, but sufficient for selection and invocation. Sibling differentiation is clear.

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 all 6 parameters. The description does not add new semantic information beyond the schema, but it reinforces the context of error codes and ranges.

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?

Clearly states the verb 'Get' and resource 'code fixes' for specific error codes at a range in TypeScript/JavaScript files. Distinguishes from sibling tools like getDiagnostics and getCombinedCodeFix by emphasizing it returns raw code actions.

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?

Explicitly instructs to 'Use getDiagnostics first to discover error codes and ranges, then pass them here.', providing a clear prerequisite and usage context.

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 indicate readOnlyHint=true and openWorldHint=false. The description adds that the tool returns the full set of file edits as a CombinedCodeActions response, which is useful behavioral context beyond the annotations. It 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 concise with two short paragraphs, front-loading the core purpose, followed by examples and workflow. Every sentence adds value without unnecessary verbosity.

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 has no output schema, the description sufficiently explains the return type (CombinedCodeActions response). Context is adequate for the agent to understand the tool's role among many code fix siblings, though it could mention that the fix is not applied immediately.

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 has 100% description coverage for both parameters. The description mentions that fixId comes from a code fix, but this adds minimal meaning beyond the schema definitions. 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 that the tool gets a combined code fix applying all instances of a fix across a file. It provides concrete examples ('Add all missing imports', 'Remove all unused variables') and distinguishes itself from the sibling tool getCodeFixes.

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 use getCodeFixes first to discover available fixId values, then pass fixId to this tool. This provides clear guidance on when and how to use it, with an explicit workflow.

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 indicate readOnlyHint=true, which is consistent. Description adds behavioral details (project requirement, conditional unused diagnostics) that go beyond annotations, enhancing transparency.

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?

Three concise sentences: purpose first, then conditions. No redundant information, each sentence adds value.

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 single required param, no output schema, and simple use case, description fully covers what the tool does, what it returns, and prerequisites. Nothing missing.

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% (one param described). The description does not add additional meaning beyond the schema's description of the 'file' parameter. Baseline score of 3 applies.

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 begins with a clear verb+resource: 'Get all errors, warnings, and suggestions for a TypeScript/JavaScript file.' It lists specific types of diagnostics, distinguishing it from sibling tools like completionInfo or getCodeFixes.

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?

Explicitly provides prerequisites: file must be in a tsconfig.json project, and conditions for unused-code diagnostics. Does not explicitly state when NOT to use or provide alternatives, but the context is clear.

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 effectively discloses key behaviors: automatic import path updates across the project, support for folders, and the preview mode that shows changes without applying. It does not cover error handling or mutation details beyond the preview parameter, which is acceptable for this tool's scope.

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 concise—three sentences with the main action front-loaded. Every sentence adds value, though the structure could be slightly improved by separating file and folder handling more distinctly.

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 is reasonably complete for a tool with no output schema, covering what the tool does and the preview feature. However, it does not describe the output format (e.g., applied changes vs. edit list) or potential side effects, leaving some 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 coverage is 100%, so the schema already explains the three parameters (from, to, preview). The description adds no additional parameter-specific meaning beyond what the schema provides, meeting the baseline for coverage but not exceeding it.

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 renames or moves a file/folder and updates import paths, specifying supported file types (.ts, .tsx, .js, .jsx). However, it does not explicitly differentiate from sibling tools like 'rename' or 'moveSymbol', which may have overlapping or distinct purposes.

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 implies usage when renaming/moving files with import path updates needed, but lacks explicit when-to-use/when-not-to-use guidance or comparisons to alternatives (e.g., the 'rename' tool for symbol renames). The context of tsserver auto-discovery is helpful but not directive.

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; description adds that it returns both a suggested new file name and existing files, though more detail on response structure would be helpful.

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 concise sentences that are front-loaded and contain no 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?

Covers key information but could elaborate on the return structure given no output schema; adequate for a tool with well-documented parameters.

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 provides full coverage with descriptions for all 5 parameters; description adds no extra meaning beyond what schema already conveys.

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?

Clearly states it retrieves suggested target files when moving a symbol, distinguishing it from sibling tools like moveSymbol.

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?

Explicitly advises to use this before moveSymbol, 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, so the agent knows it's a safe read operation. The description adds that it returns hierarchical structure and kinds, which is useful behavioral context 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 two sentences: first sentence states the core purpose, second explains return value and use cases. It is concise and front-loaded with essential 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?

For a simple tool with one parameter and no output schema, the description covers basic functionality and use case. However, it lacks specifics about the output format (e.g., start/end positions), which would help completeness.

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 one well-described parameter (file path). The description adds no additional meaning beyond the schema, so baseline score of 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 verb 'Get' and the resource 'code folding regions for a file.' It specifies the return of hierarchical structure with kinds (comment, region, code, imports), distinguishing it from sibling tools like navto or navtree.

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 mentions usefulness for understanding file structure and navigating large files, but does not explicitly state when to use this tool versus alternatives or provide exclusions among the 40+ sibling 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, indicating read-only behavior. The description adds that omitting the file parameter causes an error ('No Project'), which is valuable behavioral context beyond annotations. No contradiction detected.

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 two sentences, front-loading the core purpose and adding critical usage guidance. Every sentence adds value; no wasted words.

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 simplicity (single optional param, read-only annotation), the description is complete. It covers purpose, usage guidance, and a key error. However, it does not explicitly describe the return format (e.g., array of strings), which could be helpful but is not critical for a discovery tool.

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 description doesn’t need to repeat param details, but it adds context about why the file param is needed ('to establish a project context') and the consequence of omission. This 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 what the tool does: 'Returns the list of all error codes that have available code fixes.' It uses a specific verb ('Returns') and resource ('list of error codes'), and distinguishes itself from sibling tools by positioning it as a discovery tool before calling getCodeFixes.

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 says 'Use this as a discovery tool before calling getCodeFixes' and warns that omitting a file path will cause tsserver to throw an error. This provides clear context on when to use it and a prerequisite.

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, so the description does not need to reiterate safety. It adds context about the tool's purpose but does not detail return format or limitations.

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, no wasted words. The description is concise and front-loaded with the key purpose.

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 high schema coverage and read-only annotations, the description is mostly complete. It could mention that results are file locations, but overall sufficient for a navigation tool.

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 all parameters have descriptions. The description adds no additional parameter info beyond the schema, which is adequate.

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 concrete implementations of an interface or abstract class, with a concrete example (Serializable). This distinguishes it from sibling tools like definition, references, and typeDefinition.

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 implies when to use the tool (when you have an interface or abstract class), but it does not explicitly contrast with alternatives or mention when not to use it.

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 destructiveHint=true, and description confirms modification. Beyond that, description adds position requirement but lacks details on error cases (e.g., un-inferrable types, existing return types) or side effects (like formatting). Minimal behavioral context 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?

Two concise sentences, front-loaded with action. No wasted words. Efficiently communicates core purpose and a key constraint.

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 4 parameters (all required), no output schema, and only a destructiveHint annotation, the description is too brief. It omits important context: error conditions, handling of existing return types, exact position requirements (function name vs keyword), and what happens on preview. Incomplete for an agent to use 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 baseline is 3. Description does not add any extra meaning beyond the schema for parameters file, line, offset, preview. The position requirement is mentioned in the main text but not linked to the parameters explicitly.

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?

Clearly states the action (add return type annotation), resource (function), and mechanism (inferred by TypeScript). Includes specific position constraint (on function name or declaration keyword). Differentiates from sibling tools that are other refactoring or completion tools.

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?

No explicit guidance on when to use this tool versus alternatives like getCodeFixes or extractType. Only implies usage for adding inferred return types, but no exclusion criteria or context for when not to use.

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 indicate destructiveHint: true, and the description aligns by stating 'delete the declaration.' It adds behavioral context beyond annotations by specifying the positioning constraint and the replacement of all references, which is critical for correct invocation.

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 two sentences with no fluff. The first sentence states the purpose and effect, and the second provides essential positioning guidance. Every word 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?

For a well-known refactoring with a clear action and positioning requirement, the description is largely sufficient. It could be improved by noting potential failure cases or confirming that the tool directly modifies the file (implied by destructiveHint).

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 has 100% description coverage, so parameters are already well-documented. The description does not add new semantics for individual parameters beyond implying that 'line' and 'offset' should point to the variable name, which is more of a usage guideline.

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 action ('Inline a variable') and explains what it does ('replace all references with the variable's initializer and delete the declaration'). This distinguishes it from sibling refactoring tools like extractConstant or extractFunction, though it does not explicitly contrast them.

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 a specific usage condition: 'Position must be on the variable name in its declaration or any usage.' This guides where to invoke the tool but does not discuss when to use this refactoring versus alternatives (e.g., when to inline vs. extract), leaving usage context implied.

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 idempotentHint=true and destructiveHint=true. The description goes far beyond by detailing the exact matching algorithm (by name, only for certain node types), the behavior when match found vs. not found, the limitations of multiple contents entries, and the handling of non-existent files via a virtual buffer. 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-organized with headings, bullet points, and an example. It front-loads the core purpose and then systematically covers matching, limitations, and usage patterns. While every sentence adds value, the length is slightly high for a tool description; a more streamlined version could achieve perfect conciseness.

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 (four parameters, intricate matching logic, multiple edge cases like non-existent files and const/var unsupported) and the absence of an output schema, the description thoroughly covers all essential aspects. It explains matching scope, replacement versus append, how to handle multiple declarations, and how to create new files, leaving no gaps for an AI agent to fill.

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?

All four parameters are described in the input schema with 100% coverage. The description adds crucial meaning: it explains that without focusLocations, code is always appended; it clarifies that the focusLocations parameter enables name-based matching within a scope; and it provides a concrete example showing how to use contents and focusLocations together. This elevates understanding beyond the raw 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 'Map/insert/replace code snippets into a file. Designed for AI code generation workflows,' using a specific verb+resource and setting the tool apart. It also details how matching works and when to use alternatives, clearly distinguishing this tool from sibling tools like refactoring or completion services.

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 usage patterns: REPLACE a function, ADD new code, CREATE a new file, and explicitly states what is NOT supported (matching const/let/var) and what to do instead ('use standard file editing'). It also recommends using preview=true to verify output and explains the multiple contents limitation. This leaves no ambiguity about when and how to invoke the 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 provide destructiveHint=true. The description adds that it automatically rewires all imports across the project and creates the target file if it doesn't exist, which provides valuable behavioral context beyond the annotation.

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 three sentences, concise and front-loaded. It covers the main action, side effects, and edge case (target file creation). No unnecessary words, but could be more structured (e.g., bullet points).

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 no output schema, the description does not explain what the tool returns (e.g., a code edit or confirmation). It mentions 'preview' parameter but doesn't clarify behavior when preview is true. Completeness is adequate but has 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%, so all parameters have descriptions in the schema. The description does not add additional meaning beyond what the schema already provides. It mentions 'top-level declarations' but does not clarify the selection range parameters further.

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 moves top-level declarations (functions, classes, types, constants) to another file, which is a specific verb and resource. It distinguishes from siblings like extractFunction and getMoveToRefactoringFileSuggestions by specifying the scope (top-level) and automatic import rewiring.

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 explains what the tool does but does not explicitly state when to use it versus alternatives like extractFunction or rename. No guidance on when not to use it or prerequisites (e.g., using getMoveToRefactoringFileSuggestions first).

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 indicate readOnlyHint=true, and the description adds that the search is workspace-wide and returns locations and kinds. However, it does not disclose performance characteristics, case sensitivity, or behavior with partial matches. The description adds some 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?

Two sentences, no wasted words. Front-loaded with the key action and scope. Every word 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?

The description explains the return value (symbols, locations, kinds) without an output schema. For a read-only search tool with 4 parameters, this is adequate and 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%, with each parameter described. The description does not add significant new meaning beyond the schema; it merely echoes 'search string' and 'project files'. Baseline score of 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 it performs a workspace-wide symbol search by name, returning matching symbols with locations and kinds. This distinguishes it from sibling tools like definition, references, and quickinfo which serve different purposes.

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 implies usage for finding symbols across the workspace but does not provide explicit guidance on when to use this tool versus alternatives like definition or quickinfo. No 'when to use' or 'when not to use' is stated.

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, indicating safe read operation. The description adds that it returns kind, name, spans, and child items, providing some behavioral context beyond safety. No mention of auth needs or rate limits, but the tool is simple.

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 a single sentence that is concise and front-loaded with the core action. Every word adds value with no 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 has one parameter, no output schema, and readOnlyHint annotation, the description is fairly complete. It covers what it retrieves and the type of output. Minor gap: no explicit mention of nesting hierarchy shape.

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 one parameter fully described. The description reiterates 'File path' but adds no additional meaning beyond the schema. Baseline score of 3 is appropriate as schema already carries the burden.

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 retrieves the complete hierarchical structure of a file, listing specific elements like classes, functions, variables, etc. It distinguishes itself from sibling tools which are mostly about completions, diagnostics, and refactoring, not file structure.

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 does not provide explicit guidance on when to use this tool versus alternatives. While it is clear that this tool is for structural navigation, it lacks statements about contexts where other tools would be more appropriate.

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?

The description adds detail beyond annotations by specifying that it uses TypeScript's native organizeImports with mode 'All', explaining the exact behavior (sorts, coalesces, removes unused). This aligns with the idempotentHint and destructiveHint 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 concise with two well-structured sentences, front-loading the main action and following with important context. No unnecessary words.

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 simple tool with two parameters and no output schema, the description provides sufficient information: what the tool does, how it works, and a critical prerequisite. The behavioral details (sorts, coalesces, removes unused) cover the main outcomes.

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 parameter descriptions are clear. The description adds context that the file must be part of a tsconfig.json project, which is useful but not a significant addition 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 the tool sorts, coalesces, and removes unused imports in TypeScript/JavaScript files, specifying the verb and resource. It distinguishes from sibling tools like format or getCodeFixes by focusing specifically on import organization.

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 a prerequisite ('Requires the file to be part of a tsconfig.json project'), which helps the user know when the tool is applicable. However, it does not explicitly mention when to use this tool versus alternatives like format, though the context implies it.

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?

The description aligns with the readOnlyHint annotation by not implying any side effects. It adds value by detailing the return fields (name, kind, file location, spans), which goes beyond the structured 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 concise, consisting of two sentences that front-load the primary purpose and then list the return information. No extraneous text.

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 simplicity, read-only nature, full schema coverage, and lack of output schema, the description adequately covers behavior and return information. It is complete enough for an agent to understand usage.

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 covers all three parameters with descriptions (file path, line, offset). The tool description does not add additional semantics beyond what the schema provides, so the baseline score of 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 verb ('Returns') and resource ('call hierarchy item(s) at a position'), and it distinguishes itself from sibling tools by calling itself 'the entry point for call hierarchy queries', which implies a specific role in the workflow.

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 indicates it is the entry point for call hierarchy queries, providing context for when to use this tool before other call hierarchy commands. However, it does not explicitly state when not to use it or offer 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, so the description correctly implies no side effects. It adds that it returns three specific pieces of info but does not disclose potential behavior like file existence checks or project loading delays. The description is consistent with annotations and provides minimal extra transparency.

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 a single, focused sentence that directly states the return values. No extra words, front-loaded with the key output. Appropriate length for the tool's simplicity.

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?

While the description lists what is returned, it lacks context about how the 'file' parameter is used (e.g., to identify the project) or the typical usage pattern. Given no output schema, a bit more detail on the return format would help. However, for a simple read tool with good annotations and schema, it is adequate but not fully 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?

Input schema has 100% coverage with descriptions for both parameters. The description does not add any information about how parameters affect the result beyond what the schema provides (e.g., it doesn't explain that 'file' determines which project to query or that needFileNameList controls the file list). 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 what the tool returns: tsconfig.json path, full file list, and language service activity. It uses specific verbs and resources, and the returned data distinguishes it from sibling tools that focus on completions, definitions, etc.

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 no guidance on when to use this tool versus alternatives. With 35+ sibling tools, the agent needs explicit context on when projectInfo is appropriate (e.g., 'Use this to get project metadata before performing other operations'). No when/when-not information is given.

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 the description does not contradict this. However, it adds no further behavioral context (e.g., whether results are exhaustive, include cross-file calls, or depth). With annotations covering the safety profile, the minimal added context is adequate.

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 a single, front-loaded sentence that immediately conveys the purpose. Every word earns its place; no wasted content.

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 low complexity, no output schema, and read-only annotation, the description sufficiently explains what is returned (functions/methods that call the given function). It could benefit from mentioning the result format (e.g., file, line), but is generally complete enough for an agent to understand and invoke the tool.

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 for all three parameters (file, line, offset). The description does not add any extra meaning beyond the schema, 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 states the tool returns all functions/methods that call the function at a given position, answering 'who calls this?'. It uses specific verb 'returns' and resource, effectively distinguishing from the sibling 'provideCallHierarchyOutgoingCalls'.

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 implies when to use the tool ('who calls this?') but does not explicitly exclude alternative tools like 'references' or 'definition'. The context is clear for typical usage, but lacks explicit when-not-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?

The description adds behavioral context beyond the readOnlyHint annotation by specifying that it returns called functions/methods from a given position. It does not contradict annotations and provides useful operational detail.

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 concise sentences with no wasted words. The first sentence states the action and resource, the second clarifies the question it answers. Efficiently front-loaded.

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 no output schema, the description hints at the return type ('returns all functions/methods') which is helpful, though a brief note on return structure would improve completeness. Overall adequate for its complexity.

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 documents all three parameters with clear descriptions (100% coverage). The description does not add new semantic meaning beyond what the schema provides, hence baseline score 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?

The description uses a specific verb 'returns' and resource 'functions/methods' and clarifies the scope by answering 'what does this call?'. It clearly distinguishes the tool from incoming calls sibling.

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 implies when to use (to get outgoing calls from a position) but provides no explicit guidance on when not to use it, nor lists alternatives like 'provideCallHierarchyIncomingCalls' or prerequisites like needing a valid call site.

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, so the description does not need to reiterate safety. It adds value by specifying the types of hints returned (inferred types, parameter names, return types), enriching behavioral understanding beyond the annotation.

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 extremely concise with three short sentences, each serving a clear purpose: what it does, what it shows, and when to use it. No unnecessary words.

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 no output schema, the description adequately conveys what the tool returns (types, parameter names, return types). However, it could be more precise about the response structure (e.g., array of hints with positions). Still, it is fairly complete for a simple read-only tool.

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?

All three parameters are fully described in the input schema (100% coverage). The description adds no additional meaning, examples, or constraints beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.