Skip to main content
Glama

Change part of a code file

edit_file

Replace one exact passage in an existing file without rewriting the full content, preserving all other bytes. Use for targeted edits or deletions where the old text must match once.

Instructions

Replaces ONE passage inside a file that already exists, leaving every other byte alone — the tool to reach for whenever you are modifying rather than creating. write_file takes the FULL content, so using it to change a heading on an 80 KB page means reproducing 80 KB exactly, and one character wrong in that reproduction is a corruption that surfaces when a visitor loads the page, not when the tool returns. oldString must match the file exactly (whitespace included) and appear ONCE — include a line above and below to make it unique, or pass replaceAll. newString may be empty to delete the passage. The read-modify-write happens server-side in one request, so two edits cannot interleave. Nothing is saved if the result would not parse. The reply carries the file's sha256, so you can prove what the server now holds.

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": {
      "workspaceId": "<workspaceId>",
      "name": "<name>",
      "oldString": "<oldString>",
      "newString": "<newString>"
    },
    "name": "edit_file"
  }
}

Input Schema

NameRequiredDescriptionDefault
seoNoHow much to report about the HTML pages being written: "full" (default) everything, "minimal" only what an indexed page cannot do without, "none" to say nothing. Never blocks the write; a page with <meta name="robots" content="noindex"> is exempt either way.
nameYesCase-sensitive file name, folders with "/" — e.g. "pages/app.css", "lib/http.js".
newStringYesWhat to put in its place. Empty string deletes the passage.
oldStringYesThe exact text to replace, whitespace included. Must appear exactly once unless replaceAll is true.
replaceAllNoReplace every occurrence instead of requiring a unique match.
workspaceIdYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.53.0

TDQS

A4.8/5.0
Behavior5/5

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

With no annotations provided, the description carries the full burden and does so: it discloses server-side atomic read-modify-write ('two edits cannot interleave'), parse-gated saving ('Nothing is saved if the result would not parse'), and the sha256 in the reply as proof of server state. These are non-obvious behavioral guarantees an agent cannot infer from any structured field.

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 the core purpose and the sibling contrast, then parameters, then guarantees — a sensible order with no filler sentences. It is on the long side and includes some rhetorical framing ('one character wrong in that reproduction is a corruption'), which is persuasive rather than purely informational, costing a point on tightness.

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 6-parameter mutation tool with no annotations and no output schema, the description covers the things an agent would otherwise guess wrong: uniqueness semantics, deletion via empty string, atomicity, validation failure behavior, and confirmation of returned state. The remaining parameters are well covered by schema descriptions.

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 83%, so the baseline is 3, and the description earns an increment by adding operational meaning: oldString must match byte-for-byte including whitespace and appear exactly once, with the practical remedy of including a line above and below, or passing replaceAll. It does not touch workspaceId, name, or the seo enum, which remain schema-only.

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 ('Replaces ONE passage inside a file that already exists') and immediately draws the boundary against the sibling write_file. The capitalized ONE and 'leaving every other byte alone' tell an agent exactly what class of operation this is without opening the schema.

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 routes the agent: use this 'whenever you are modifying rather than creating,' and names write_file as the alternative with the concrete cost of choosing wrong (reproducing 80 KB, corruption surfacing at page load rather than tool return). It also covers the delete case via empty newString and the non-unique case via replaceAll.

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