doc-control

Overview Schema Source Related Servers Discussions Admin

history_search

Read-onlyIdempotent

Search the undo log for a quote to find when a passage was changed or deleted and the op_id needed for undo or restore. Read-only.

Instructions

Search the undo log for a quote: in each logged request and in the text of every paragraph before and after each write, newest first. Use it to find when a passage was changed or deleted, and the op_id for history.undo or history.restore; text.find searches the current document instead. Exact by default (ignore_case, ignore_accents loosen it); match_level default or loose folds case, accents and punctuation and returns each hit's offsets and level. Works on an orphaned store too. Read-only; limit (default 20) caps hits, total counts all.

Input Schema

Name	Required	Description
`doc`	No	Path to the .docx.
`limit`	No	Most hits to return (default 20); `total` counts them all.
`query`	Yes	Text to find.
`store`	No	A store folder (see history.orphans) to read instead of the document's own.
`ignore_case`	No	Ignore case.
`match_level`	No	Fold the search as `text.find` does: `default` ignores case, accents and punctuation (symbols such as `$` still count), `loose` drops symbols too; `exact` keeps the flags. When passed, Word's Find codes in `query` are read as their characters, every hit in a text is returned (not only the first, `exact` included), each with `start` and `end` (its offsets in that text: the request's JSON or the paragraph before or after the write, as `in` names it; not offsets into the cut `text`), `match_level` (the strictest level it meets) and `text` cut around it, and the reply gains `matches_by_level`, adding up to `total`. Without it, the first hit per text, with no `start`, `end` or level. Not with `ignore_case` or `ignore_accents` false at a folded level.
`ignore_accents`	No	Ignore accents: `maria` finds `María`.

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.

Changed4 schema fields changedv0.7.2Oct 15, 2026

addedInput schema / properties / ignore_accents / description
```
Added value: +"Ignore accents: `maria` finds `María`."
```
addedInput schema / properties / ignore_case / description
```
Added value: +"Ignore case."
```

addedInput schema / properties / limit / description

Added value: +"Most hits to return (default 20); `total` counts them all."

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": "Hits, newest entry first (up to limit).",
+          "items": {
+            "description": "A hit.",
+            "properties": {
+              "end": {
+                "description": "With match_level: end of the hit.",
+                "type": "integer"
+              },
+              "in": {
+                "description": "Where: request, or change <n> before/after.",
+                "type": "string"
+              },
+              "match_level": {
+                "description": "With match_level: the level it matched at.",
+                "type": "string"
+              },
+              "op_id": {
+                "description": "The logged op it is in.",
+                "type": "string"
+              },
+              "start": {
+                "description": "With match_level: start of the hit in the text.",
+                "type": "integer"
+              },
+              "text": {
+                "description": "The text around the hit.",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "matches_by_level": {
+          "description": "With match_level: hits per level.",
+          "type": "object"
+        },
+        "total": {
+          "description": "Hits in the whole log.",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "matches",
+        "total"
+      ],
+      "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 / match_level / description

Previous value: -"Fold the search as `find` does: `default` ignores case, accents and punctuation (symbols such as `$` still count), `loose` drops symbols too; `exact` keeps the flags. When passed, Word's Find codes in `query` are read as their characters, every hit in a text is returned (not only the first, `exact` included), each with `start` and `end` (its offsets in that text: the request's JSON or the paragraph before or after the write, as `in` names it; not offsets into the cut `text`), `match_level` (the strictest level it meets) and `text` cut around it, and the reply gains `matches_by_level`, adding up to `total`. Without it, the first hit per text, with no `start`, `end` or level. Not with `ignore_case` or `ignore_accents` false at a folded level."New value: +"Fold the search as `text.find` does: `default` ignores case, accents and punctuation (symbols such as `$` still count), `loose` drops symbols too; `exact` keeps the flags. When passed, Word's Find codes in `query` are read as their characters, every hit in a text is returned (not only the first, `exact` included), each with `start` and `end` (its offsets in that text: the request's JSON or the paragraph before or after the write, as `in` names it; not offsets into the cut `text`), `match_level` (the strictest level it meets) and `text` cut around it, and the reply gains `matches_by_level`, adding up to `total`. Without it, the first hit per text, with no `start`, `end` or level. Not with `ignore_case` or `ignore_accents` false at a folded level."

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 already declare read-only, idempotent and closed-world behavior, but the description adds important operational context: the search order, the scope of paragraphs before and after each write, default exact matching, how ignore flags loosen it, what match_level returns, and the limit/total behavior.

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 and then moves through usage, matching behavior, store support, and limits in a dense but logical order. It is somewhat long and repeats a few schema/annotation facts such as read-only and limit default, but the complexity justifies most of the length.

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?

Given the rich schema, annotations and output schema, the description covers the important gaps: scope of the undo log, default match mode, flag interactions, hit offsets, total counts, sibling alternative, and orphaned-store support. An agent has enough context to call it correctly without opening additional tools.

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 description coverage is 100%, so the schema already documents all parameters in detail. The description adds value by clarifying that matching is exact by default and that ignore_case/ignore_accents loosen it, plus how match_level folds case, accents and punctuation, but much of this overlaps with the schema text.

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: search the undo log for a quote across logged requests and surrounding paragraphs, newest first. It distinguishes from the sibling text_find by explicitly saying text.find searches the current document instead, and it names the downstream tools that consume its op_id.

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 a clear when-to-use case: finding when a passage was changed or deleted, and retrieving op_id for history.undo or history.restore. It also names the alternative text.find for current-document searches, and notes the orphaned `store` case, which is an uncommon but important context.

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

Deploy Server