EMET

patch_doc

Destructive

Replace one exact text match in a document without resending the whole file. Ideal for small edits to large files, rejecting zero or multiple matches instead of guessing.

Instructions

Replace one exact substring in a document (str_replace semantics) without resending the whole file. THE PREFERRED WAY TO MAKE SMALL EDITS to large docs like STATE.md. old_str must match EXACTLY ONCE - zero or multiple matches are rejected rather than guessed. Pass new_str as an empty string to delete. Same versioning, archiving, and sha256 read-back as write_doc.

Input Schema

TableJSON Schema

Name	Required	Description
`edits`	No	Several replacements in one revision. Each old_str must match the current text exactly once. Applied together, so a failed edit writes nothing.
`doc_id`	Yes
`origin`	No	Required when a board edit adds a row id. Names the session, chat or drop the row came from.
`reason`	Yes	Required, at least 10 characters. A removed or closed board row says why.
`source`	No	Source tag - which host produced this write. One name on every write since 2026-09-27.
`new_str`	No	Replacement text. Empty string deletes the matched text.
`old_str`	No	Exact text to replace. Must occur exactly once in the current text. Omit when `edits` is set.
`exchange`	No	The exchange (turn) this write belongs to, counting from 1. A write for exchange n while exchange n-1 was never appended is refused by the session graph until n-1 is appended.
`session_id`	No	Transcript session id. The floor is measured from the size when this session first touched the document.
`updated_by`	No	Alias of `source` (the older name, kept one release). Prefer `source`.
`expected_version`	No	Optional optimistic-concurrency guard.

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedv0.2.2Oct 5, 2026

addedInput schema / properties / edits

Added value: +{
+  "description": "Several replacements in one revision. Each old_str must match the current text exactly once. Applied together, so a failed edit writes nothing.",
+  "items": {
+    "type": "object"
+  },
+  "type": "array"
+}

changedInput schema / properties / exchange / description

Previous value: -"The exchange (turn) this write belongs to, counting from 1. A write for exchange n while exchange n-1 was never appended is flagged by the session graph."New value: +"The exchange (turn) this write belongs to, counting from 1. A write for exchange n while exchange n-1 was never appended is refused by the session graph until n-1 is appended."

changedInput schema / properties / old_str / description

Previous value: -"Exact text to replace. Must occur exactly once - include surrounding context to disambiguate."New value: +"Exact text to replace. Must occur exactly once in the current text. Omit when `edits` is set."

addedInput schema / properties / origin

Added value: +{
+  "description": "Required when a board edit adds a row id. Names the session, chat or drop the row came from.",
+  "type": "string"
+}

addedInput schema / properties / reason

Added value: +{
+  "description": "Required, at least 10 characters. A removed or closed board row says why.",
+  "type": "string"
+}

changedInput schema / properties / session_id / description

Previous value: -"Your transcript session id from emet_session_open. The session graph reads this session's state before the write and returns `session_graph.next` - the next step."New value: +"Transcript session id. The floor is measured from the size when this session first touched the document."

changedInput schema / required

Previous value: -[
-  "doc_id",
-  "old_str",
-  "new_str"
-]New value: +[
+  "doc_id",
+  "reason"
+]

First observedv0.1.0Oct 3, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true and non-idempotent, so the mutation profile is known. The description adds genuinely useful behavior beyond that: exact-once match enforcement with ambiguous matches rejected rather than guessed, empty new_str as delete, and parity with write_doc's versioning/archiving/sha256 read-back. It does not discuss permissions or what a failed multi-edit leaves behind (that detail lives in the schema).

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 tight sentences, front-loaded with the operation and its mechanism, then preference guidance, then the critical exact-match constraint, then delete behavior and parity guarantees. No filler and each sentence carries distinct information.

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 an 11-parameter mutation tool with no output schema, the description covers the core mental model (substring replacement, ambiguity rejection, delete, versioning parity) and the schema carries the remaining parameters at 91% coverage. It omits any narrative about the session/exchange graph constraints and batch-edit atomicity, which are only in schema text, but nothing essential to invoking it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 91%, so the schema already documents nearly every parameter including the edits array, origin, reason, exchange and expected_version. The description only restates old_str/new_str semantics already present in the schema, adding no syntax, format, or constraint detail beyond it. Baseline 3 is appropriate.

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?

Names a specific verb+resource with its mechanism ('Replace one exact substring ... str_replace semantics') and explicitly distinguishes itself from the full-file alternative ('without resending the whole file'). An agent can tell this apart from write_doc and revise_memory from the first sentence alone.

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?

Gives clear selection context: 'THE PREFERRED WAY TO MAKE SMALL EDITS to large docs like STATE.md' implicitly routes full rewrites to write_doc. It stops short of naming write_doc explicitly or stating when-not to use patching (e.g. multi-region rewrites), so it is clear but not fully exclusionary.

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

patch_doc

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools