Skip to content

text-edit

Replace text in an existing file using exact string matching.

Category: Write-capable

Parameters

filePath (required)
Absolute path to the file to modify.
oldString (required)

The text to replace. Must match the file contents exactly, including whitespace, indentation, and line endings. CRLF line endings are normalized before matching, so LF-only values match CRLF files.

Pass an empty string ("") to create a new file or overwrite an existing one entirely with newString.

newString (required)
The replacement text. Must differ from oldString.
replaceAll (optional)
When true, all occurrences of oldString are replaced. When false (the default), the edit fails if oldString appears more than once — the agent must supply enough context to make oldString unique.

Behavior

  • If oldString is not found in the file, the tool fails immediately with an error. The agent should re-read the file and retry with the exact content.
  • If oldString appears more than once and replaceAll is false, the tool returns an error listing the count. Either set replaceAll to true or provide more surrounding context to make the string unique.
  • If oldString is empty and the file's parent directory does not exist, the parent directory is created automatically.

Output

Edited file successfully. on success, or an error message describing why the edit could not be applied.