doc-control

Overview Schema Source Related Servers Discussions Admin

text_find

Read-onlyIdempotent

Locate text or Python regex in a Word document and get each match as a range with surrounding context, ready for replace or anchor operations.

Instructions

Find text or a Python regex (regex) in the document; each match comes back as a range (p8#b72009e4:0-8) with context, ready for text.replace or anchor.create. ignore_case, ignore_accents (maria finds María), whole_word and match_level (default: also ignores punctuation) loosen it; stories adds notes or headers. The first page gives total, and query_word, the query as typed in Word's Find box. Use para.locate to describe where a paragraph is, history.search for removed text. Read-only; limit (default 20) per page, cursor continues; stops after 10 s with more.

Input Schema

TableJSON Schema

Name	Required	Description
`doc`	Yes	Path to the .docx file.
`limit`	No	Most matches to return; more are reached with `cursor`.
`query`	Yes	Text to find (at most 1000 characters), or a Python regex if `regex`.
`regex`	No	Treat `query` as a regex.
`cursor`	No	The `next` value of the previous page.
`context`	No	Characters of surrounding text on each side of a match.
`stories`	No	Stories to read (default ["body"]): "notes" adds footnotes and endnotes, each after the paragraph holding its mark; "headers" adds headers and footers, after the body. Their addresses carry a prefix (fn3/p1#…, hdr1.default/p1#…).
`whole_word`	No	Match only whole words (no letter, digit or mark on either side).
`ignore_case`	No	Ignore case.
`match_level`	No	Fold a literal query: `default` ignores case, accents and punctuation (symbols such as `$` still count), `loose` drops symbols too; `exact` is the search as without it. When passed, Word's Find codes (^p, ^t, ^l, ^s, ^-, ^~, ^uNNN, ^^) in `query` are read as their characters and each match gains `match_level`, the strictest level it meets. Not with `regex` (unless `exact`), nor with `ignore_case` or `ignore_accents` false at a folded level. Two meanings of exact: plain `text.find` (no `match_level`) matches the query as typed, flags as given, ^ codes literal, and its matches carry no level; `match_level: "exact"` keeps that text rule but reads the ^ codes and tags every match. A match's own `match_level` is `exact` only when it equals the query character for character (`case` when only case differs).
`ignore_accents`	No	Ignore accents: `maria` finds `María`. A regex must be written without accents then.

Output Schema

TableJSON 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": {
+        "matches": {
+          "description": "This page of matches, in document order.",
+          "items": {
+            "description": "A match.",
+            "properties": {
+              "at": {
+                "description": "Range address, p<n>#<fp>:<start>-<end> (code points).",
+                "type": "string"
+              },
+              "context": {
+                "description": "The match with some text around it (… marks a cut).",
+                "type": "string"
+              },
+              "match_level": {
+                "description": "With match_level: the level it matched at.",
+                "type": "string"
+              },
+              "text": {
+                "description": "The matched text (clipped when very long).",
+                "type": "string"
+              },
+              "text_truncated": {
+                "description": "True when text was clipped.",
+                "type": "boolean"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "more": {
+          "description": "First page, time budget hit: true (more matches may follow).",
+          "type": "boolean"
+        },
+        "query_word": {
+          "description": "The query as typed in Word's Find box (^p, ^l, ^t, ^s, ^^ codes); null past 255 characters, with ignore_accents, with a soft or no-break hyphen, or at a folded match_level. Absent for a regex.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "query_word_options": {
+          "description": "Find options to tick in Word for the same matches.",
+          "properties": {
+            "match_case": {
+              "description": "Match case.",
+              "type": "boolean"
+            },
+            "whole_words": {
+              "description": "Find whole words only.",
+              "type": "boolean"
+            }
+          },
+          "type": "object"
+        },
+        "total": {
+          "description": "First page only: matches in the whole document.",
+          "type": "integer"
+        },
+        "total_at_least": {
+          "description": "First page, time budget hit: matches counted so far.",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "matches"
+      ],
+      "type": "object"
+    },
+    "warnings": {
+      "description": "Things to know about the result.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "api",
+    "ok",
+    "op",
+    "result",
+    "warnings",
+    "next"
+  ],
+  "type": "object"
+}

Addedv0.1.3Oct 15, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and closed-world, so the safety profile is covered. The description still adds real operational context: a default page size of 20, cursor-based continuation, and a 10-second timeout that signals truncation via `more`. It stops short of describing anything about how matches are ordered or what happens on a regex syntax error.

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 output format are front-loaded, and every sentence carries content. It is, however, a dense run-on paragraph stitched with semicolons rather than discrete clauses, which makes scanning for a specific flag harder than it needs to be.

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 an 11-parameter tool with complex folding semantics, the description covers the purpose, the output address format, pagination, timeout behavior and sibling alternatives, all of which pair with the presence of an output schema. An agent has everything needed to call it correctly on the first attempt.

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% and extremely detailed (especially match_level), so the schema does the heavy lifting and baseline 3 applies. The description restates the flag behaviors with a helpful example ('ignore_accents (maria finds María)') but adds little syntax or defaults that aren't already in the 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 ('Find text or a Python regex in the document') and immediately describes the output shape (a range like p8#b72009e4:0-8 with context). It also names downstream consumers (text.replace, anchor.create), so an agent can distinguish it from siblings such as para_locate or history_search without opening another 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?

Explicitly routes to alternatives: 'Use para.locate to describe where a paragraph is, history.search for removed text.' It also frames the find-then-act workflow by saying matches are 'ready for text.replace or anchor.create', which tells the agent both when to use this tool and what to do next.

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

Deploy Server