rename_symbol

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

With no annotations, the description carries the burden of disclosing behavior. It does disclose that renaming is AST-level, syntactically safe, cross-consumer, and that unified diffs are returned. However, it does not explicitly state that files are modified on disk by default, whether changes are reversible, or what the concrete diff output looks like.

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?

A single, front-loaded sentence with no filler. Every qualifier contributes meaning: syntactically safe, AST-level, across all consumers, and unified diffs. It is compact without sacrificing the most important semantic 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 is adequate given the complete parameter schema: an agent can identify the required inputs and the basic behavior. However, it lacks explicit usage guidance, a clear side-effect statement, and detail on the unified diff return format, so some context must still be inferred.

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 baseline is 3. The description adds meaning beyond the schema: 'across all consumers' clarifies that targetFile is an entry point rather than the only file affected, and 'AST-level' informs how oldName and newName will be matched. Optional parameters like line, dryRun, and workspaceRoot are already well described 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?

The description states a specific operation ('Applies ... renames'), a concrete resource ('symbol'), a scope ('across all consumers'), and an output ('unified diffs'). It also adds meaningful qualifiers ('syntactically safe, AST-level') that distinguish this from a naive find-and-replace tool and from sibling tools like find_all_usages.

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: this is the tool to use when a symbol should be renamed across all its consumers. However, it does not explicitly say when to prefer find_all_usages, get_file_outline, or set_workspace_root, nor does it give when-not-to-use guidance or enumerate alternatives.

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