Skip to main content
Glama
Sign In
doc-control

doc-control

by nuncaeslupus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

table_row_insert

Insert a row into a Word body table as a tracked change, after a chosen row with one value per cell. Preview with dry_run and use SHA-256 guards to refuse stale-file edits.

Instructions

Insert a row into a body table as a tracked change: after row after_row (0: before the first), with one text per cell in cells (e.g. ["2024", "12.5"]), matching the row it follows (SCHEMA_INVALID otherwise). Refused (UNSUPPORTED_CONTENT) between two rows a vertical merge spans. Backed up and logged for history.undo; dry_run previews; expect.sha256 refuses a changed file. Use doc.batch for several rows at once.

Input Schema

NameRequiredDescriptionDefault
docYesPath to the .docx.
tagNoAppended to the author.
cellsYesOne text per cell of the row it follows (the first row for after_row 0); a horizontally merged cell is one cell.
tableYesTable number as `table.get` numbers it: 1-based, in document order, main story only (a table in a note, header or footer cannot be named here).
authorNoRevision 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.
after_rowYesInsert after this row (1-based); 0 inserts before the first row.

Output 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": {
+        "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"
+          ]
+        },
+        "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"
+        },
+        "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"
+          ]
+        },
+        "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"
+          ]
+        },
+        "warnings": {
+          "description": "Notes on what the write could not do as asked.",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "applied",
+        "dry_run",
+        "preview",
+        "address_map",
+        "footprint",
+        "revision_ids"
+      ],
+      "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. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only declare readOnly/destructive/openWorld hints; the description goes well beyond them by disclosing the tracked-change nature, specific error outcomes (SCHEMA_INVALID, UNSUPPORTED_CONTENT near vertical merges), that the change is backed up and logged for history.undo, and the dry_run/expect guard behaviors.

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 in the first clause, followed by error conditions and the batch alternative in one dense but well-ordered sentence. It is information-dense without padding, though the single run-on sentence is slightly heavy.

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?

With an output schema present, return values need no explanation. The description covers the mutation semantics, error codes, history/backup behavior, preview mode, write guard, and bulk alternative, which is complete for this 8-parameter tracked-change tool.

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 schema already documents parameters (baseline 3). The description adds a concrete cells example (["2024", "12.5"]), clarifies after_row 0 means before the first row, and explains the match-the-following-row rule, giving meaning beyond the raw schema.

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 ('Insert a row into a body table as a tracked change') and immediately scopes it with the insertion position and cell contract. It is clearly distinguishable from sibling table_row_delete and table_get 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 Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes bulk work to doc.batch ('Use doc.batch for several rows at once') and notes dry_run for preview and expect.sha256 as a write guard. It lacks an explicit when-not condition, but the sibling routing and guard conditions give strong context.

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