Skip to main content
Glama

Edit batch

edit_batch

Apply multiple file edits atomically, rolling back every changed file if any edit fails so multi-file changes land completely or not at all.

Instructions

Apply edits across one or more files all-or-nothing. Each item takes edit_file arguments (relative_path, old_text, new_text, ...). The first failure rolls back every touched file from an automatic snapshot and skips the rest. Use when: a change spans several files or sections and must land completely or not at all. Avoid when: you make one edit (edit_file). Output: success: per-edit {relative_path, replacements, sha256_after}. Failure: ok=false, error batch_failed, data {executed, skipped, rollback_succeeded, snapshot_id}.

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

Input Schema

NameRequiredDescriptionDefault
editsYesedit_file argument objects (typed like edit_file). Unknown fields are rejected with a did-you-mean hint and nothing is applied.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changedv4.5.0
    • removedInput schema / properties / edits / items / properties / edits / items / properties / replace_all / anyOf
      Removed value: -[
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "maximum": 1,
      -    "minimum": 0,
      -    "type": "integer"
      -  }
      -]
    • changedInput schema / properties / edits / items / 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 / edits / items / properties / replace_all / maximum
      Removed value: -1
    • removedInput schema / properties / edits / items / properties / edits / items / properties / replace_all / minimum
      Removed value: -0
    • changedInput schema / properties / edits / items / properties / edits / items / properties / replace_all / type
      Previous value: -"integer"New value: +"boolean"
    • 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"
  2. Addedv4.0.0

TDQS

A4.9/5.0
Behavior5/5

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

Beyond the hints, the description discloses the failure semantics (first failure rolls back all touched files, remaining items skipped, rollback driven by an automatic snapshot) and spells out both success and failure response shapes including resume-relevant fields like retry indices. This is exactly the kind of context the terse hints cannot convey.

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?

Four short sentences, front-loaded with the atomicity guarantee, then labeled Use/Avoid/Output blocks. No restatement of the tool name or filler; every clause carries operational meaning.

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 batch mutation with no output schema, the description supplies the return contract (per-edit relative_path, replacements, sha256_after) and the failure contract (ok=false, error batch_failed, executed/skipped counts, rollback_succeeded, snapshot_id), so an agent knows what to report and how to recover.

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 per-field meaning is already documented; the description still adds the non-obvious fact that each array item is typed like edit_file's arguments, which explains the shape and why unknown fields are rejected. It adds orientation rather than new field-level detail.

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 first sentence states a specific verb and resource ('Apply edits across one or more files') plus the defining property ('all-or-nothing'), which is exactly what separates it from edit_file. An agent can classify the tool 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?

Explicit 'Use when' (a change spans several files/sections and must land completely or not at all) and 'Avoid when' (single edit -> edit_file) sections name the alternative and the condition that selects it. This is the strongest form of routing guidance.

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