Skip to main content
Glama

Edit file

edit_file

Replace exact text in a single file with verified, targeted substitutions, optionally applying multiple edits and checking a SHA-256 hash to prevent stale-content changes.

Instructions

Replace exact text: old_text to new_text, or edits[] for several replacements in one file (edits[] wins). Use when: you make a targeted change. old_text must match exactly once unless replace_all=true. Pass expected_sha256 (read_file's sha256 or your last sha256_after) to refuse stale content and get a verified re-read. Avoid when: you rewrite the whole file (write_file) or change several files at once (edit_batch). Output: replacements, sha256_before, sha256_after, verified (when expected_sha256 is given). Failures leave the file unchanged: old_text_not_found (data.mismatch locates the first difference, data.context shows the nearby lines) and old_text_ambiguous (lists each match with context).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "relative_path": "<relative_path>"
    },
    "name": "edit_file"
  }
}

Input Schema

NameRequiredDescriptionDefault
editsNoMultiple section replacements in this file; takes precedence over old_text/new_text.
reasonNoOptional why (max 400 chars), audit-logged.
new_textNoReplacement text (paired with old_text; ignored when edits[] is given).
old_textNoExact text to replace. Must match exactly once unless replace_all=true. Ignored when edits[] is given.
replace_allNotrue replaces every match; false (default) requires exactly one match.
relative_pathYesWorkspace-relative ('.' = root); absolute/.. outside it rejected.
expected_sha256NoHex SHA-256 of the file's current full content. The edit is refused if the file on disk differs. Use sha256_after from your last write/edit of this file; read_file's sha256 only matches when the whole file was returned. When given, the result is re-read after the write and reports verified.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changedv4.5.0
    • removedInput schema / properties / edits / items / properties / replace_all / anyOf
      Removed value: -[
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "maximum": 1,
      -    "minimum": 0,
      -    "type": "integer"
      -  }
      -]
    • changedInput schema / properties / edits / items / properties / replace_all / description
      Previous value: -"1 replaces every match; 0 (default) requires exactly one match."New value: +"true replaces every match; false (default) requires exactly one match."
    • removedInput schema / properties / edits / items / properties / replace_all / maximum
      Removed value: -1
    • removedInput schema / properties / edits / items / properties / replace_all / minimum
      Removed value: -0
    • changedInput schema / properties / edits / items / properties / replace_all / type
      Previous value: -"integer"New value: +"boolean"
    • changedInput schema / properties / old_text / description
      Previous value: -"Exact text to replace. Must match exactly once unless replace_all=1. Ignored when edits[] is given."New value: +"Exact text to replace. Must match exactly once unless replace_all=true. Ignored when edits[] is given."
    • removedInput schema / properties / replace_all / anyOf
      Removed value: -[
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "maximum": 1,
      -    "minimum": 0,
      -    "type": "integer"
      -  }
      -]
    • changedInput schema / properties / replace_all / description
      Previous value: -"1 replaces every match; 0 (default) requires exactly one match."New value: +"true replaces every match; false (default) requires exactly one match."
    • removedInput schema / properties / replace_all / maximum
      Removed value: -1
    • removedInput schema / properties / replace_all / minimum
      Removed value: -0
    • changedInput schema / properties / replace_all / type
      Previous value: -"integer"New value: +"boolean"
  2. Addedv4.0.0

TDQS

A4.7/5.0
Behavior5/5

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

Goes well beyond the annotations, which only declare readOnlyHint=false, destructiveHint=false and idempotentHint=false. It discloses the unique-match requirement, the expect-sha256 staleness refusal with a verified re-read, the atomic failure guarantee ('Failures leave the file unchanged'), and the specific error codes old_text_not_found / old_text_ambiguous including the diagnostic fields (data.mismatch, data.context) each carries.

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?

Dense but zero waste: directive sentence first, then labelled Use when / Avoid when / Output / Failures blocks. Every line carries actionable information, and the most decision-relevant content (what it does, when to use it) is front-loaded.

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

Completeness5/5

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

With no output schema, the description carries that burden and does: it enumerates return fields (replacements, sha256_before, sha256_after, verified) and the conditions under which 'verified' appears. Combined with the documented failure modes, an agent has everything needed to invoke this 7-parameter mutation correctly.

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 coverage is 100%, so all seven parameters already carry descriptions. The description largely restates schema content (match-exactly-once, edits[] precedence, expected_sha256 semantics); the only marginal addition is the workflow hint of feeding back 'your last sha256_after', which the schema also mentions. Baseline 3 applies when the schema does the heavy lifting.

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?

Opens with a specific verb and resource: 'Replace exact text: old_text to new_text, or edits[] for several replacements in one file', and immediately clarifies precedence ('edits[] wins'). The scope is narrow and unmistakable against siblings like write_file and edit_batch.

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?

Explicitly structured as 'Use when: you make a targeted change' and 'Avoid when: you rewrite the whole file (write_file) or change several files at once (edit_batch)', naming the alternative tools and the conditions that select them. Nothing is left to inference.

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