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

The description discloses the recursive traversal behavior and the depth parameter, which is useful. However, with no annotations provided, the description carries the full burden of behavioral disclosure. It doesn't mention whether this is a read-only operation, whether it executes code, or what the output format looks like. The 'max_queries' parameter hints at a query budget but the description doesn't explain what happens when the budget is exhausted.

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 zero waste. The core behavior is front-loaded ('What breaks if this symbol changes'), and the usage guidance is a natural second sentence. 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 read-only analysis tool with 100% schema coverage, the description is nearly complete. It explains the transitive behavior, the depth parameter, and when to use it. The only gap is the lack of detail about the output format and what happens when max_queries is hit, but these are minor given the schema covers the 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 the schema already documents all three parameters. The description adds context for 'depth' by explaining the transitive hops behavior, but doesn't add meaning beyond the schema for 'name' or 'max_queries'. Baseline 3 is appropriate since 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 uses a specific verb ('breaks') and resource ('symbol'), and clearly states the transitive behavior ('everything that references it, then everything that references those, to the given depth'). It distinguishes itself from siblings like find_references by emphasizing the recursive blast-radius analysis rather than just direct references.

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 states when to use this tool: 'Run before changing a signature or deleting anything.' This provides clear context and implies it is a pre-refactoring safety check, distinguishing it from alternatives like find_references or rename_symbol.

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 behavioral disclosure burden. It adds meaningful context beyond the schema: the tool depends on an already-running language server, is non-build invariant, and returns diagnostics in milliseconds. This implies a read-only, non-destructive operation, which is sufficient for this tool type.

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 zero filler. The first sentence front-loads the purpose and key differentiators (fast, no build, language server), and the second adds a concrete usage trigger. 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 simple diagnostics tool with no output schema and no annotations, the description covers what it returns (errors/warnings), when to use it (after editing), and its precondition (already-running language server). The only minor omission is explicit behavior if the server is not running, but that is not critical for invoking it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning for file, limit, or severity beyond what the schema already documents; it does not compensate for any gaps because there are none.

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 names a specific verb and resource ('compiler diagnostics for one file') and distinguishes the tool from the symbol-focused sibling tools (find_symbol, find_references, etc.). The phrase 'errors and warnings in milliseconds, without a build' precisely scopes what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit workflow guidance: 'Run this after editing to confirm the change compiles.' It does not name alternatives or exclusions, but the sibling set is all symbol-navigation tools, so there is no realistic alternative to confuse it with. The 'without a build' and 'already-running language server' context clarifies when it is 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?

No annotations are provided, so the description carries the burden. It accurately describes the operation as outlining symbols and notes it does not read the file body, which is a useful behavioral detail. However, it does not explicitly state that the operation is non-destructive or mention any side effects, though for a read-only tool this is minor.

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, zero filler. The core action ('outline one file') is front-loaded, and the clarifying phrase about the API surface is concise and valuable.

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 one-parameter tool with no output schema, the description is largely complete: it specifies what is returned (symbols with line numbers) and what is not done (reading the body). Minor gaps like handling of large files or edge cases are not critical for basic 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% for the single 'file' parameter, which is already documented as 'Path relative to the repo root'. The description adds no additional parameter-specific guidance, so the baseline 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?

The description states a specific verb ('outline') and resource ('one file'), and clearly enumerates the output ('every type, method, and field it declares, with line numbers'). It differentiates from siblings by specifying the scope is the entire file's API surface, not a single symbol or body.

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 you want a file's API surface without reading its body) but does not explicitly mention when not to use it or name alternatives like find_symbol or get_symbol_body. The context is clear but exclusions are left to inference.

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 explicitly lists the output components (resolved type, signature, documentation, declaration line) and implies a read-only, non-mutating lookup by saying 'without opening the file.' It does not mention prerequisites like project indexing or error behavior, but for a simple explanation tool, the core behavior is transparent.

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 concise sentences with no filler. The first sentence front-loads the output contents, and the second gives the practical use case. Both sentences earn their 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 single-parameter, read-only tool with no output schema, the description covers what the tool returns, why an agent would use it, and the expected input via schema. It could further specify naming conventions or failure behavior, but the information provided is sufficient for correct selection and invocation in most cases.

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 for the single parameter is 100%, with the schema describing 'name' as 'Symbol name'. The description adds overall context about what the tool does with the symbol but does not provide additional detail about name format, qualification, or matching rules. Baseline 3 applies since the schema already documents the parameter sufficiently.

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: it explains what a symbol is by returning resolved type, signature, documentation, and declaration line. It also frames the specific use case ('what does this call do') and differentiates itself from siblings like find_symbol and get_symbol_body by emphasizing semantic explanation over locating or retrieving source code.

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 clear guidance on when to use the tool: when you need to understand what a call or symbol does without opening the file. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of full exclusion-based guidance.

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

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

