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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool deletes symbols and references, implying a destructive mutation, but fails to mention critical behaviors like whether deletions are permanent, require specific permissions, have side effects on code structure, or provide confirmation. For a destructive tool with zero annotation coverage, this is a significant gap.

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, efficient sentence that front-loads the core action and scope. It avoids redundancy and wastes no words, though it could be slightly more structured by explicitly separating purpose from behavior.

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 destructive mutation tool with 5 parameters, no annotations, and no output schema, the description is incomplete. It lacks information on error handling, return values, safety warnings, or dependencies, leaving critical gaps for an agent to use this tool effectively in a codebase context.

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 5 parameters thoroughly. The description adds no additional semantic context about parameters beyond implying 'symbol' includes variables, functions, classes, etc., which is minimal value. Baseline 3 is appropriate when the 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 the specific action ('Delete') and target resource ('TypeScript/JavaScript symbol'), distinguishing it from sibling tools like 'rename_symbol' or 'find_references'. It specifies the scope includes 'all its references', making the purpose unambiguous and distinct from alternatives.

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 like 'rename_symbol' or 'find_references', nor does it mention prerequisites or exclusions. It lacks context about appropriate scenarios, leaving the agent to infer usage from the tool name 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states what the tool does but doesn't describe how it behaves: no information on performance (e.g., speed, scalability), error handling (e.g., invalid paths), output format (e.g., list of locations), or limitations (e.g., symbol resolution accuracy). For a tool with 4 required parameters and no annotation coverage, this leaves significant gaps in understanding its operational characteristics.

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, efficient sentence that front-loads the core purpose without unnecessary words. Every part earns its place: 'Find all references' specifies the action, 'to a TypeScript/JavaScript symbol' defines the target, and 'across the codebase' sets the scope. There's zero waste or 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 complexity (4 required parameters, no annotations, no output schema), the description is incomplete. It doesn't explain what the tool returns (e.g., a list of reference locations), how results are structured, or any behavioral nuances like handling ambiguous symbols. For a code analysis tool with multiple inputs, more context is needed to guide effective use.

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 thoroughly. The description adds no additional meaning beyond implying that parameters relate to symbol location (filePath, line, symbolName) and codebase context (root). Since the schema does the heavy lifting, the baseline score of 3 is appropriate—the description doesn't compensate but doesn't need to given the high 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 action ('Find all references') and target ('TypeScript/JavaScript symbol across the codebase'), making the purpose immediately understandable. It distinguishes from siblings like 'get_definitions' or 'get_symbols_in_scope' by focusing specifically on reference finding rather than definitions or scope analysis. However, it doesn't explicitly contrast with 'get_type_at_symbol' or 'rename_symbol', which might also involve symbol operations.

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 like 'get_definitions' or 'get_symbols_in_scope'. It doesn't mention prerequisites (e.g., needing a codebase root) or exclusions (e.g., not for non-symbol references). Without such context, an agent might struggle to choose between this and sibling tools for related tasks.

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 provided, the description carries the full burden of behavioral disclosure but offers minimal information. It doesn't mention whether this is a read-only operation, what the output format looks like (e.g., structured data vs. plain text), error conditions, or performance implications. The description is too vague to guide the agent effectively beyond the basic action.

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, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action and resource, making it easy to parse quickly. There's no wasted space or redundant phrasing.

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 a TypeScript symbol definition tool with 6 parameters and no output schema, the description is insufficient. It doesn't explain what constitutes a 'definition' (e.g., source code location, type details), how results are returned, or error handling. Without annotations or output schema, the agent lacks critical context for effective use.

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 description adds no parameter-specific information beyond what's already in the schema, which has 100% coverage with detailed descriptions for all 6 parameters. This meets the baseline score of 3, as the schema adequately documents parameters like 'root', 'filePath', and 'symbolName' without needing duplication in the description.

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 ('Get') and resource ('definition(s) of a TypeScript symbol'), making the purpose immediately understandable. It doesn't explicitly differentiate from siblings like 'get_symbols_in_scope' or 'get_type_at_symbol', which would require more specificity about what distinguishes 'definitions' from other symbol-related queries.

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 like 'find_references' or 'get_type_at_symbol'. It lacks context about prerequisites (e.g., needing a TypeScript project setup) or typical use cases (e.g., debugging vs. documentation), leaving the agent to infer usage from the tool name 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?

