introduce_parameter

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

With no annotations, the description properly discloses the key behavioral traits: it defaults to a Dry Run preview, requires apply=true to write changes, and states 'this tool only changes code' after reading with LSP. This is valuable side-effect and prerequisite information that goes well 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 four sentences but every sentence adds essential value: the transformation, the selection syntax, the dry-run/apply behavior, and the LSP prerequisite. It is dense with no filler and front-loads the 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?

For a complex 8-parameter refactoring tool with no annotations and no schema descriptions, this description is unusually complete. It covers purpose, selection criteria, range semantics, apply behavior, and the important prerequisite to read code with LSP. The presence of an output schema means return values need not be described, and the only minor omission (root) is optional and likely inferable.

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 has 0% description coverage, so the description must compensate. It explains the Range parameters in detail (0-based, UTF-16 units), the parameter_name, and the apply flag. It does not mention the optional root parameter at all, but the core parameters are well covered and the file is implied via the LSP instruction.

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 core transformation: turning a value inside a function into a new parameter, with the original expression becoming the default. It specifies the verb ('Turn'), the resource (a value inside a function), and the result (new parameter), which distinguishes it from sibling refactorings like extract_variable or change_signature by its mechanism and outcome.

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 concrete when/how: select an expression inside the function body, provide a parameter name, and use LSP first. It also explains the dry-run vs apply workflow. However, it does not explicitly mention when not to use this tool or compare it to alternatives such as change_signature, so the guidance is clear but not exhaustive.

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