Skip to main content
Glama
nuncaeslupus

doc-control

by nuncaeslupus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

revision_reject

Reject tracked changes in a Word .docx by ID, author, paragraph, run, or all — removing insertions and restoring deletions, with optional dry-run preview.

Instructions

Reject tracked changes, undoing them in the text (insertions removed, deletions restored): by ids (from revision.list), by revision author, in a paragraph or run (at, p3#a1b2c3d4..p9#e5f6a7b8), or all. Not itself a tracked change: on the file engine the file is backed up first and the write is logged for history.undo; dry_run previews counts; expect.sha256 refuses a changed file. Use revision.accept to keep changes instead, doc.batch to accept and reject in one write. Returns counts and the revisions resolved.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
atNoParagraph p3#fp or run p3#fp..p9#fp.
allNotrue: every revision in the document.
docYesPath to the .docx (live: or the file name of one open in a live app).
idsNoReject the revisions with these ids (from revision.list).
authorNoExact revision author.
expectNoWrite 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_runNoPreview only; write nothing.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
okYesAlways true on success.
opYesThe operation that ran.
apiYesAPI version (1.0).
docNoThe document read or written: path, sha256 and paragraph count.
nextYesCursor for the next page (pass as cursor), or null.
resultYesWhat the operation returns.
warningsYesThings to know about the result.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.7.2
    • 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."
    • 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": {
+        "accepted": {
+          "description": "Revisions accepted.",
+          "type": "integer"
+        },
+        "address_map": {
+          "description": "Old address -> new address of every paragraph whose address changed.",
+          "type": "object"
+        },
+        "applied": {
+          "description": "Edits applied (a count), or for style kinds one entry per style op.",
+          "type": [
+            "integer",
+            "array"
+          ]
+        },
+        "backup": {
+          "description": "Path of the backup taken before the write.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "dry_run": {
+          "description": "True when nothing was written (a preview).",
+          "type": "boolean"
+        },
+        "footprint": {
+          "description": "Part name -> the paragraphs or items it touched in that part.",
+          "type": "object"
+        },
+        "merged_paragraphs": {
+          "description": "Paragraphs joined by resolving paragraph marks.",
+          "type": "integer"
+        },
+        "op_id": {
+          "description": "Undo-log id of this write (history.undo / history.restore).",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "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"
+        },
+        "rejected": {
+          "description": "Revisions rejected.",
+          "type": "integer"
+        },
+        "revisions": {
+          "description": "The revisions resolved (capped; see revisions_omitted).",
+          "items": {
+            "description": "A resolved revision.",
+            "properties": {
+              "action": {
+                "description": "accept or reject.",
+                "type": "string"
+              },
+              "at": {
+                "description": "Paragraph address.",
+                "type": "string"
+              },
+              "author": {
+                "description": "Its author.",
+                "type": "string"
+              },
+              "id": {
+                "description": "Revision id.",
+                "type": "string"
+              },
+              "type": {
+                "description": "Revision type (insert, delete, mark_insert, format...).",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "revisions_omitted": {
+          "description": "Resolved revisions left out of the list.",
+          "type": "integer"
+        },
+        "sha256": {
+          "description": "sha256 of the file after the write (pass as expect.sha256 next).",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "warnings": {
+          "description": "Notes on what the write could not do as asked.",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "applied",
+        "dry_run"
+      ],
+      "type": "object"
+    },
+    "warnings": {
+      "description": "Things to know about the result.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "api",
+    "ok",
+    "op",
+    "result",
+    "warnings",
+    "next"
+  ],
+  "type": "object"
+}
  2. Addedv0.1.3

TDQS

A4.4/5.0
Behavior3/5

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

Annotations already declare the write/safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description is consistent with them by explaining why rejecting is non-destructive. It adds real context: backup on the file engine, history.undo logging, dry_run previewing counts, and expect.sha256 refusing a changed file. However, this is context beyond what annotations carry but not a complete behavioral picture (e.g. error cases beyond DOC_CHANGED_ON_DISK), so it sits at a solid 3–4; credit is given for the backup/logging disclosure.

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?

One dense paragraph that front-loads the core action and effect before listing selectors, guards, and alternatives. Every clause earns its place, though the packed parentheticals and clause stacking make it slightly heavier than ideal.

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 7-parameter mutation tool with an output schema, the description covers the action, all selection modes, the safety guards, the undo relationship, and alternatives. With the output schema present, return-value explanation ('returns counts and the revisions resolved') is a bonus rather than a gap.

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 description coverage is 100%, so the schema already documents every parameter, setting a baseline of 3. The description adds marginal value by tying `ids` to its source (revision.list) and giving a concrete `at` example range (p3#a1b2c3d4..p9#e5f6a7b8), which clarifies the address format beyond the schema's terse wording.

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 (reject tracked changes) plus the concrete effect (insertions removed, deletions restored), and immediately distinguishes itself from revision_accept. An agent can tell exactly what this does versus its nearest sibling without opening a 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?

Enumerates every selection mode (ids, author, at, all) and names the alternatives explicitly: revision.accept to keep changes, doc.batch to combine accept and reject in one write. The when-to-use and when-to-use-something-else routing is fully specified.

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