Venira

Overview Schema Source Related Servers Discussions Admin

Edit batch

project_edit_batch

Apply edits across multiple files atomically: if any edit fails, roll back all touched files and skip remaining changes. Use for multi-file changes that must fully succeed or not apply.

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 (project_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": "project_edit_batch"
  }
}

Input Schema

Name	Required	Description	Default
`edits`	Yes	edit_file argument objects (typed like project_edit_file). Unknown fields are rejected with a did-you-mean hint and nothing is applied. Snapshot first when later checks may need a full rollback; automatic rollback covers in-batch failures only.
`max_response_bytes_per_item`	No	Max serialized bytes per edit item (default 1 MiB).

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv1.21.0Nov 10, 2026

changedInput schema / properties / edits / description

Previous value: -"Array of edit_file arguments. For existing files across multiple edits, create a scoped project_snapshot first if later validation may require full rollback; automatic rollback only handles in-batch failures."New value: +"edit_file argument objects (typed like project_edit_file). Unknown fields are rejected with a did-you-mean hint and nothing is applied. Snapshot first when later checks may need a full rollback; automatic rollback covers in-batch failures only."

addedInput schema / properties / edits / items / properties

Added value: +{
+  "edits": {
+    "description": "Several replacements in this file; wins over old_text/new_text.",
+    "items": {
+      "properties": {
+        "new_text": {
+          "description": "Replacement text.",
+          "type": "string"
+        },
+        "old_text": {
+          "description": "Exact text to replace.",
+          "minLength": 1,
+          "type": "string"
+        },
+        "replace_all": {
+          "description": "1 replaces every match; 0 (default) requires exactly one match.",
+          "maximum": 1,
+          "minimum": 0,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "old_text",
+        "new_text",
+        "replace_all"
+      ],
+      "type": "object"
+    },
+    "maxItems": 64,
+    "type": "array"
+  },
+  "expected_sha256": {
+    "description": "Hex SHA-256 of the current full content; edit refused if it differs; when given, the result also reports verified.",
+    "type": "string"
+  },
+  "new_text": {
+    "description": "Replacement text (see project_edit_file).",
+    "type": "string"
+  },
+  "old_text": {
+    "description": "Exact text to replace (see project_edit_file).",
+    "minLength": 1,
+    "type": "string"
+  },
+  "reason": {
+    "description": "Optional why (max 400 chars), audit-logged. Required only on project_ci_control.",
+    "maxLength": 400,
+    "type": "string"
+  },
+  "relative_path": {
+    "description": "File to edit (required per item).",
+    "type": "string"
+  },
+  "replace_all": {
+    "description": "1 replaces every match; 0 (default) requires exactly one match.",
+    "maximum": 1,
+    "minimum": 0,
+    "type": "integer"
+  }
+}

removedInput schema / properties / edits / items / propertyNames
```
Removed value: -{
-  "type": "string"
-}
```
addedInput schema / properties / edits / items / required
```
Added value: +[
+  "relative_path"
+]
```
addedInput schema / properties / max_response_bytes_per_item / description
```
Added value: +"Max serialized bytes per edit item (default 1 MiB)."
```

Changed1 schema field changedv1.17.1Nov 7, 2026

changedInput schema / properties / edits / description

Previous value: -"Array of edit_file argument objects. The batch aborts on the first failure and rolls back earlier writes when possible."New value: +"Array of edit_file arguments. For existing files across multiple edits, create a scoped project_snapshot first if later validation may require full rollback; automatic rollback only handles in-batch failures."

Addedv1.13.0Nov 2, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations only declare the generic safety profile (readOnly=false, destructive=false, idempotent=false); the description adds substantive behavior beyond that: first failure rolls back every touched file from an automatic snapshot, remaining edits are skipped, and the snapshot_id is returned. It also scopes the guarantee precisely — automatic rollback covers in-batch failures only — which is exactly the kind of caveat annotations cannot express.

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?

Front-loads the core guarantee, then gives usage, exclusion, and output in clearly separated labeled lines. Every sentence carries non-redundant information; the dense output line is justified because there is no output schema.

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?

Covers purpose, when/when-not, failure and rollback semantics, and both success and failure response shapes, which compensates for the absence of an output schema. Nothing an agent needs in order to invoke it correctly is missing.

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 the baseline would be 3; the description adds value by declaring each array item is typed like project_edit_file arguments (relative_path, old_text, new_text, ...), which lets the agent reuse knowledge of the sibling's parameter shape. It does not mention max_response_bytes_per_item, but the schema documents that fully.

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 ('apply edits across one or more files') plus the defining semantic: 'all-or-nothing'. It explicitly contrasts with the sibling project_edit_file, so an agent can distinguish the two without opening either 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?

Provides an explicit 'Use when' condition (change spans several files/sections and must land completely or not at all) and an explicit 'Avoid when' naming the alternative (project_edit_file). Both the selection and the exclusion are stated, not inferred.

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