Skip to main content

edit

The edit tool performs search-and-replace operations on files, replacing either the first occurrence (default) or all occurrences when explicitly specified. It provides flexible control over replacement scope.

Parameters​

The tool accepts these parameters:

  • file_path (required): The path of the file to modify relative to the current working directory.
  • old_string (required): The exact text to search for and replace.
  • new_string (required): The text to replace occurrences with.
  • replace_all (optional): Boolean flag. When true, replaces all occurrences. When false or omitted, replaces only the first occurrence.

What It Does​

This tool searches for an exact string in a file and replaces either the first occurrence or all occurrences based on the replace_all parameter. By default, it replaces only the first match, making it suitable for targeted single-instance changes.

When is it used?​

  • When updating a single specific occurrence of text (default behavior)
  • When the first instance requires different handling than subsequent ones
  • When you need explicit control over whether to replace once or globally
  • When making targeted changes to specific instances without affecting others
  • When replacing all instances by setting replace_all: true

Key Features​

  • Replaces first occurrence only by default (conservative behavior)
  • Optional replace_all parameter for global replacement
  • Exact string matching (no regex or fuzzy matching)
  • Shows preview of changes before applying
  • Preserves file formatting and structure
  • User approval required before applying changes

Limitations​

  • Requires exact string matches (case-sensitive, whitespace-sensitive)
  • Cannot use regular expressions or patterns
  • Not suitable for context-dependent replacements requiring code analysis
  • Less precise than apply_diff for complex edits
  • Cannot specify which specific occurrence to replace (first vs. second vs. third)

How It Works​

When the edit tool is invoked, it follows this process:

  1. Parameter Validation: Validates required file_path, old_string, and new_string parameters.
  2. File Loading: Reads the target file content.
  3. Search Operation: Searches for occurrences of old_string in the file.
  4. Replacement Logic:
    • If replace_all is false or omitted: replaces only the first occurrence
    • If replace_all is true: replaces all occurrences
  5. User Review: Shows a preview of changes for user approval.
  6. Application: Applies changes to the file if approved.
  7. Feedback: Reports the result of the operation.

Relation to Other Tools​

  • edit: Replaces first occurrence by default (this tool)
  • edit_file: Always replaces all occurrences
  • search_replace: Always replaces all occurrences
  • apply_diff: Use for precise, context-aware edits with fuzzy matching
Deprecated Alias

SearchAndReplaceTool is a deprecated internal alias for EditTool. They are the same tool.