Skip to main content
Glama
CoderDayton

Semantic Cache MCP

by CoderDayton
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Batch Edit

batch_edit

Apply many exact edits to one file atomically in a single call, returning precise results for each edit. Supports dry-run and range-based replacements, so you can retry only the failed changes.

Instructions

Apply many exact edits to one file in a single atomic call.

Preferred over repeated edit calls on the same file: one response, applied atomically, faster on large files. Partial success is allowed — any failed edits are returned with their reason so you can retry just the misses (status is edited when all apply, partial when some fail, no_changes when none do). A dry_run writes nothing and says so: the status becomes would_edit/would_partial and dry_run: true comes back with it. For edits across different files, call the tool once per file.

edits is a JSON array; each entry is one of:

  • [old, new] — exact find/replace.

  • [old, new, start_line, end_line] — find/replace confined to a range.

  • [null, new, start_line, end_line] — replace that line range wholesale.

  • {"old": ..., "new": ..., "start_line": ..., "end_line": ...} — object form.

Prefer line-range entries when you already have line numbers from read. Pass known_hash and the response carries a claimable content_hash, so no read is needed afterwards; without it, or with auto_format, you get file_hash instead.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pathYesFile path to modify (absolute, or relative to root).
editsYesJSON array of edit entries, in any of the forms above.
dry_runNoPreview without writing.
show_diffNoReturn the full diff even on a deterministic all-success batch.
known_hashNoThe `content_hash` from your last read of this file. Proves you hold the text being edited, so the result can be handed back as a claimable `content_hash`.
auto_formatNoRun the formatter after all edits.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.6.0
    • addedInput schema / properties / known_hash
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The `content_hash` from your last read of this file. Proves\nyou hold the text being edited, so the result can be handed back as\na claimable `content_hash`."
+}
    • changedOutput schema / (root)
      Previous value: -{
-  "properties": {
-    "content_hash": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Content Hash"
-    },
-    "diff": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Diff"
-    },
-    "diff_omitted": {
-      "anyOf": [
-        {
-          "type": "boolean"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Diff Omitted"
-    },
-    "diff_state": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Diff State"
-    },
-    "diff_stats": {
-      "anyOf": [
-        {
-          "additionalProperties": true,
-          "type": "object"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Diff Stats"
-    },
-    "failed": {
-      "anyOf": [
-        {
-          "type": "integer"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Failed"
-    },
-    "failures": {
-      "anyOf": [
-        {
-          "items": {
-            "properties": {
-              "error": {
-                "anyOf": [
-                  {
-                    "type": "string"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "default": null,
-                "title": "Error"
-              },
-              "old": {
-                "anyOf": [
-                  {
-                    "type": "string"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "default": null,
-                "title": "Old"
-              },
-              "truncated": {
-                "anyOf": [
-                  {
-                    "type": "boolean"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "default": null,
-                "title": "Truncated"
-              }
-            },
-            "title": "BatchEditFailure",
-            "type": "object"
-          },
-          "type": "array"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Failures"
-    },
-    "from_cache": {
-      "anyOf": [
-        {
-          "type": "boolean"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "From Cache"
-    },
-    "outcomes": {
-      "anyOf": [
-        {
-          "items": {
-            "properties": {
-              "error": {
-                "anyOf": [
-                  {
-                    "type": "string"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "default": null,
-                "title": "Error"
-              },
-              "line_number": {
-                "anyOf": [
-                  {
-                    "type": "integer"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "default": null,
-                "title": "Line Number"
-              },
-              "new": {
-                "anyOf": [
-                  {
-                    "type": "string"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "default": null,
-                "title": "New"
-              },
-              "old": {
-                "anyOf": [
-                  {
-                    "type": "string"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "default": null,
-                "title": "Old"
-              },
-              "success": {
-                "anyOf": [
-                  {
-                    "type": "boolean"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "default": null,
-                "title": "Success"
-              },
-              "truncated": {
-                "anyOf": [
-                  {
-                    "type": "boolean"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "default": null,
-                "title": "Truncated"
-              }
-            },
-            "title": "BatchEditOutcome",
-            "type": "object"
-          },
-          "type": "array"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Outcomes"
-    },
-    "params": {
-      "anyOf": [
-        {
-          "properties": {
-            "auto_format": {
-              "anyOf": [
-                {
-                  "type": "boolean"
-                },
-                {
-                  "type": "null"
-                }
-              ],
-              "default": null,
-              "title": "Auto Format"
-            },
-            "dry_run": {
-              "anyOf": [
-                {
-                  "type": "boolean"
-                },
-                {
-                  "type": "null"
-                }
-              ],
-              "default": null,
-              "title": "Dry Run"
-            },
-            "show_diff": {
-              "anyOf": [
-                {
-                  "type": "boolean"
-                },
-                {
-                  "type": "null"
-                }
-              ],
-              "default": null,
-              "title": "Show Diff"
-            },
-            "truncated": {
-              "anyOf": [
-                {
-                  "type": "boolean"
-                },
-                {
-                  "type": "null"
-                }
-              ],
-              "default": null,
-              "title": "Truncated"
-            }
-          },
-          "title": "BatchEditParams",
-          "type": "object"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null
-    },
-    "path": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Path"
-    },
-    "status": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Status"
-    },
-    "succeeded": {
-      "anyOf": [
-        {
-          "type": "integer"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Succeeded"
-    },
-    "tokens_saved": {
-      "anyOf": [
-        {
-          "type": "integer"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Tokens Saved"
-    },
-    "truncated": {
-      "anyOf": [
-        {
-          "type": "boolean"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Truncated"
-    }
-  },
-  "title": "BatchEditResponse",
-  "type": "object"
-}New value: +null
  2. Changed5 schema fields changedv0.5.1
    • addedInput schema / properties / auto_format / description
      Added value: +"Run the formatter after all edits."
    • addedInput schema / properties / dry_run / description
      Added value: +"Preview without writing."
    • addedInput schema / properties / edits / description
      Added value: +"JSON array of edit entries, in any of the forms above."
    • addedInput schema / properties / path / description
      Added value: +"File path to modify (absolute, or relative to root)."
    • addedInput schema / properties / show_diff / description
      Added value: +"Return the full diff even on a deterministic all-success batch."
  3. Addedv0.4.5

TDQS

A5/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 thoroughly. It discloses atomic application semantics, partial success behavior, status values (`edited`, `partial`, `no_changes`), dry-run behavior (`would_edit`/`would_partial` and `dry_run: true`), and hash-handling behavior (`content_hash` vs `file_hash`).

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?

The description is dense but every sentence earns its place. It front-loads the core purpose and usage preference, then covers edit formats, status outcomes, dry-run behavior, and hash semantics without redundant fluff.

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 complex tool with 6 parameters, no annotations, and no output schema, the description is remarkably complete. It covers invocation context, input formats, failure behavior, return-status semantics, and post-call hash handling, leaving little ambiguity for an agent.

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 the input schema already covers 100% of parameters, the description adds meaningful semantics beyond the schema: it documents the JSON array forms for `edits`, explains the line-range variants, and clarifies how `known_hash`, `content_hash`, and `file_hash` interact. This significantly helps an agent construct valid calls.

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 description opens with a specific verb and resource: 'Apply many exact edits to one file in a single atomic call.' It also distinguishes the tool from repeated `edit` calls, making its purpose and scope immediately clear.

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?

The description explicitly states when to prefer this tool over repeated `edit` calls, when to use it once per file for cross-file edits, and when to prefer line-range entries based on existing `read` data. This gives the agent actionable routing criteria.

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