Prepare an exact function-body replacement

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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description aligns: the dry_run parameter clarifies 'Direct application is disabled; this tool always prepares.' This is a valuable behavioral disclosure. It adds that the tool produces a 'hash-bound' result and that changes go through a plan/prepare step, which goes beyond the annotation baseline.

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 action, zero filler. The supported-types list is useful and concise. 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?

Given there's an output schema, return-value explanation isn't needed. The tool's relationship to ast_apply_operation is implied but not spelled out — for a prepare-only operation, clarifying that the prepared plan must subsequently be applied would strengthen completeness. Otherwise, the description covers purpose, supported symbols, and the prepare-only nature well.

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 only 50%, so the description should compensate. It notably adds that new_body is 'without the enclosing braces' — a critical format detail. The dry_run/compatibility semantics are also clarified. However, symbol_path format and project_root semantics aren't explained in the description, leaving those to 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 verb+resource ('prepares a hash-bound body replacement') and clarifies scope ('preserving the signature'). It lists supported symbol types (declarations, methods, accessors, function-valued variables/properties). However, it doesn't explicitly distinguish from siblings like ast_rename_symbol or ast_get_operation_preview beyond the general subject matter.

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 you need a body swap while keeping the signature) and lists what it supports, which gives context. However, it doesn't explicitly state when NOT to use it or name alternative tools like ast_get_operation_preview/ast_apply_operation as the pipeline for applying changes, which would clarify the workflow relationship.

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