replace - Replace Text

Overview

The replace tool replaces text within a file. By default, it replaces a single occurrence, but can replace multiple occurrences when expected_replacements is specified. This tool requires providing significant context around the change to ensure precise targeting.

Tool Name

• Internal Name: replace
• Display Name: Edit
• Icon: Pencil

Parameters

Required Parameters

Parameter	Type	Description
file_path	string	The absolute path to the file to modify. Must start with /.
old_string	string	The exact literal text to replace (including all whitespace, indentation, newlines, and surrounding code etc.).
new_string	string	The exact literal text to replace old_string with (also including all whitespace, indentation, newlines, and surrounding code etc.). Ensure the resulting code is correct and idiomatic.

Optional Parameters

Parameter	Type	Description
expected_replacements	number	Number of replacements expected. Defaults to 1 if not specified. Use when you want to replace multiple occurrences. Minimum value is 1.
modified_by_user	boolean	Whether the edit was modified manually by the user. Used for internal tracking.

Features

1. Exact Matching:

   • Must provide exact text match (including spaces, indentation, newlines)
   • Do not escape old_string or new_string
   • Matching is case-sensitive

2. Context Requirements:

   • For single replacements: Include at least 3 lines of context BEFORE and AFTER the target text
   • Match whitespace and indentation precisely
   • If string matches multiple locations or doesn't match exactly, the tool will fail

3. Multiple Replacements:

   • Set expected_replacements to the number of occurrences to replace
   • Tool will replace ALL occurrences that match old_string exactly
   • Ensure the number of replacements matches your expectation

4. Security Restrictions:

   • File path must be absolute
   • File must be within project root directory
   • Use read_file to examine file content before attempting replacement

Important Notes

If ANY of the following are not satisfied, the tool will fail:

1. file_path MUST be an absolute path
2. old_string MUST be the exact literal text to replace (including all whitespace, indentation, newlines, and surrounding code etc.)
3. new_string MUST be the exact literal text to replace old_string with (also including all whitespace, indentation, newlines, and surrounding code etc.)
4. NEVER escape old_string or new_string

CRITICAL for old_string: Must uniquely identify the single instance to change. Include at least 3 lines of context BEFORE and AFTER the target text, matching whitespace and indentation precisely.

Usage Examples

Single Replacement (with context)

{
  "file_path": "/home/user/project/src/app.ts",
  "old_string": "function greet(name: string) {\n  console.log('Hello, ' + name);\n  return name;\n}",
  "new_string": "function greet(name: string): string {\n  console.log(`Hello, ${name}`);\n  return name;\n}"
}

Multiple Replacements

{
  "file_path": "/home/user/project/src/utils.ts",
  "old_string": "var ",
  "new_string": "const ",
  "expected_replacements": 5
}

Replace Indented Code Block

{
  "file_path": "/home/user/project/src/component.tsx",
  "old_string": "  render() {\n    return (\n      <div>Old Content</div>\n    );\n  }",
  "new_string": "  render() {\n    return (\n      <div>New Content</div>\n    );\n  }"
}

Return Value

The tool returns an object containing:

• llmContent: Operation result description
• returnDisplay: User-friendly display information (including file diff)
• summary: Operation summary (e.g., "Replaced 1 occurrence in file.ts")

Error Handling

Possible error scenarios:

1. Match Errors:

   • Cannot find old_string
   • Found multiple matches but expected_replacements is 1
   • Actual replacement count doesn't match expected_replacements

2. Path Errors:

   • Path is not absolute
   • Path is outside project root directory
   • File does not exist

3. Parameter Errors:

   • Missing required parameters
   • old_string or new_string is empty
   • expected_replacements is less than 1

Workflow

1. Read File: First use read_file to examine the file's current content
2. Plan Replacement: Determine the exact text to replace and context
3. Execute Replacement: Call the replace tool
4. Verify Result: Check if replacement was successful

Notes

1. Always use read_file: Use the read_file tool to examine the file's current content before attempting a text replacement
2. Provide Sufficient Context: For single replacements, include at least 3 lines of context BEFORE and AFTER the target text
3. Do Not Escape: Do not escape old_string or new_string, that would break the exact literal text requirement
4. Verify Indentation: Ensure spaces and indentation match exactly
5. Line Endings: Be aware of line ending consistency (LF vs CRLF)

Related Tools

• read_file: Read file content
• write_file: Write entire file
• search_file_content: Search file content
• list_directory: List directory contents