Edit Tool

The Edit tool performs exact string replacements in files. It is the primary tool for making targeted changes — renaming variables, adding lines, modifying function bodies, and any other surgical edit where you want to preserve the rest of the file unchanged.

Parameters

How It Works

The Edit tool uses exact string matching. It finds old_string in the file and replaces it with new_string. The match must be exact — including whitespace and indentation.

Key behaviors:

• By default (replace_all: false), old_string must match exactly one location in the file. If it matches zero or multiple locations, the edit fails.
• With replace_all: true, every occurrence of old_string is replaced.
• The file must have been read earlier in the conversation. Edits on un-read files are rejected.

Usage Examples

Renaming a Variable

> Rename getCwd to getCurrentWorkingDirectory in utils.ts

Agent invokes Edit:
  file_path: src/lib/utils.ts
  old_string: export function getCwd(
  new_string: export function getCurrentWorkingDirectory(
  replace_all: false

Result: ✓ Edit applied (1 occurrence)

Adding a Line

> Add error logging to the catch block in auth.ts

Agent invokes Edit:
  file_path: src/auth/login.ts
  old_string:
    } catch (error) {
      throw new Error('Authentication failed');
  new_string:
    } catch (error) {
      console.error('Auth error:', error);
      throw new Error('Authentication failed');

Result: ✓ Edit applied (1 occurrence)

Replacing All Occurrences

> Rename all instances of userData to userProfile

Agent invokes Edit:
  file_path: src/components/UserCard.tsx
  old_string: userData
  new_string: userProfile
  replace_all: true

Result: ✓ Edit applied (5 occurrences)

Minimal Edit Principle

The agent is trained to use the smallest possible old_string that uniquely identifies the location:

• To change 1 word: include that line plus 1-2 context lines
• To add 1 line: include 2-4 surrounding lines
• Do not replace entire functions to change one line inside them

This minimizes the risk of conflicts and makes diffs easier to review.

Good (minimal):

old_string: const API_URL = 'https://api.example.com';
new_string: const API_URL = 'https://api.newdomain.com';

Bad (too large):

old_string: [entire config object with 30 lines, only changing URL]
new_string: [entire config object with 30 lines, URL changed]

Smart Matching

The Edit tool uses smart matching to handle minor whitespace differences (line endings, indentation variations). If an exact match is not found, the tool attempts to locate the closest match and will report an error with helpful context if it cannot find a suitable match.

Line Number Prefix Awareness

When the agent reads a file, each line is prefixed with a line number:

    1  import React from 'react';
    2
    3  export function App() {
    4    return <div>Hello</div>;
    5  }

The agent must use the content after the line number prefix as old_string. The format is: spaces + line number + tab + content.

# Correct old_string (content only, no line number prefix):
export function App() {

# Incorrect old_string (includes line number prefix):
    3  export function App() {

MultiEdit for Batch Changes

For multiple edits to the same file, the agent can use the MultiEdit variant which applies several edits atomically:

Agent invokes MultiEdit:
  file_path: src/lib/config.ts
  edits:
    - old_string: "port: 3000"  →  new_string: "port: 8080"
    - old_string: "debug: false" →  new_string: "debug: true"

Result: ✓ 2 edits applied atomically

Tip: MultiEdit is efficient for making several independent changes to the same file. All edits succeed or none are applied.

Edit vs Write

Edit is safer because it preserves unmodified portions of the file exactly as they are.

Common Patterns

Rename a function:

old_string: function handleClick(
new_string: function handleButtonClick(

Add an import:

old_string: import { useState } from 'react';
new_string: import { useState, useCallback } from 'react';

Remove a line:

old_string: console.log('debug:', data);
  return data;
new_string: return data;

Change a default value:

old_string: const timeout = 5000;
new_string: const timeout = 10000;

Next Steps

• Read — Reading files before editing
• Write — Creating and overwriting files
• Tools Overview — All available tools