Skip to main content
Glama
nuncaeslupus

doc-control

by nuncaeslupus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

history_adopt

Re-attach a moved or renamed .docx to its orphaned undo history so undo and restore work again. Finds the matching store by sha256; supports dry runs and forced adoption.

Instructions

Re-attach a moved or renamed document to its old undo history, so history.undo and history.restore work again. It finds the orphaned store whose last recorded state is this file's sha256 (doc.open lists them as adoptable, history.orphans lists all) and moves it, backups and log, to where this document's store lives now. Pass store when several match (the reply lists candidates); force adopts a file edited since; a document that already has history is never overwritten (BATCH_CONFLICT). dry_run moves nothing.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
docYesPath to the .docx.
forceNoAdopt although the document's sha256 is not the store's last.
storeNoThe orphan store to adopt (see doc.open's `adoptable` or history.orphans); needed when several match or the old folder is far away.
dry_runNoSay what would move; move nothing.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
okYesAlways true on success.
opYesThe operation that ran.
apiYesAPI version (1.0).
docNoThe document read or written: path, sha256 and paragraph count.
nextYesCursor for the next page (pass as cursor), or null.
resultYesWhat the operation returns.
warningsYesThings to know about the result.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.7.2
    • 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": {
+        "adopted": {
+          "description": "Whether the store was moved to the document.",
+          "type": "boolean"
+        },
+        "candidates": {
+          "description": "When several stores match: pass one as `store`; nothing moved.",
+          "items": {
+            "description": "An orphan store.",
+            "properties": {
+              "doc": {
+                "description": "Path of the document it last recorded.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "doc_id": {
+                "description": "Id of that document's history, null when unknown.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "entries": {
+                "description": "Log entries.",
+                "type": "integer"
+              },
+              "last_time": {
+                "description": "Time of the last entry (ISO 8601).",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "sha_matched": {
+                "description": "Its last recorded state is this file.",
+                "type": "boolean"
+              },
+              "store": {
+                "description": "Store folder.",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "dry_run": {
+          "description": "True when nothing was written (a preview).",
+          "type": "boolean"
+        },
+        "entries": {
+          "description": "Log entries it holds.",
+          "type": "integer"
+        },
+        "from": {
+          "description": "The orphan store adopted.",
+          "type": "string"
+        },
+        "op_id": {
+          "description": "Log entry noting the adoption.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "sha_matched": {
+          "description": "The file is the store's last recorded state.",
+          "type": "boolean"
+        },
+        "store": {
+          "description": "Where the store lives now (or would).",
+          "type": "string"
+        },
+        "would_move": {
+          "description": "dry_run: the store that would move.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "adopted"
+      ],
+      "type": "object"
+    },
+    "warnings": {
+      "description": "Things to know about the result.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "api",
+    "ok",
+    "op",
+    "result",
+    "warnings",
+    "next"
+  ],
+  "type": "object"
+}
  2. Addedv0.1.3

TDQS

A4.8/5.0
Behavior5/5

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

Goes well beyond the annotations: it discloses exactly what moves (the store, backups and log), that existing history is never overwritten (BATCH_CONFLICT), and that dry_run moves nothing. These are the mutation semantics an agent needs and are not derivable from readOnlyHint=false/destructiveHint=false alone.

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 purpose in the first sentence, then layers the mechanism and parameter conditions. It is dense and multi-clause, but each clause carries actionable information about behavior or parameters, so little waste remains.

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, return values need no explanation, and the description still usefully names reply fields (`adoptable`, `candidates`) and the BATCH_CONFLICT conflict state. For a filesystem-mutating tool this is complete enough to invoke correctly.

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 is 3, but the description adds real meaning: it explains that `store` is needed when several candidates match and points to the reply's `candidates`, and frames `force`/`dry_run` in operational terms. Minor value-add beyond the already-thorough 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+resource ('Re-attach a moved or renamed document to its old undo history') with a clear downstream consequence ('so history.undo and history.restore work again'). This distinguishes it cleanly from history_restore, history_undo, and history_orphans without opening any 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?

Gives explicit trigger conditions (moved or renamed document), names the discovery alternatives (doc.open's `adoptable`, history.orphans), and specifies when each param is needed ('store when several match', 'force adopts a file edited since', dry_run). An agent knows exactly when to reach for this versus siblings.

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

Deploy Server

Other Tools