Skip to main content
Glama
nuncaeslupus

doc-control

by nuncaeslupus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

field_update

Recompute and update stale TOC, PAGE, NUMPAGES, SEQ, and REF/PAGEREF field results in a .docx as tracked changes. Preview changes with dry_run.

Instructions

Recompute the body's TOC, PAGE, NUMPAGES, SEQ and REF/PAGEREF results with headless LibreOffice and write only those result runs, as tracked changes (old result struck, new inserted). Needs LibreOffice (soffice): without it, ENGINE_UNAVAILABLE names the stale fields; set_update_on_open instead sets w:updateFields so Word updates them on opening. Citations are never changed; INDEX, SECTIONPAGES, SECTION, NOTEREF and unresolvable REFs are left and listed under skipped. Run after toc.insert, caption.add or xref.add. Backed up and undoable; dry_run previews; slow (seconds).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
docYesPath to the .docx.
tagNoAppended to the author.
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.
set_update_on_openNoOnly set w:updateFields in settings.xml (no LibreOffice).

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": {
+        "author": {
+          "description": "Revision author stamped on the changes.",
+          "type": "string"
+        },
+        "backup": {
+          "description": "Path of the backup taken before the write.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "changed": {
+          "description": "set_update_on_open: whether the setting changed.",
+          "type": "boolean"
+        },
+        "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"
+          ]
+        },
+        "revision_ids": {
+          "description": "w:id of every revision this write created.",
+          "items": {
+            "type": [
+              "integer",
+              "string"
+            ]
+          },
+          "type": "array"
+        },
+        "set_update_on_open": {
+          "description": "True when w:updateFields was set instead.",
+          "type": "boolean"
+        },
+        "sha256": {
+          "description": "sha256 of the file after the write (pass as expect.sha256 next).",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "skipped": {
+          "description": "Fields left as they are, with why: SECTIONPAGES, SECTION and NOTEREF (LibreOffice keeps their cached results), every INDEX (rebuild it in Word, F9), a REF that resolves to an error or to nothing, and fields not paired with LibreOffice's.",
+          "items": {
+            "description": "A skipped field.",
+            "properties": {
+              "at": {
+                "description": "Its address.",
+                "type": "string"
+              },
+              "reason": {
+                "description": "Why it was not recomputed.",
+                "type": "string"
+              },
+              "type": {
+                "description": "Field type.",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "unchanged": {
+          "description": "Fields whose result was already right.",
+          "type": "integer"
+        },
+        "updated": {
+          "description": "Fields whose result changed.",
+          "items": {
+            "description": "An updated field.",
+            "properties": {
+              "after": {
+                "description": "Result paragraphs after.",
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "at": {
+                "description": "Paragraph address, p<n>#<fingerprint> (story-prefixed in notes/headers).",
+                "type": "string"
+              },
+              "before": {
+                "description": "Result paragraphs before.",
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "code": {
+                "description": "Field code.",
+                "type": "string"
+              },
+              "type": {
+                "description": "Field type (TOC, PAGE, REF...).",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "written": {
+          "description": "Whether the document was written.",
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "dry_run",
+        "updated",
+        "skipped",
+        "footprint"
+      ],
+      "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.8/5.0
Behavior5/5

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

Goes well beyond the annotations: it discloses which fields are rewritten, that citations are never changed, the exact 'skipped' set (INDEX, SECTIONPAGES, SECTION, NOTEREF, unresolvable REFs), the ENGINE_UNAVAILABLE failure mode, that it is backed up and undoable, and that it is slow. Annotations only supply the safety profile.

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?

It is dense but front-loaded, leading with the recompute action and its scope, with zero filler sentences. The single-block layout without sub-structure costs it a point but nothing is wasted.

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 mutation tool with several optional params and an output schema, everything an agent needs is present: prerequisites, ordering, alternatives, error semantics, performance expectation, and the skipped-field contract. No reliance on return-value explanation is needed since an output schema exists.

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. The description adds value by framing set_update_on_open as a cheap alternative to the full recompute and by tying dry_run and error codes to behavior, rather than merely restating field names.

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 ('Recompute ... results') and an exact resource set (TOC, PAGE, NUMPAGES, SEQ, REF/PAGEREF), and names the write behavior (tracked changes). An agent can tell this apart from field_list, toc_insert, and xref_add 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?

Gives explicit ordering ('Run after toc.insert, caption.add or xref.add') and a named alternative path ('set_update_on_open instead sets w:updateFields so Word updates them on opening'), plus the prerequisite (needs soffice). This is when-to-use, when-not, and alternative all in one.

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