With no annotations, the description carries the full burden. It discloses that resolution is handled by the language server and implies a read-only navigation action, but it does not mention failure cases, response shape, or any side effects. This is adequate for a simple lookup but leaves some behavioral ambiguity.

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 communicates the action, target, and resolution mechanism without any filler. Every word contributes 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 one-parameter read-only tool, the description covers the core behavior. However, there is no output schema and no explanation of what 'jump' returns (e.g., location, range), nor any guidance on prerequisites like an active language server. This leaves some gaps for an agent deciding how to handle the response.

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 covers the single parameter 'name' with 'Symbol name to look up' at 100% coverage. The description's phrase 'where a symbol is defined' adds minimal semantic context beyond the schema, so a 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 states a specific action ('Jump to where a symbol is defined') and a clear resource (the symbol's definition). The word 'definition' inherently distinguishes this from siblings like find_references and find_implementations, and 'resolved by the language server' adds technical precision.

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, no exclusions, and no mention of prerequisites. It simply states what the tool does without situational cues.

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 present, so the description carries the disclosure burden. It clarifies that results are runtime implementations rather than mere reference locations, but it does not explicitly state read-only behavior, scope limits, or behavior when no implementations exist. 'Find' implies a safe read operation, but that is left implicit.

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 filler. The core action and resource are front-loaded, and the second sentence earns its place by distinguishing the tool from reference-based siblings.

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 two-parameter read-only tool with no output schema, the description provides enough context about what the results represent and when to use it. The exact return shape is implied rather than stated, but the tool name and description make it reasonably predictable.

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 documents both name and limit. The description adds real meaning to `name` by specifying that it can be an interface, abstract member, or virtual member, and by explaining the nature of the result. It appropriately avoids repeating the limit 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 names a specific verb and resource: finding concrete implementations or overrides. It also differentiates from siblings like find_references with the phrase 'what actually runs when this is called', giving the tool a precise semantic identity.

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 embeds a clear usage trigger: when references alone cannot tell you what actually runs, use this tool. It does not explicitly list exclusions or compare against find_definition, but it provides enough directional guidance to select among the 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool performs compiler-level static analysis (not just text matching) and that it includes DI registrations and interface implementations. It does not mention side effects or permissions, but as a find operation it is implicitly read-only. The description adds useful behavioral context beyond the 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 two sentences with no filler. The first sentence establishes the core functionality, and the second gives actionable usage guidance. It is front-loaded with the primary purpose and 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 tool has five parameters, no output schema, and no annotations. The description covers the purpose and usage guidance but does not describe the return structure beyond the hint in the include_code parameter. Given the simplicity of the tool and the schema's parameter details, the description is largely complete, though a brief mention of the returned data (e.g., list of file/line/code) would improve it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already fully documents all five parameters. The description adds no additional parameter-specific information beyond what the schema provides, so it meets the baseline without extra value.

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 states a specific verb and resource ('Find everything that references a symbol') and clarifies that it includes compiler-visible sites like dependency-injection registrations and interface implementations, which differentiates it from text search and sibling tools like find_implementations. The purpose is unambiguous and the resource is well-defined.

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 states when to use it: 'Run this before renaming, changing a signature, or deleting.' It also implies a contrast with text search by saying it finds what a text search misses. However, it does not explicitly name alternatives or when not to use it, but the directive is clear enough for an agent to decide.

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 does mention that resolution is via the language server rather than text search, and that results include file and line. It does not explicitly state that the operation is read-only, but that is strongly implied by 'find'. It also omits any potential caveats such as index availability or performance trade-offs, which would be useful for a tool with no annotation safety profile.

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 exactly two sentences, front-loaded with the primary action and scope. Every word contributes value, and there is no redundant information. It is a model of concise, efficient writing.

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 context to call it correctly: it tells you what input is expected, what it does, and what the output contains (file and line). It could mention the project-wide scope explicitly, but that is already in the first sentence. The only missing piece is explicit routing to sibling tools, but that falls under usage guidelines rather than 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 description coverage is 100%, with both 'name' and 'limit' clearly described in the schema. The description adds no additional meaning beyond what the schema already provides, such as matching semantics or the meaning of the limit. This meets the baseline but does not exceed 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 finds a symbol by name anywhere in the project, distinguishes itself from text search by noting it's language-server resolved, and implies a different purpose from sibling tools like find_definition or find_references. The verb-resource pairing is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: you use this when you have a symbol name and want to locate it. However, it does not explicitly state when not to use it or mention any of the sibling tools as alternatives, leaving the agent to infer the distinction from the tool names and description.

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

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

