doc-control

Overview Schema Source Related Servers Discussions Admin

xref_add

Insert a cross-reference field in a .docx that points to a caption or paragraph, with options for number, page, or text. Run field.update to fill the shown value.

Instructions

Insert a cross-reference field at an insertion point (at: p14#a1b2c3d4:20-20, or a paragraph address for its end), pointing to a caption or another body paragraph. show number (default: "Table 3" for a caption), page (a PAGEREF) or text. The target gets a hidden bookmark when it has none; run field.update afterwards to fill in the shown value. A tracked insertion; backed up and undoable (history.undo); dry_run previews. Add captions with caption.add first.

Input Schema

Name	Required	Description
`at`	Yes	Insertion point: p<n>#<fp>:<k>-<k>, or a paragraph address for its end.
`to`	Yes	Address of the caption or heading it points at.
`doc`	Yes	Path to the .docx.
`tag`	No	Appended to the author.
`show`	No	number (default): a caption's label and number, or a paragraph's number; page: the page it is on; text: the caption or paragraph text.
`author`	No	Revision author.
`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.

Output 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.

Changed2 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."

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": {
+        "at": {
+          "description": "Address of the paragraph that holds the field.",
+          "type": "string"
+        },
+        "author": {
+          "description": "Revision author stamped on the changes.",
+          "type": "string"
+        },
+        "backup": {
+          "description": "Path of the backup taken before the write.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "bookmark": {
+          "description": "The target's bookmark.",
+          "type": "string"
+        },
+        "code": {
+          "description": "The field code, e.g. REF _Ref100000001 \\h.",
+          "type": "string"
+        },
+        "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"
+        },
+        "sha256": {
+          "description": "sha256 of the file after the write (pass as expect.sha256 next).",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "show": {
+          "description": "number, page or text.",
+          "type": "string"
+        },
+        "to": {
+          "description": "Address of the target paragraph.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "dry_run",
+        "at",
+        "to",
+        "show",
+        "code",
+        "bookmark",
+        "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"
+}

First observedv0.1.0Oct 15, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only declare readOnlyHint=false, destructiveHint=false, openWorldHint=false. The description adds substantive side effects the annotations cannot convey: a tracked insertion, backup plus undoability via history.undo, and that the target gets a hidden bookmark when it has none. That is exactly the kind of hidden-state mutation an agent must know before calling.

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?

Three dense sentences, front-loaded with the primary action and followed by side effects and sequencing. Parentheticals carry real detail rather than filler, though the address-format clause makes the first sentence 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, the description need not explain returns; instead it covers the prerequisites (caption first), follow-up (field.update), mutation semantics (tracked, undoable, hidden bookmark), write guard via `expect`, and dry_run. Nothing an agent needs to invoke this correctly is missing.

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 would be 3. The description goes beyond it by giving a concrete address example (`p14#a1b2c3d4:20-20`) and clarifying that `show` defaults to a caption's label and number ('Table 3') versus page (PAGEREF) or text, which helps an agent construct valid arguments.

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?

Opens with a specific verb+resource: 'Insert a cross-reference field at an insertion point... pointing `to` a caption or another body paragraph.' It names the exact `at`/`to` model, so an agent can distinguish it from caption_add (which creates the target) and field_update (which fills the value).

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?

Routes the agent explicitly: 'Add captions with caption.add first' and 'run field.update afterwards to fill in the shown value,' which gives both prerequisite and follow-up. It also notes dry_run previews. There is no explicit when-not-to-use, but the sequencing guidance is clear enough for confident selection.

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

Deploy Server