replace_symbol_body
Replace a symbol's entire declaration (signature + body) via LSP or tree-sitter fallback. Optionally include its doc comment. Preview with dry-run and view a unified diff.
Instructions
Replace the entire declaration of a symbol with new content.
The replacement spans the symbol's full Range as reported by the LSP — for a function, this is from 'func' keyword through the closing '}'. Provide the complete new declaration (signature + body) in 'content'.
Set include_doc_comment=true to also cover any contiguous doc comment above the symbol — gopls and most LSP servers report the symbol range starting at the declaration keyword, so without this flag the old doc comment is left orphaned. With it on, your 'content' must include the new doc comment too (or the symbol will have none).
Use rename_symbol if you only want to change the symbol's name. Use this tool when changing logic, signature, or both — addressed by name_path, no line/character coordinates to compute like edit_file's range mode.
The response includes a unified diff of the change — a preview in dry-run, the applied change otherwise — unless show_write_diff is disabled.
Works even when the language server is cold or cannot parse the file: it then locates the symbol via a fresh tree-sitter parse (line-granular range, annotated in the output).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uri | No | Absolute path, file:// URI, or workspace-relative path. | |
| content | No | The full replacement declaration. | |
| dry_run | No | If true (default), preview only; do not write. | |
| dirty_ok | No | Allow editing a file with uncommitted changes. Default false — review/commit first, or pass true to proceed. | |
| name_path | Yes | Slash-separated symbol path within the file (e.g. "ClassName/methodName", or just "funcName" for top-level). | |
| include_doc_comment | No | If true, extend the operation to cover any contiguous comment lines (//, #, /*, *) directly above the symbol declaration. Lets you replace/delete a function together with its doc comment, or insert a new block above an existing doc comment instead of between the comment and its symbol. A WRAPPED declaration (an exported ES declaration under its export statement, a decorated Python def under its @decorator) keeps its doc comment above the wrapper, so WHEN SUCH A COMMENT EXISTS insert_before_symbol and replace_symbol_body extend past the wrapper — replacement content must then reproduce the export keyword or the decorator, or it is dropped. With no doc comment above the wrapper the range starts at the declaration and the wrapper is untouched; safe_delete_symbol never extends past the declaration at all. |