With no annotations, the description carries the full burden. It usefully discloses that the tool returns the full source of one declaration and does not require opening the containing file. It does not explain error behavior or edge cases, but for a simple read-oriented tool it gives meaningful behavioral insight.

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 compact sentences, front-loaded with the core purpose, with no filler. Every word adds information, and the usage guidance is succinctly appended.

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 (one required parameter) and no output schema, the description conveys the return value ('full source') and the input semantics sufficiently. It omits error conditions and resolution scope, but for this straightforward getter, the description is largely 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 already describes the 'name' parameter as 'Symbol name' with 100% coverage, so the baseline is 3. The description adds value by specifying that the name must be a method, class, or function declaration, clarifying the accepted symbol kinds and the intent that it is a declaration name, not a file path.

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 the full source of one declaration (method, class, or function) identified by name, which is a specific verb+resource. It distinguishes the tool from simply reading a file, though it does not explicitly differentiate from sibling tools like find_symbol or find_definition.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance: 'Use this instead of opening a file to look at a single member.' This gives a clear invocaton context and identifies an alternative to avoid. However, it does not address sibling tools or edge cases like when the symbol is not found.

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 behavioral disclosure burden. It discloses that the tool 'answers cheaply without starting the language server,' which is a meaningful behavioral trait. It does not fully describe the return shape or error modes, but for a zero-parameter informational query this is reasonably 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, well-structured sentence that front-loads the core purpose and then adds the cheapness and usage guidance. Every clause earns its place with no redundant information.

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

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

For a zero-parameter, no-output-schema tool, this description is complete: it explains what the tool reports, how to use it first, and why it is useful. The agent has everything needed to decide when and why to call it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has exactly zero parameters, and the schema coverage is trivially 100%. The baseline for zero-parameter tools is 4, and the description has no need to explain parameter behavior.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool's resource ('which repository this server bound to') and its informational purpose, including 'how' the binding is established. It also distinguishes this tool from the symbol-oriented siblings by focusing on server configuration state rather than code navigation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit usage guidance: 'use it first to confirm the server is pointed at the project you think it is.' It clearly explains when to invoke it, though it does not explicitly state when not to use it, but no obvious alternative among the sibling tools directly competes.

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 must disclose behavioral traits, and it does disclose the most critical one: 'Defaults to a dry run showing what would change.' This tells the agent that by default no mutation occurs and that apply=true is required to write changes. It also explains the semantic behavior (renames only the right symbols). However, it does not disclose potential side effects of applying (e.g., whether changes are reversible, file scope, or confirmation requirements), which would be expected for a mutation tool with zero annotation coverage.

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 zero fluff. The core purpose is front-loaded in the first sentence, and the critical dry-run default is stated immediately after. Every clause earns its place; there is no redundant information. The structure leads with what the tool does, then clarifies its safety 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 tool of this complexity, the description covers the essential context: purpose, semantic accuracy, and default preview behavior. It does not explain what happens when apply is true (beyond the schema's 'Write the changes') or any prerequisites or consequences, but the dry-run default mitigates risk. Given no annotations and no output schema, the description is reasonably complete but could explicitly mention that applying is a permanent mutation.

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 all three parameters (name, new_name, apply) are already documented in the schema. The description's mention of 'dry run' is consistent with the apply parameter's schema text, but it adds no new semantic information beyond what the schema already provides. The description does not clarify parameter formats, constraints, or relationships, so it stays at the baseline for full coverage.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool renames a symbol everywhere using compiler semantics rather than text replacement, explicitly distinguishing it from a naive search-and-replace. The verb 'rename' and resource 'symbol' are specific, and the contrast with text replacement sets it apart from any generic editing tool. Sibling tools like find_symbol and find_references are for lookup, so this tool's unique purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool (when a semantic rename is needed) but does not explicitly state when not to use it or mention any sibling alternatives. The phrase 'rather than text replacement' gives a comparative guideline, but it does not address how this tool relates to find_references or other siblings, leaving the agent to infer that rename is the right choice. This is acceptable but not fully explicit.

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