renamePreview

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds meaningful context beyond annotations: the preview is the only place showing how far the rename goes, and it warns that the rename touches objects the agent did not open. This is a valuable behavioral caveat that goes beyond the structured metadata.

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 core function and followed by a one-sentence caveat about usage. No redundancy; every clause 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 preview tool with no output schema, the description tells the agent what it does (shows affected objects/lines), what input to provide (the evaluation result), and when to use it (before agreeing to execute). It leaves the optional transport parameter underspecified but that is a minor gap; the core invocation information is present.

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 meaning by clarifying that the required renameRefactoring parameter is the evaluation passed back in from a prior step, rather than just a generic proposal. The optional transport parameter is not further explained, but it is optional and its schema description is present.

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 function: it is the second step of a rename and shows every object and line the rename would touch, based on the evaluation passed back in. This clearly identifies the tool as a preview/read operation and distinguishes it from renameEvaluate and renameExecute without needing to compare schemas.

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 explicitly says to read this before agreeing and explains why: a rename reaches objects you did not open, and the preview is the only place that shows the full scope. This is clear when-to-use guidance (after evaluation, before execution), though it does not name sibling tools or state explicit alternatives.

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