With no annotations provided, the description carries full burden but only states what the tool does, not how it behaves. It lacks details on error handling, performance characteristics, whether it reads from disk or memory, or what the output format looks like (diagnostics 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?

The description is a single, efficient sentence that front-loads the core purpose without unnecessary words. Every element ('Get TypeScript diagnostics', 'errors, warnings', 'for a single file') contributes directly to understanding the tool's function.

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 diagnostic tool with 3 parameters and no output schema, the description is minimally adequate but lacks completeness. It doesn't explain what diagnostics include (e.g., line numbers, severity levels) or how virtualContent overrides file reading, leaving gaps for effective agent 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?

Schema description coverage is 100%, so parameters are fully documented in the schema. The description doesn't add any parameter-specific context beyond what's in the schema (e.g., explaining interactions between filePath and virtualContent). Baseline 3 is appropriate when 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 the specific action ('Get TypeScript diagnostics') and resource ('for a single file'), with precise scope covering errors and warnings. It effectively distinguishes from siblings like get_definitions or get_type_at_symbol by focusing on diagnostic analysis rather than type or definition lookup.

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 TypeScript file diagnostics but doesn't explicitly state when to use this tool versus alternatives like get_type_at_symbol for type queries or find_references for symbol tracking. No guidance on prerequisites, file formats, or exclusion cases is provided.

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 provided, the description carries full burden but lacks behavioral details. It doesn't disclose whether this is a read-only operation, potential performance implications, error conditions, or output format. 'Get' suggests a query, but no safety or side-effect information is given for a tool analyzing code modules.

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 that efficiently conveys the core purpose with zero wasted words. Front-loaded with the main action and resource, making it immediately understandable while appropriately sized for its informational 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?

For a tool with 3 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain what 'exported symbols' includes (functions, variables, types?), the return format, or how it handles different module systems. The lack of behavioral context and output information leaves significant gaps for 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 description coverage is 100%, so parameters are fully documented in the schema. The description adds no additional parameter semantics beyond the schema's details for 'root', 'moduleName', and 'filePath'. Baseline 3 is appropriate when the schema handles parameter documentation.

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 resource ('exported symbols from a TypeScript/JavaScript module'), specifying the scope ('without detailed signatures'). It distinguishes from siblings like 'get_symbols_in_scope' by focusing on module exports rather than local scope, but doesn't explicitly contrast with 'get_type_at_symbol' or 'get_type_in_module'.

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 like 'get_symbols_in_scope' or 'get_type_in_module'. The description implies usage for module analysis but provides no explicit context, prerequisites, or exclusions for choosing among similar symbol-related 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?

With no annotations provided, the description carries full burden but only states what the tool does, not how it behaves. It doesn't disclose whether this is a read-only operation, potential performance impacts, error conditions, or output format. For a tool with 4 parameters and no annotations, this is a significant gap in behavioral disclosure.

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 efficiently conveys the core purpose with zero waste. Front-loaded with the main action and resource, followed by scope qualification. 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 tool with 4 parameters, no annotations, and no output schema, the description is minimally adequate. It explains what the tool does but lacks behavioral context, output expectations, and usage guidance. The 100% schema coverage helps, but the description should do more given the 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?

Schema description coverage is 100%, so the schema fully documents all parameters. The description adds no parameter-specific information beyond what's in the schema. Baseline 3 is appropriate when schema does all the parameter documentation work.

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 'all symbols (variables, types, functions, etc.)' with specific scope 'visible at a specific location in a TypeScript/JavaScript file'. It distinguishes from siblings like 'get_module_symbols' (module-level) and 'get_type_at_symbol' (type-specific) by emphasizing location-based visibility.

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 context (TypeScript/JavaScript file analysis) but doesn't explicitly state when to use this vs. alternatives like 'get_module_symbols' for module-level symbols or 'find_references' for symbol usage tracking. No exclusions or prerequisites are 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?

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions what the tool does but doesn't describe how it behaves: no information about error conditions, performance characteristics, authentication needs, rate limits, or what the return format looks like. This is inadequate for a tool with 5 parameters and no output schema.

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, efficient sentence that communicates the core purpose without any wasted words. It's appropriately sized and front-loaded with the 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 tool with 5 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what type information is returned, how errors are handled, or the tool's limitations. Given the complexity and lack of structured metadata, the description should provide more behavioral context to be 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?

The schema description coverage is 100%, so all parameters are documented in the schema. The description adds no additional parameter semantics beyond what's already in the schema descriptions. The baseline score of 3 reflects adequate but minimal value added by the description regarding parameters.

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 type information') and resource ('TypeScript/JavaScript symbol at a specific location'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from siblings like 'get_type_in_module' or 'get_definitions', which could provide similar type-related functionality.

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 like 'get_type_in_module' or 'get_definitions'. It doesn't mention prerequisites, limitations, or scenarios where this tool is preferred over siblings, leaving the agent to infer 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'detailed signature information' but doesn't specify what that includes (e.g., parameters, return types, modifiers), whether it handles nested types, error conditions, or performance characteristics. For a tool with 4 parameters and no output schema, this leaves significant gaps in understanding how the tool behaves.

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, efficient sentence that front-loads the core purpose without unnecessary words. It could be slightly more structured by explicitly listing the tool's scope, but it avoids redundancy and stays focused, earning a high score for 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 4 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain what 'detailed signature information' entails, how errors are handled, or the format of results. For a tool that likely returns complex type data, this lack of output clarification and behavioral context makes it inadequate for reliable agent use.

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 thoroughly. The description adds no additional meaning beyond implying that 'type' includes various constructs like functions or classes, which is somewhat redundant with the schema's 'typeName' description. Baseline 3 is appropriate as the schema does the heavy lifting, but the description doesn't enhance parameter 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 action ('Get detailed signature information') and target ('for a specific type from a module'), specifying the types of objects it works with (function, class, interface, type alias, etc.). It distinguishes from siblings like 'get_module_symbols' (lists symbols) or 'get_type_at_symbol' (type at location) by focusing on detailed analysis of a named type within a module. However, it doesn't explicitly contrast with all siblings, keeping it at 4 rather than 5.

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. It doesn't mention when to choose it over siblings like 'get_definitions' or 'get_symbols_in_scope', nor does it specify prerequisites or exclusions. The agent must infer usage from the purpose alone, which is insufficient for optimal tool selection.

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 provided, the description carries the full burden of behavioral disclosure. It describes the core functionality but lacks details about response format, pagination, rate limits, authentication requirements, or error conditions. The description is accurate but minimal in behavioral context.

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, efficient sentence that communicates the essential purpose without unnecessary words. It's appropriately sized for a simple listing tool and front-loads the core functionality immediately.

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 read-only tool with one well-documented parameter and no output schema, the description is minimally adequate. However, without annotations or output schema, it could benefit from more detail about the response structure or behavioral characteristics to be truly 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 description coverage is 100%, with the single parameter 'category' fully documented in the schema. The description doesn't add any parameter semantics beyond what the schema already provides, maintaining the baseline score appropriate when schema documentation is complete.

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 ('List') and resource ('all available MCP tools'), specifying what information is included ('with descriptions and categories'). It distinguishes itself from siblings like 'get_symbols_in_scope' or 'get_definitions' by focusing on tool metadata rather than code analysis.

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 discovering available tools, but provides no explicit guidance on when to use it versus alternatives. There's no mention of prerequisites, timing considerations, or comparison to other tools in the context of tool discovery workflows.

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 provided, the description carries the full burden. It discloses the key behavioral trait of updating TypeScript imports/references, which is valuable beyond basic move operations. However, it doesn't mention potential side effects like error handling, permission requirements, or whether the operation is atomic/reversible.

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, efficient sentence that front-loads the core action and key benefit. Every word earns its place with no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no annotations and no output schema, the description is moderately complete—it covers the primary purpose and a key behavioral trait. However, it lacks details on error conditions, return values, or advanced usage scenarios that would be helpful given the tool's 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?

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds no additional parameter semantics beyond what the schema provides (e.g., it doesn't clarify path formats or the scope of 'overwrite'). Baseline 3 is appropriate when 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 the specific action ('move a directory') and the key behavioral outcome ('updating all TypeScript imports and references automatically'), which distinguishes it from sibling tools like 'move_file' (which presumably moves individual files) and 'rename_symbol' (which renames symbols rather than directories).

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 moving directories in TypeScript projects where import/ref updates are needed, but doesn't explicitly state when to use this vs. alternatives like 'move_file' or when not to use it (e.g., for non-TypeScript projects). No prerequisites or exclusions are 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?

No annotations are provided, so the description carries full burden. It mentions updating import statements, which is valuable behavioral context beyond basic file movement. However, it doesn't disclose important traits like whether this requires write permissions, what happens to broken imports, if there are rate limits, or how conflicts are handled with the 'overwrite' parameter.

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, efficient sentence that communicates the core functionality without unnecessary words. It's front-loaded with the main action and includes the important secondary effect of updating import statements. 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 mutation tool with no annotations and no output schema, the description is adequate but has clear gaps. It explains what the tool does but doesn't cover behavioral aspects like error conditions, permission requirements, or what the return value contains. The import statement update is helpful context, but more completeness would be expected for a file system operation 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%, providing complete parameter documentation. The description adds no additional parameter semantics beyond what's in the schema. The baseline score of 3 is appropriate since the schema does the heavy lifting, though the description could have explained parameter interactions or edge cases.

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 ('move'), the resource ('TypeScript/JavaScript file'), and the additional effect ('update all import statements'). It distinguishes from sibling tools like 'move_directory' by specifying file-level operations and from 'rename_symbol' by focusing on physical file movement with import updates.

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 like 'move_directory' or 'rename_symbol'. It doesn't mention prerequisites, constraints, or typical scenarios for file movement versus other operations. Usage context is implied but not explicitly 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?

With no annotations provided, the description carries full burden but only states the basic action. It doesn't disclose that this is a destructive mutation (renames symbols globally), potential side effects (e.g., breaking references), error conditions, or output format. This is inadequate for a complex refactoring tool with significant behavioral implications.

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, efficient sentence with zero wasted words. It front-loads the core action and scope, making it immediately understandable without unnecessary elaboration.

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 complex, destructive refactoring tool with 5 parameters and no annotations or output schema, the description is insufficient. It lacks critical context about mutation behavior, error handling, and what happens after renaming (e.g., success confirmation or diff output), leaving significant gaps for 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 description coverage is 100%, so the schema fully documents all 5 parameters. The description adds no parameter-specific information beyond implying that 'oldName' and 'newName' refer to TypeScript symbols. This meets the baseline for 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 action ('Rename'), the target ('TypeScript symbol'), and scope ('across the codebase'), with specific examples of symbol types (variable, function, class, etc.). It distinguishes from siblings like delete_symbol (destructive removal) and find_references (read-only search).

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 like delete_symbol or find_references. It doesn't mention prerequisites (e.g., needing a TypeScript project) or exclusions (e.g., not for non-TypeScript files), leaving the agent to infer usage context.

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