Skip to main content
Glama

batch_edit

Destructive

Apply multiple replace_text and insert_paragraph edits to a DOCX or ODT file in one validated call; conflicts are rejected before changes, and applied steps emit tracked changes.

Instructions

Single-agent front door for applying multiple edit steps (replace_text, insert_paragraph) to a document in one call. Validates all steps first, rejects conflicts before applying anything, then executes valid steps sequentially. Two source-proven bonded heading/body insertions may share an anchor and position when both declare the same bonded_pair_id and distinct style_source_id values; unrelated same-slot inserts remain conflicts. Accepts inline steps or a plan_file_path JSON array. Surface: revisionable — every applied step emits native OOXML tracked changes.

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": {
      "file_path": "<file_path>"
    },
    "name": "batch_edit"
  }
}

Input Schema

NameRequiredDescriptionDefault
stepsNoJSON array of edit steps. Each step needs step_id, operation, and operation-specific fields.
file_pathYesPath to the DOCX or ODT file.
plan_file_pathNoPath to a .json file containing an array of edit steps. Mutually exclusive with steps.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.12.1

TDQS

A4.5/5.0
Behavior5/5

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

Goes well beyond the annotations by disclosing the execution model: all steps are validated first, conflicts abort before anything is applied, and valid steps then run sequentially — critical atomicity information the destructiveHint alone does not convey. It also explains the tracked-changes surface ('revisionable', native OOXML), which tells the agent edits are recorded rather than silently overwritten, and documents the non-obvious bonded_pair_id exception to the same-slot conflict rule.

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 purpose, then validation behavior, then the conflict rule, then the input modes and tracking surface — a logical order with little redundancy. The bonded-pair sentence is dense and requires careful parsing, but it encodes a rule that cannot be shortened without losing meaning.

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 destructive multi-step mutation with no output schema, the description covers validation, conflict rejection, sequential execution, and tracking adequately. The remaining gap is the shape of the result — whether it reports per-step success/failure or partial application details — which is unavailable elsewhere since no output schema exists.

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 parameter basics are already documented; the description adds real semantic value by explaining the steps/plan_file_path mutual exclusivity and by defining the bonded_pair_id + distinct style_source_id condition under which same-anchor inserts are allowed. The actual per-step operation fields remain free-form with no property-level definition in either place.

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 — applying multiple edit steps (replace_text, insert_paragraph) to a document in one call — and explicitly positions itself as the batch 'front door' relative to those single-operation siblings. An agent can tell this apart from calling replace_text or insert_paragraph individually without opening another schema.

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?

Clearly establishes the context of use: multiple edit steps applied atomically in one call, with an inline-vs-plan_file_path choice described as mutually exclusive. It does not, however, explicitly say when to prefer individual replace_text/insert_paragraph calls over batching, or when a plan file is preferable to inline steps.

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