Skip to main content
Glama

Edit File

edit_file
Destructive

Apply ordered line-based text replacements within allowed directories, preview results as a git-style diff, and write nothing if any match fails.

Instructions

Make line-based edits to a text file. Edits apply in order, each to the result of the ones before it, and each replaces the first match of its oldText with newText. oldText must match the file's text exactly, except that line endings (LF or CRLF) never matter and, when there is no exact match, a run of whole lines matches if each line is equal once leading and trailing whitespace is ignored (newText then takes the file's indentation). Whitespace inside a line must match. If any edit has no match, nothing is written and the error shows the closest lines of the file, numbered, to copy oldText from. Returns a git-style diff showing the changes made. Only works within allowed directories.

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": {
      "path": "<path>",
      "edits": "<edits>"
    },
    "name": "edit_file"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathYesThe text file to edit. Absolute, or relative to an allowed directory; it must resolve inside the allowed directories.
editsYesThe replacements to make, applied in order, each to the result of the ones before it. If any one has no match, none is written.
dryRunNoPreview changes using git-style diff format

Output Schema

NameRequiredDescriptionDefault
contentYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.3.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 (destructiveHint=true, readOnlyHint=false, idempotentHint=false) by disclosing atomicity: 'If any edit has no match, nothing is written,' and describing the error payload with numbered closest lines. It also describes ordering semantics across edits and the git-style diff return, which is exactly the behavioral context an agent needs before invoking a destructive mutation.

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-loaded with purpose and free of filler, but it is a single dense paragraph packing matching rules, fallback behavior, error format, and return format together. Bullet-style separation would make the layered matching rules easier to parse, though nothing is redundant.

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?

For a destructive, three-parameter mutation tool with an output schema, the description covers atomicity, ordering, match semantics, failure behavior, and directory restrictions. Nothing an agent needs to call it correctly is missing, and return values are appropriately left to the output schema.

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

Parameters5/5

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

Although schema coverage is 100%, the description adds real meaning the schema does not: edits apply in order each to the prior result, oldText must match exactly except line endings, a whitespace-insensitive whole-line fallback exists, and newText adopts the file's indentation. The dryRun preview behavior is also clarified beyond the terse schema text.

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 ('Make line-based edits to a text file') and immediately scopes it to line-based replacement rather than whole-file writes, which separates it from write_file and append_file without naming them. The matching semantics are precise enough that an agent knows exactly what kind of edit this performs.

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?

The description clearly implies the use case (surgical text replacement rather than rewriting a file) and states the environment constraint 'Only works within allowed directories.' It does not explicitly say when to prefer write_file or append_file instead, so it stops short of naming alternatives and exclusions.

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