doc-control

Overview Schema Source Related Servers Discussions Admin

anchor_resolve

Read-onlyIdempotent

Locate a passage's current range in a .docx after edits. Returns its position, a 0-1 score, and match kind (exact, normalized, fuzzy) to re-address text reliably.

Instructions

Find an anchor's passage in the document as it is now: its current range, a 0-1 score and the match kind (exact, normalized or fuzzy). Pass the anchor object anchor.create returned, or just {exact, prefix, suffix}. mode best (default) falls back to a fuzzy match scoring at least 0.80; mode exact accepts only verbatim, normalised or folded (match_level, default default: case, accents, punctuation) matches. Fails with ANCHOR_NOT_FOUND, or ANCHOR_AMBIGUOUS listing up to 5 tied candidates. Use it to re-address a passage after edits; doc.diff maps addresses between two files instead. Read-only.

Input Schema

Name	Required	Description	Default
`doc`	Yes	Path to the .docx file.
`mode`	No	best: verbatim matches first, then fuzzy ones (match says which). exact: only places holding the quote verbatim or, when none does, in the normalised text (soft hyphens and zero-width characters ignored, whitespace collapsed, as text.normalize) or at a fold level of match_level; anything else is ANCHOR_NOT_FOUND.	best
`anchor`	Yes	An anchor from anchor.create, or just {exact, prefix, suffix}.
`match_level`	No	How far the quote is folded when neither it nor its normalised text occurs. exact: today's rule (verbatim, then normalised, then fuzzy in mode best). default: then ignoring case, accents and punctuation (case, then default level), and failing that symbols too (loose). loose: the same ladder. The reply's match_level is the strictest level at which the quote equals the matched text (exact: character for character; case: normalised text with case ignored), with matched_text when it is not exact; a fuzzy match has neither. Not the reply's match kind `match` (exact, normalized, fuzzy), which keeps its meaning.	default

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": {
+        "at": {
+          "description": "Range address, p<n>#<fp>:<start>-<end> (code points).",
+          "type": "string"
+        },
+        "match": {
+          "description": "exact, normalized or fuzzy.",
+          "type": "string"
+        },
+        "match_level": {
+          "description": "Strictest fold level at which the quote equals the matched text.",
+          "type": "string"
+        },
+        "matched_text": {
+          "description": "The text matched, when not character for character.",
+          "type": "string"
+        },
+        "score": {
+          "description": "Match score, 0-1.",
+          "type": "number"
+        },
+        "sentence": {
+          "description": "Sentence address, for a sentence anchor.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "at",
+        "score",
+        "match"
+      ],
+      "type": "object"
+    },
+    "warnings": {
+      "description": "Things to know about the result.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "api",
+    "ok",
+    "op",
+    "result",
+    "warnings",
+    "next"
+  ],
+  "type": "object"
+}

Changed1 schema field changedv0.1.3Oct 15, 2026

changedInput schema / properties / mode / description

Previous value: -"best: verbatim matches first, then fuzzy ones (match says which). exact: only places holding the quote verbatim or, when none does, in the normalised text (soft hyphens and zero-width characters ignored, whitespace collapsed, as text.normalized) or at a fold level of match_level; anything else is ANCHOR_NOT_FOUND."New value: +"best: verbatim matches first, then fuzzy ones (match says which). exact: only places holding the quote verbatim or, when none does, in the normalised text (soft hyphens and zero-width characters ignored, whitespace collapsed, as text.normalize) or at a fold level of match_level; anything else is ANCHOR_NOT_FOUND."

First observedv0.1.0Oct 15, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations cover read-only/idempotent, and the description goes well beyond them: the 0.80 fuzzy threshold, the failure modes ANCHOR_NOT_FOUND and ANCHOR_AMBIGUOUS (listing up to 5 tied candidates), and the strictest-level resolution rule. This is exactly the behavioral detail an agent needs before invoking a fuzzy matcher.

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 and return shape are front-loaded, and almost every sentence carries load (thresholds, error codes, ladder semantics). The prose is dense and dash-heavy, making a few sentences harder to parse than necessary, which keeps it just below the top mark.

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 complex resolver with nested anchor input, two enums and fuzzy behavior, the description covers inputs, default modes, fallback thresholds, and both failure paths. An output schema exists, so return-value documentation is correctly left out.

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 all four parameters and both enums, establishing a baseline of 3. The description adds real value on top by stating the 0.80 fallback threshold for mode=best and explicitly disambiguating the reply's `match_level` from the `match` kind, which the schema does not spell out as clearly.

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?

Specific verb (find/resolve) plus resource (an anchor's passage) and states exactly what is returned: current range, a 0-1 score, and the match kind. It also distinguishes itself from siblings by naming anchor.create (input source) and doc.diff (address mapping between files).

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 the triggering condition ('re-address a passage after edits'), the exact alternative with a different job ('doc.diff maps addresses between two files instead'), and the accepted input forms (full anchor.create object or minimal {exact, prefix, suffix}).

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

Deploy Server