doc-control

Overview Schema Source Related Servers Discussions Admin

text_replace

Replace a text range in a .docx with new content as a tracked change by default, or delete it with empty text; ranges come from text.find or para.get.

Instructions

Replace one range with new text, as a tracked change: part of a paragraph (p3#a1b2c3d4:10-15, code-point offsets), a whole paragraph (p3#a1b2c3d4) or a span across paragraphs (p3#a1b2c3d4:10..p5#e5f6a7b8:2); empty text deletes it. Get ranges from text.find or para.get. File engine: backed up first, logged for history.undo, dry_run previews, expect.sha256 refuses a changed file. tracked: false writes plainly, on either engine. engine live edits the open app. STALE_ADDRESS if the paragraph changed since read. Use term.rename for a name everywhere, doc.batch for several edits.

Input Schema

TableJSON Schema

Name	Required	Description
`at`	Yes	Range p3#fp:10-15, p3#fp or p3#fp:10..p5#fp:2.
`doc`	Yes	Path to the .docx (live: or the file name of one open in a live app).
`tag`	No	Appended to the author.
`text`	Yes	New text; empty deletes the range.
`author`	No	Revision author.
`engine`	No	`live` edits the document open in Word or LibreOffice (see live.open).
`expect`	No	Write guard: the sha256 read earlier (doc.info, or a reply's doc.sha256), e.g. {"sha256": "9f86d081…"}; a file changed since is DOC_CHANGED_ON_DISK.
`dry_run`	No	Preview only; write nothing.
`tracked`	No	true (default): edits are tracked changes. false: a plain write, for a change the writer already approved: built as the tracked edit, then this call's own revisions are accepted in the same verified write (no revision marks; the log has it, and undo takes it back from the backup, only while the document is exactly as the write left it: no out-of-order undo). Refused (UNSUPPORTED_CONTENT) when a paragraph it rewrites holds another unresolved tracked change. Text, paragraph and style/format edits only (refused with revision, row and comment operations). engine live: the app's change tracking is off for the edit and put back after; text.replace and para.insert, refused (UNSUPPORTED_CONTENT) next to another unresolved tracked change; the app's undo takes it back. A plain edit inside a tracked-inserted table row is allowed: rejecting that row later removes the plain text too.

Output Schema

TableJSON Schema

Name	Required	Description
`ok`	Yes	Always true on success.
`op`	Yes	The operation that ran.
`api`	Yes	API version (1.0).
`doc`	No	The document read or written: path, sha256 and paragraph count.
`next`	Yes	Cursor for the next page (pass as cursor), or null.
`result`	Yes	What the operation returns.
`warnings`	Yes	Things to know about the result.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.7.2Oct 15, 2026

addedInput schema / properties / expect / description

Added value: +"Write guard: the sha256 read earlier (doc.info, or a reply's doc.sha256), e.g. {\"sha256\": \"9f86d081…\"}; a file changed since is DOC_CHANGED_ON_DISK."

changedInput schema / properties / tracked / description

Previous value: -"true (default): edits are tracked changes. false: a plain write, for a change the writer already approved: built as the tracked edit, then this call's own revisions are accepted in the same verified write (no revision marks; the log has it, and undo takes it back from the backup, only while the document is exactly as the write left it: no out-of-order undo). Refused (UNSUPPORTED_CONTENT) when a paragraph it rewrites holds another unresolved tracked change. Text, paragraph and style/format edits only (refused with revision, row and comment operations); file engine only for now. A plain edit inside a tracked-inserted table row is allowed: rejecting that row later removes the plain text too."New value: +"true (default): edits are tracked changes. false: a plain write, for a change the writer already approved: built as the tracked edit, then this call's own revisions are accepted in the same verified write (no revision marks; the log has it, and undo takes it back from the backup, only while the document is exactly as the write left it: no out-of-order undo). Refused (UNSUPPORTED_CONTENT) when a paragraph it rewrites holds another unresolved tracked change. Text, paragraph and style/format edits only (refused with revision, row and comment operations). engine live: the app's change tracking is off for the edit and put back after; text.replace and para.insert, refused (UNSUPPORTED_CONTENT) next to another unresolved tracked change; the app's undo takes it back. A plain edit inside a tracked-inserted table row is allowed: rejecting that row later removes the plain text too."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "api": {
+      "description": "API version (1.0).",
+      "type": "string"
+    },
+    "doc": {
+      "description": "The document read or written: path, sha256 and paragraph count.",
+      "properties": {
+        "characters": {
+          "description": "text.normalize of a text string: its length.",
+          "type": "integer"
+        },
+        "paragraphs": {
+          "description": "Body paragraphs.",
+          "type": "integer"
+        },
+        "path": {
+          "description": "Path of the document.",
+          "type": "string"
+        },
+        "sha256": {
+          "description": "sha256 of the file (pass as expect.sha256 to a write).",
+          "type": "string"
+        },
+        "source": {
+          "description": "A .txt/.md/.odt source's format, encoding and split mode; \"text\" for a text string (text.normalize).",
+          "type": [
+            "object",
+            "string"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "next": {
+      "description": "Cursor for the next page (pass as cursor), or null.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "ok": {
+      "description": "Always true on success.",
+      "type": "boolean"
+    },
+    "op": {
+      "description": "The operation that ran.",
+      "type": "string"
+    },
+    "result": {
+      "description": "What the operation returns.",
+      "properties": {
+        "address_map": {
+          "description": "Old address -> new address of every paragraph whose address changed.",
+          "type": "object"
+        },
+        "applied": {
+          "description": "Edits applied (1).",
+          "type": "integer"
+        },
+        "author": {
+          "description": "Revision author stamped on the changes.",
+          "type": "string"
+        },
+        "backup": {
+          "description": "Path of the backup taken before the write.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "date": {
+          "description": "Revision date (UTC, ISO 8601).",
+          "type": "string"
+        },
+        "dry_run": {
+          "description": "True when nothing was written (a preview).",
+          "type": "boolean"
+        },
+        "engine": {
+          "description": "live: edited in the open app; nothing backed up or verified.",
+          "type": "string"
+        },
+        "footprint": {
+          "description": "Part name -> the paragraphs or items it touched in that part.",
+          "type": "object"
+        },
+        "op_id": {
+          "description": "Undo-log id of this write (history.undo / history.restore).",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "op_ids": {
+          "description": "Live: one log entry per edit, in request order.",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "preview": {
+          "description": "One entry per edit: what changes where.",
+          "items": {
+            "description": "A previewed edit.",
+            "properties": {
+              "action": {
+                "description": "accept or reject (revision kinds).",
+                "type": "string"
+              },
+              "after": {
+                "description": "Text after.",
+                "type": "string"
+              },
+              "at": {
+                "description": "Where it applies.",
+                "type": "string"
+              },
+              "before": {
+                "description": "Text before.",
+                "type": "string"
+              },
+              "op": {
+                "description": "Index of the edit in ops.",
+                "type": "integer"
+              },
+              "revisions": {
+                "description": "Revisions it resolves (revision kinds).",
+                "type": "integer"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "revision_ids": {
+          "description": "w:id of every revision this write created.",
+          "items": {
+            "type": [
+              "integer",
+              "string"
+            ]
+          },
+          "type": "array"
+        },
+        "sha256": {
+          "description": "sha256 of the file after the write (pass as expect.sha256 next).",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "tracked": {
+          "description": "False for a plain (untracked) write.",
+          "type": "boolean"
+        },
+        "warnings": {
+          "description": "Notes on what the write could not do as asked.",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "applied"
+      ],
+      "type": "object"
+    },
+    "warnings": {
+      "description": "Things to know about the result.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "api",
+    "ok",
+    "op",
+    "result",
+    "warnings",
+    "next"
+  ],
+  "type": "object"
+}

Addedv0.1.3Oct 15, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only declare the generic safety triple, so the description carries real weight and delivers: file engine backs up first, logs for history.undo, dry_run previews, expect.sha256 refuses a changed file, STALE_ADDRESS on stale paragraphs, DOC_CHANGED_ON_DISK, and the full tracked:false accept-as-you-write semantics. Deletion via empty text is disclosed, which is consistent with destructiveHint=false because everything is backed up and undoable.

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?

Purpose is front-loaded and nearly every clause carries distinct operational information (guards, errors, engine behavior, alternatives). It is, however, a dense semicolon-chained run-on that packs many independent facts into single sentences, which costs a little scannability despite the high information density.

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?

An output schema exists, so return values need not be explained. For a 9-parameter mutation tool with nested objects, the description still covers engines, guards, error conditions, staleness, and sibling alternatives, so an agent has everything needed to call it correctly.

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 is 3, but the description adds cross-parameter meaning the schema does not: 'empty `text` deletes it', the interaction of tracked:false with engine live, and the alternate range syntaxes for `at`. It stops short of fully restating each field, which is fine given the schema already documents them.

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 precise verb+resource ('Replace one range with new text, as a tracked change') and enumerates the addressable range forms (sub-paragraph offsets, whole paragraph, cross-paragraph span). It also names the sibling tools it is not (term.rename, doc.batch), so an agent can differentiate it without opening any 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?

Explicitly routes the agent: 'Get ranges from text.find or para.get' for obtaining inputs, and 'Use term.rename for a name everywhere, doc.batch for several edits' as alternatives. When-to-use and when-to-use-something-else are both stated, leaving nothing to inference.

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

Deploy Server