Skip to main content
Glama

Edit Files

edit
Destructive

Replace exact text in files with precision: each oldText must match once, and writes only occur when all edits match. Batch multiple files or preview with dry-run.

Instructions

Edit text files in place by replacing exact oldText with newText, like str_replace. 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

TableJSON Schema
NameRequiredDescriptionDefault
pathNoSingle file path; mutually exclusive with files
editsNoReplacements applied to path; not allowed when using files
filesNoPer-file entries (batch mode)
dryRunNoPreview diffs without writing to disk (default: false = apply edits)
ignoreWhitespaceNoIgnore leading/trailing whitespace differences when matching oldText

Schema Changelog

Changes observed during successful MCP inspections.

  1. 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"
  2. 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."
  3. 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
  4. 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"
      +]
  5. Addedv1.15.3
  6. Removedv1.15.0
  7. First observed

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description carries a lighter burden. It adds valuable behavioral context: the atomicity of writes ('a file is written only if all its edits match') and the uniqueness requirement for oldText. This goes beyond the annotations and is useful for the agent to predict outcomes.

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?

Two sentences, with the core purpose front-loaded and the key behavioral constraints stated economically. No fluff, and the alternative tool is mentioned in the same breath, making it highly scannable.

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?

The description covers the core semantics (exact match, uniqueness, atomicity) and the primary alternative. It does not mention dryRun or ignoreWhitespace, but these are fully documented in the schema with defaults and descriptions. The batch mode via files is also implied by the sibling contrast but not explicitly highlighted; still, the schema covers it. Overall adequate for a destructive edit tool with strong schema support.

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 fully documents each parameter. The description adds the str_replace analogy and the uniqueness/atomicity constraints, which reinforce but do not substantially extend the schema. This meets the baseline for a well-documented schema.

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?

The description states a specific action (edit text files in place) with a clear verb-resource pair, and explicitly contrasts with the sibling replace_text tool, which replaces every occurrence across files. This distinguishes it from alternatives immediately.

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?

It gives clear guidance on when to use this tool versus replace_text ('replace_text replaces every occurrence across files'), and states the exact-match-once constraint. However, it does not explicitly address other siblings like patch or create, leaving some inference to the agent. The guidance is clear for the most relevant alternative but not exhaustive.

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