Skip to main content
Glama
dimitar-grigorov

mcp-file-tools

by dimitar-grigorov
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Go
Local

edit_file

Destructive

Modify a file using exact text replacements or a unified diff while preserving encoding and line endings. Returns the applied diff; use instead of read+write for safe, verifiable edits.

Instructions

Edit one file with replacements or a unified diff. Returns a unified diff and keeps the file's encoding and line endings. PREFER THIS over read+write to modify a file. In 'ask before edits' mode call dryRun=true first, show the diff, then dryRun=false once the user confirms; with auto-edit permissions go straight to dryRun=false. On no match, prefer fixing oldText from the closest-content hint. Alternatively retry that edit with similarity (0.0-1.0) for whitespace/comment drift, not different code. Do NOT re-read the file afterwards to verify: a success with a diff means the edit is on disk, a failed edit changes nothing. A file with mixed line endings is repaired to its dominant style; the result says how many endings changed, so report that to the user. Parameters: path; exactly one of edits [{oldText, newText, similarity?, replaceAll?}] or patch (---/+++/@@ unified diff for one file); dryRun (default false); encoding (auto); expectedHash (the contentHash of the read this edit is based on — the edit fails and changes nothing if the file has since changed). oldText must match ONE place: several matches fail with their line numbers and change nothing — add surrounding lines to pick one, or set replaceAll: true to change them all and report the count to the user. Edits apply in order. Matching ignores per-line leading/trailing whitespace and CRLF/LF, but interior spacing must match; newText is re-indented. Example: {"path": "D:\src\unit1.pas", "edits": [{"oldText": "i: Integer;", "newText": "i: NativeInt;"}, {"oldText": "for i := 0 to 10 do", "newText": "for i := 0 to 20 do"}], "dryRun": true}

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pathYes
editsNo
patchNo
dryRunNo
encodingNo
expectedHashNo
forceWritableNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv4.5.0
    • addedInput schema / properties / expectedHash
      Added value: +{
+  "type": "string"
+}
  2. Changed1 schema field changedv4.2.0
    • addedInput schema / properties / edits / items / properties / replaceAll
      Added value: +{
+  "type": "boolean"
+}
  3. Addedv3.3.0
  4. Removedv0.1.1
  5. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

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

Annotations declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered, yet the description still adds major context: atomicity ('a failed edit changes nothing'), encoding/line-ending preservation, mixed-ending repair with a reported count, ordered application, and exact match/failure semantics.

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

Conciseness4/5

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

Front-loads the preference and the dryRun workflow, then flows into matching and parameter details. Dense and largely earns its length, though it is overloaded for a single paragraph.

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 7-parameter mutation tool with no output schema and an unusual input shape, coverage is strong: behavior, failure modes, concurrency guard, and matching rules are all stated. Missing only forceWritable and any hint of the exact diff return shape.

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 0%, so the description carries the burden and documents path, the edits shape (oldText/newText/similarity/replaceAll), patch format, dryRun default, encoding auto, and expectedHash concurrency semantics. The only gap is that the schema's forceWritable parameter is never mentioned.

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 precise verb+resource ('Edit one file with replacements or a unified diff') and explicitly distinguishes itself from the read+write approach with 'PREFER THIS over read+write'.

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?

Gives an explicit workflow for 'ask before edits' vs auto-edit permissions, tells when to use similarity vs different code, when to add surrounding lines vs replaceAll, and forbids re-reading to verify.

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

Deploy Server

Other Tools