Skip to main content
Glama

Edit Files

edit
Destructive

Apply exact text replacements to files with context matching, batch editing up to 5 files, and preview diffs before writing.

Instructions

Apply sequential literal string replacements to one or more files (max 5 files per call). Modes: single-file { path, edits } or per-file { files: [{ path, edits }] }. oldText must match file content exactly and only once; include 3-5 lines of surrounding context, or the edit fails listing the lines it matched. Set dryRun=true to preview diffs without writing. For glob-based bulk regex replacement across many files, use replace_text instead.

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.6/5.0
Behavior4/5

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

Annotations already signal destructive/write behavior, and the description reinforces this by stating edits are applied and that dryRun can preview without writing. It adds useful behavioral details beyond annotations: exact-once matching, failure with matched line numbers, and the 5-file cap. It does not contradict annotations, though it could mention atomicity or partial-apply behavior on multi-edit failures.

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?

The description is dense but every sentence earns its place: core behavior, modes, matching constraints, dry-run option, and the alternative tool. It is front-loaded with the most important operational fact and avoids unnecessary filler.

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 destructive 5-parameter tool with no output schema, the description covers the critical invocation aspects: files cap, mode shapes, matching failure behavior, dryRun, and the main alternative. It does not describe the success return format or behavior across multiple files when one edit fails, which would make it fully complete.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the oldText uniqueness requirement, recommending 3-5 lines of context, and clarifying the two invocation modes. It does not cover ignoreWhitespace, but the schema already documents that parameter.

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 names a specific action ('apply sequential literal string replacements'), identifies the resource ('one or more files'), and scopes it with a clear limit (max 5 files per call). It also distinguishes itself from the sibling replace_text, so an agent can tell them apart immediately.

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

Usage Guidelines5/5

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

The description explicitly routes alternative usage: 'For glob-based bulk regex replacement across many files, use replace_text instead.' It also explains when to use dryRun and lays out the single-file vs per-file modes, giving the agent clear selection criteria.

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