Skip to main content
Glama

Edit Files

edit
Destructive

Replace exact text in text files in place by supplying oldText and newText strings. Apply single-file or batch replacements; a file is written only if all its matches succeed.

Instructions

Edit text files in place by replacing exact oldText with newText, like str_replace. Pass path with edits, or files for a batch; never both. Each oldText must match exactly once, and a file is written only if all its edits match. replace_text replaces every occurrence across files.

Input Schema

NameRequiredDescriptionDefault
pathNoSingle file path; mutually exclusive with files
editsNoReplacements applied to path (required with path); not allowed with files
filesNoPer-file entries (batch mode)
dryRunNoPreview diffs without writing to disk (default: false = apply edits)
ignoreWhitespaceNoIgnore leading/trailing whitespace differences when matching oldText; newText is re-indented to the match and replaces its inner blank lines

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.13.0
    • changedInput schema / properties / ignoreWhitespace / description
      Previous value: -"Ignore leading/trailing whitespace differences when matching oldText"New value: +"Ignore leading/trailing whitespace differences when matching oldText; newText is re-indented to the match and replaces its inner blank lines"
  2. Changed2 schema fields changedv2.9.1
    • removedInput schema / oneOf
      Removed value: -[
      -  {
      -    "required": [
      -      "path",
      -      "edits"
      -    ]
      -  },
      -  {
      -    "required": [
      -      "files"
      -    ]
      -  }
      -]
    • changedInput schema / properties / edits / description
      Previous value: -"Replacements applied to path; not allowed when using files"New value: +"Replacements applied to path (required with path); not allowed with files"
  3. Changed11 schema fields changedv2.8.1
    • removedInput schema / $defs
      Removed value: -{
      -  "EditSpec": {
      -    "additionalProperties": false,
      -    "properties": {
      -      "newText": {
      -        "description": "Replacement text. Use an empty string to delete the matched oldText.",
      -        "examples": [
      -          "const x = 2;",
      -          "function newName(",
      -          ""
      -        ],
      -        "type": "string"
      -      },
      -      "oldText": {
      -        "description": "Exact literal text to locate in the file; it must match exactly once. Include 3-5 lines of context so it does — an oldText found in several places fails with their line numbers.",
      -        "examples": [
      -          "const x = 1;",
      -          "function oldName("
      -        ],
      -        "minLength": 1,
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "oldText",
      -      "newText"
      -    ],
      -    "type": "object"
      -  }
      -}
    • removedInput schema / properties / edits / items / $ref
      Removed value: -"#/$defs/EditSpec"
    • addedInput schema / properties / edits / items / additionalProperties
      Added value: +false
    • addedInput schema / properties / edits / items / properties
      Added value: +{
      +  "newText": {
      +    "description": "Replacement text. Use an empty string to delete the matched oldText.",
      +    "examples": [
      +      "const x = 2;",
      +      "function newName(",
      +      ""
      +    ],
      +    "type": "string"
      +  },
      +  "oldText": {
      +    "description": "Exact literal text to locate in the file; it must match exactly once. Include 3-5 lines of context so it does — an oldText found in several places fails with their line numbers.",
      +    "examples": [
      +      "const x = 1;",
      +      "function oldName("
      +    ],
      +    "minLength": 1,
      +    "type": "string"
      +  }
      +}
    • addedInput schema / properties / edits / items / required
      Added value: +[
      +  "oldText",
      +  "newText"
      +]
    • addedInput schema / properties / edits / items / type
      Added value: +"object"
    • removedInput schema / properties / files / items / properties / edits / items / $ref
      Removed value: -"#/$defs/EditSpec"
    • addedInput schema / properties / files / items / properties / edits / items / additionalProperties
      Added value: +false
    • addedInput schema / properties / files / items / properties / edits / items / properties
      Added value: +{
      +  "newText": {
      +    "description": "Replacement text. Use an empty string to delete the matched oldText.",
      +    "examples": [
      +      "const x = 2;",
      +      "function newName(",
      +      ""
      +    ],
      +    "type": "string"
      +  },
      +  "oldText": {
      +    "description": "Exact literal text to locate in the file; it must match exactly once. Include 3-5 lines of context so it does — an oldText found in several places fails with their line numbers.",
      +    "examples": [
      +      "const x = 1;",
      +      "function oldName("
      +    ],
      +    "minLength": 1,
      +    "type": "string"
      +  }
      +}
    • addedInput schema / properties / files / items / properties / edits / items / required
      Added value: +[
      +  "oldText",
      +  "newText"
      +]
    • addedInput schema / properties / files / items / properties / edits / items / type
      Added value: +"object"
  4. Changed3 schema fields changedv2.4.1
    • addedInput schema / $defs / EditSpec / properties / newText / examples
      Added value: +[
      +  "const x = 2;",
      +  "function newName(",
      +  ""
      +]
    • addedInput schema / $defs / EditSpec / properties / oldText / examples
      Added value: +[
      +  "const x = 1;",
      +  "function oldName("
      +]
    • addedInput schema / $schema
      Added value: +"https://json-schema.org/draft/2020-12/schema"
  5. Changed1 schema field changedv2.3.0
    • changedInput schema / $defs / EditSpec / properties / oldText / description
      Previous value: -"Exact literal text to locate in the file. Must include 3-5 lines of context to ensure uniqueness and avoid matching the wrong block."New value: +"Exact literal text to locate in the file; it must match exactly once. Include 3-5 lines of context so it does — an oldText found in several places fails with their line numbers."
  6. Changed1 schema field changedv2.1.5
    • changedOutput schema / (root)
      Previous value: -{
      -  "additionalProperties": false,
      -  "properties": {
      -    "results": {
      -      "description": "Per-path edit results ordered to match the input paths",
      -      "items": {
      -        "additionalProperties": false,
      -        "properties": {
      -          "error": {
      -            "additionalProperties": false,
      -            "description": "Error details; present on failure",
      -            "properties": {
      -              "code": {
      -                "type": "string"
      -              },
      -              "message": {
      -                "type": "string"
      -              },
      -              "path": {
      -                "type": "string"
      -              },
      -              "suggestion": {
      -                "type": "string"
      -              }
      -            },
      -            "required": [
      -              "code",
      -              "message"
      -            ],
      -            "type": "object"
      -          },
      -          "path": {
      -            "description": "Requested file path",
      -            "type": "string"
      -          },
      -          "value": {
      -            "additionalProperties": false,
      -            "description": "Edit result; present on success",
      -            "properties": {
      -              "appliedEdits": {
      -                "description": "Number of edits successfully applied",
      -                "minimum": 0,
      -                "type": "integer"
      -              },
      -              "diff": {
      -                "description": "Unified diff of all changes (present only in dryRun mode)",
      -                "type": "string"
      -              },
      -              "kind": {
      -                "description": "Broad file kind: text, binary, image, audio, or pdf",
      -                "enum": [
      -                  "text",
      -                  "binary",
      -                  "image",
      -                  "audio",
      -                  "pdf"
      -                ],
      -                "type": "string"
      -              },
      -              "lineCount": {
      -                "description": "Number of lines in the file after edits",
      -                "minimum": 0,
      -                "type": "integer"
      -              },
      -              "lineRange": {
      -                "description": "Line range [firstLine, lastLine] covering all applied edits",
      -                "prefixItems": [
      -                  {
      -                    "exclusiveMinimum": 0,
      -                    "type": "integer"
      -                  },
      -                  {
      -                    "exclusiveMinimum": 0,
      -                    "type": "integer"
      -                  }
      -                ],
      -                "type": "array"
      -              },
      -              "linesAdded": {
      -                "description": "Net lines added by all applied edits",
      -                "minimum": 0,
      -                "type": "integer"
      -              },
      -              "linesRemoved": {
      -                "description": "Net lines removed by all applied edits",
      -                "minimum": 0,
      -                "type": "integer"
      -              },
      -              "mimeType": {
      -                "description": "Detected MIME type of the file",
      -                "type": "string"
      -              },
      -              "modified": {
      -                "description": "Last modification timestamp after edits (ISO 8601 UTC)",
      -                "format": "date-time",
      -                "type": "string"
      -              },
      -              "path": {
      -                "description": "Resolved absolute path of the edited file",
      -                "type": "string"
      -              },
      -              "resourceUri": {
      -                "description": "Resource URI pointing to the updated file content; omitted when no edit matched (appliedEdits is 0) and the file was left untouched",
      -                "type": "string"
      -              },
      -              "size": {
      -                "description": "File size in bytes after edits",
      -                "minimum": 0,
      -                "type": "integer"
      -              },
      -              "unmatchedEdits": {
      -                "description": "oldText values that did not match any content in the file",
      -                "items": {
      -                  "type": "string"
      -                },
      -                "type": "array"
      -              }
      -            },
      -            "required": [
      -              "path",
      -              "size",
      -              "lineCount",
      -              "mimeType",
      -              "kind",
      -              "modified",
      -              "appliedEdits"
      -            ],
      -            "type": "object"
      -          }
      -        },
      -        "required": [
      -          "path"
      -        ],
      -        "type": "object"
      -      },
      -      "type": "array"
      -    },
      -    "summary": {
      -      "additionalProperties": false,
      -      "properties": {
      -        "failed": {
      -          "minimum": 0,
      -          "type": "integer"
      -        },
      -        "succeeded": {
      -          "minimum": 0,
      -          "type": "integer"
      -        },
      -        "total": {
      -          "minimum": 0,
      -          "type": "integer"
      -        }
      -      },
      -      "required": [
      -        "total",
      -        "succeeded",
      -        "failed"
      -      ],
      -      "type": "object"
      -    }
      -  },
      -  "required": [
      -    "results",
      -    "summary"
      -  ],
      -  "type": "object"
      -}New value: +null
  7. Changed27 schema fields changedv2.0.0
    • addedInput schema / $defs
      Added value: +{
      +  "EditSpec": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "newText": {
      +        "description": "Replacement text. Use an empty string to delete the matched oldText.",
      +        "type": "string"
      +      },
      +      "oldText": {
      +        "description": "Exact literal text to locate in the file. Must include 3-5 lines of context to ensure uniqueness and avoid matching the wrong block.",
      +        "minLength": 1,
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "oldText",
      +      "newText"
      +    ],
      +    "type": "object"
      +  }
      +}
    • removedInput schema / $schema
      Removed value: -"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / oneOf
      Added value: +[
      +  {
      +    "required": [
      +      "path",
      +      "edits"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "files"
      +    ]
      +  }
      +]
    • changedInput schema / properties / dryRun / description
      Previous value: -"Preview edits without writing. Check `unmatchedEdits` in response."New value: +"Preview diffs without writing to disk (default: false = apply edits)"
    • changedInput schema / properties / edits / description
      Previous value: -"List of replacements to apply sequentially. Each edit replaces the first occurrence of oldText."New value: +"Replacements applied to path; not allowed when using files"
    • addedInput schema / properties / edits / items / $ref
      Added value: +"#/$defs/EditSpec"
    • removedInput schema / properties / edits / items / additionalProperties
      Removed value: -false
    • removedInput schema / properties / edits / items / properties
      Removed value: -{
      -  "newText": {
      -    "description": "Replacement string. Preserve surrounding indentation style.",
      -    "type": "string"
      -  },
      -  "oldText": {
      -    "description": "Exact literal string to replace (character-for-character). Include 3–5 lines of context for unique targeting.",
      -    "maxLength": 102400,
      -    "minLength": 1,
      -    "type": "string"
      -  }
      -}
    • removedInput schema / properties / edits / items / required
      Removed value: -[
      -  "oldText",
      -  "newText"
      -]
    • removedInput schema / properties / edits / items / type
      Removed value: -"object"
    • addedInput schema / properties / edits / maxItems
      Added value: +100
    • addedInput schema / properties / files
      Added value: +{
      +  "description": "Per-file entries (batch mode)",
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "edits": {
      +        "description": "Replacements to apply to this specific file",
      +        "items": {
      +          "$ref": "#/$defs/EditSpec"
      +        },
      +        "maxItems": 100,
      +        "minItems": 1,
      +        "type": "array"
      +      },
      +      "path": {
      +        "description": "File or directory path inside an allowed workspace root.",
      +        "maxLength": 4096,
      +        "minLength": 1,
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "path",
      +      "edits"
      +    ],
      +    "type": "object"
      +  },
      +  "maxItems": 5,
      +  "minItems": 1,
      +  "type": "array"
      +}
    • changedInput schema / properties / ignoreWhitespace / description
      Previous value: -"Treat all whitespace sequences as equivalent when matching oldText."New value: +"Ignore leading/trailing whitespace differences when matching oldText"
    • changedInput schema / properties / path / description
      Previous value: -"Absolute path to file or directory."New value: +"Single file path; mutually exclusive with files"
    • removedInput schema / required
      Removed value: -[
      -  "path",
      -  "edits"
      -]
    • removedOutput schema / $schema
      Removed value: -"https://json-schema.org/draft/2020-12/schema"
    • removedOutput schema / properties / appliedEdits
      Removed value: -{
      -  "maximum": 9007199254740991,
      -  "minimum": 0,
      -  "type": "integer"
      -}
    • removedOutput schema / properties / diff
      Removed value: -{
      -  "description": "Unified diff of changes (dryRun)",
      -  "type": "string"
      -}
    • removedOutput schema / properties / lineRange
      Removed value: -{
      -  "description": "Line range modified [start, end] (1-based)",
      -  "prefixItems": [
      -    {
      -      "maximum": 9007199254740991,
      -      "minimum": 1,
      -      "type": "integer"
      -    },
      -    {
      -      "maximum": 9007199254740991,
      -      "minimum": 1,
      -      "type": "integer"
      -    }
      -  ],
      -  "type": "array"
      -}
    • removedOutput schema / properties / linesAdded
      Removed value: -{
      -  "description": "Lines added",
      -  "maximum": 9007199254740991,
      -  "minimum": 0,
      -  "type": "integer"
      -}
    • removedOutput schema / properties / linesRemoved
      Removed value: -{
      -  "description": "Lines removed",
      -  "maximum": 9007199254740991,
      -  "minimum": 0,
      -  "type": "integer"
      -}
    • removedOutput schema / properties / ok
      Removed value: -{
      -  "type": "boolean"
      -}
    • removedOutput schema / properties / path
      Removed value: -{
      -  "type": "string"
      -}
    • addedOutput schema / properties / results
      Added value: +{
      +  "description": "Per-path edit results ordered to match the input paths",
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "error": {
      +        "additionalProperties": false,
      +        "description": "Error details; present on failure",
      +        "properties": {
      +          "code": {
      +            "type": "string"
      +          },
      +          "message": {
      +            "type": "string"
      +          },
      +          "path": {
      +            "type": "string"
      +          },
      +          "suggestion": {
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "code",
      +          "message"
      +        ],
      +        "type": "object"
      +      },
      +      "path": {
      +        "description": "Requested file path",
      +        "type": "string"
      +      },
      +      "value": {
      +        "additionalProperties": false,
      +        "description": "Edit result; present on success",
      +        "properties": {
      +          "appliedEdits": {
      +            "description": "Number of edits successfully applied",
      +            "minimum": 0,
      +            "type": "integer"
      +          },
      +          "diff": {
      +            "description": "Unified diff of all changes (present only in dryRun mode)",
      +            "type": "string"
      +          },
      +          "kind": {
      +            "description": "Broad file kind: text, binary, image, audio, or pdf",
      +            "enum": [
      +              "text",
      +              "binary",
      +              "image",
      +              "audio",
      +              "pdf"
      +            ],
      +            "type": "string"
      +          },
      +          "lineCount": {
      +            "description": "Number of lines in the file after edits",
      +            "minimum": 0,
      +            "type": "integer"
      +          },
      +          "lineRange": {
      +            "description": "Line range [firstLine, lastLine] covering all applied edits",
      +            "prefixItems": [
      +              {
      +                "exclusiveMinimum": 0,
      +                "type": "integer"
      +              },
      +              {
      +                "exclusiveMinimum": 0,
      +                "type": "integer"
      +              }
      +            ],
      +            "type": "array"
      +          },
      +          "linesAdded": {
      +            "description": "Net lines added by all applied edits",
      +            "minimum": 0,
      +            "type": "integer"
      +          },
      +          "linesRemoved": {
      +            "description": "Net lines removed by all applied edits",
      +            "minimum": 0,
      +            "type": "integer"
      +          },
      +          "mimeType": {
      +            "description": "Detected MIME type of the file",
      +            "type": "string"
      +          },
      +          "modified": {
      +            "description": "Last modification timestamp after edits (ISO 8601 UTC)",
      +            "format": "date-time",
      +            "type": "string"
      +          },
      +          "path": {
      +            "description": "Resolved absolute path of the edited file",
      +            "type": "string"
      +          },
      +          "resourceUri": {
      +            "description": "Resource URI pointing to the updated file content; omitted when no edit matched (appliedEdits is 0) and the file was left untouched",
      +            "type": "string"
      +          },
      +          "size": {
      +            "description": "File size in bytes after edits",
      +            "minimum": 0,
      +            "type": "integer"
      +          },
      +          "unmatchedEdits": {
      +            "description": "oldText values that did not match any content in the file",
      +            "items": {
      +              "type": "string"
      +            },
      +            "type": "array"
      +          }
      +        },
      +        "required": [
      +          "path",
      +          "size",
      +          "lineCount",
      +          "mimeType",
      +          "kind",
      +          "modified",
      +          "appliedEdits"
      +        ],
      +        "type": "object"
      +      }
      +    },
      +    "required": [
      +      "path"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / properties / summary
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "failed": {
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    "succeeded": {
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    "total": {
      +      "minimum": 0,
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "total",
      +    "succeeded",
      +    "failed"
      +  ],
      +  "type": "object"
      +}
    • removedOutput schema / properties / unmatchedEdits
      Removed value: -{
      -  "description": "Edits that could not be applied",
      -  "items": {
      -    "type": "string"
      -  },
      -  "type": "array"
      -}
    • changedOutput schema / required
      Previous value: -[
      -  "ok"
      -]New value: +[
      +  "results",
      +  "summary"
      +]
  8. Addedv1.15.3
  9. Removedv1.15.0
  10. First observed

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag this as destructive and non-read-only, so the description's job is to add specifics — and it does: 'Each oldText must match exactly once, and a file is written only if all its edits match,' which discloses uniqueness constraints and per-file all-or-nothing atomicity. It omits failure reporting details (partially covered by the schema's mention of line numbers) and says nothing about dryRun, which is the safety valve for a destructive write.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, zero waste, front-loaded with the core mechanism before the mode-selection rule and the matching constraint. Each sentence contributes a distinct fact an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a five-parameter destructive mutation with no output schema, the description covers mechanism, mode exclusivity, match uniqueness, and per-file atomicity — the essentials. Gaps remain on failure/rollback behavior across multiple files and on when to reach for dryRun, both of which matter for a tool annotated destructiveHint=true.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents path, edits, files, dryRun, and ignoreWhitespace in detail. The description restates the path/edits vs files exclusivity and the match-once rule, adding only the 'never both' framing beyond structured data. Baseline 3 is appropriate when the schema carries the semantic load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Edit text files in place by replacing exact oldText with newText') plus an analogy ('like str_replace') that pins down the mechanism instantly. It also names the sibling it differs from — 'replace_text replaces every occurrence across files' — so the agent can distinguish the two without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly gives the two calling modes and the exclusion: 'Pass path with edits, or files for a batch; never both.' It also routes the agent to replace_text for the global-replace case. It stops short of covering other plausible alternatives (patch, create, undo) or when to prefer dryRun, so it is clear context rather than full when/when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.