doc-control

Overview Schema Source Related Servers Discussions Admin

anchor_create

Read-onlyIdempotent

Bookmark a passage in a .docx so edits that shift addresses don't lose it; stores quoted text, context, paragraph number, and fingerprint for later anchor.resolve.

Instructions

Make an anchor for a passage so it can be found again after edits shift or change addresses: the quoted text, context characters before and after (default 32, max 200), and the paragraph's number and fingerprint then. at is a range in one paragraph (p142#a7b2a7b2:10-15), a whole paragraph (p142#a7b2a7b2) or a sentence (p142#a7b2a7b2.s3). Use it to bookmark passages you will come back to; find them later with anchor.resolve (text.find searches for any text instead). Read-only; STALE_ADDRESS when at is outdated, SCHEMA_INVALID for a range across paragraphs.

Input Schema

Name	Required	Description
`at`	Yes	Range inside one paragraph, e.g. p142#a7b2a7b2:10-15, or a whole paragraph or sentence (p142#a7b2a7b2.s3).
`doc`	Yes	Path to the .docx file.
`context`	No	Characters of prefix and of suffix to keep.

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.

Changed1 schema field changedv0.7.2Oct 15, 2026

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": {
+        "anchor": {
+          "description": "The anchor: pass it whole to anchor.resolve later.",
+          "properties": {
+            "at": {
+              "description": "Range address, p<n>#<fp>:<start>-<end> (code points).",
+              "type": "string"
+            },
+            "exact": {
+              "description": "The quoted text.",
+              "type": "string"
+            },
+            "fingerprint": {
+              "description": "That paragraph's fingerprint then.",
+              "type": "string"
+            },
+            "hint": {
+              "description": "Paragraph number then, as p<n>.",
+              "type": "string"
+            },
+            "prefix": {
+              "description": "Text just before it.",
+              "type": "string"
+            },
+            "sentence": {
+              "description": "Sentence address when the range was a sentence.",
+              "type": "string"
+            },
+            "suffix": {
+              "description": "Text just after it.",
+              "type": "string"
+            }
+          },
+          "required": [
+            "exact",
+            "prefix",
+            "suffix"
+          ],
+          "type": "object"
+        }
+      },
+      "required": [
+        "anchor"
+      ],
+      "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.4/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), and the description confirms 'Read-only' plus adds what the anchor captures (quoted text, context window, paragraph number and fingerprint). It also discloses two specific failure conditions (STALE_ADDRESS, SCHEMA_INVALID), which is useful beyond the annotations, though return/persistence behavior is only lightly implied.

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?

Front-loads the core purpose before the format details and alternatives, and every clause carries information. It is dense but not padded, using semicolons to pack parallel facts efficiently.

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. The description covers purpose, input formats, alternatives, read-only nature, and error codes, leaving nothing an agent needs to call it correctly unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/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 all three parameters, including the `at` format examples and the context default/max. The description largely restates these (context default 32, max 200; range vs whole-paragraph vs sentence forms) with no additional syntax beyond the schema, so it lands at the baseline.

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 ('Make an anchor for a passage') and immediately explains purpose ('so it can be found again after edits shift or change addresses'). It clearly distinguishes itself from the sibling anchor_resolve by describing the create-vs-find relationship.

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 instructs when to use it ('bookmark passages you will come back to') and names both alternatives by function: find them later with anchor.resolve, and text.find searches for any text instead. The routing decision 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