Skip to main content
Glama
Sign In
doc-control

doc-control

by nuncaeslupus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

style_merge

Destructive

Merge duplicate document styles by redirecting every reference from the from styles to the into style, then removing the from styles. Use dry_run to preview first.

Instructions

Merge styles: re-point every use of the from style or styles (ids or names) to into in the body, notes, headers and other styles, then delete the from styles. Use it to clean up duplicate styles; style.rename only renames, style.update changes formatting. Not a tracked change, but history.undo takes it back; it removes style definitions, so the file is backed up first (backup); check with dry_run first. STYLE_NOT_FOUND for an unknown style.

Input Schema

NameRequiredDescriptionDefault
docYesPath to the .docx.
fromYesStyle id or name, or a list of them (they are removed).
intoYesStyle id or name.
expectNoWrite guard: the sha256 read earlier (doc.info, or a reply's doc.sha256), e.g. {"sha256": "9f86d081…"}; a file changed since is DOC_CHANGED_ON_DISK.
dry_runNoPreview only; write nothing.

Output 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. Changed2 schema fields changedv0.7.2
    • addedInput schema / properties / expect / description
      Added value: +"Write guard: the sha256 read earlier (doc.info, or a reply's doc.sha256), e.g. {\"sha256\": \"9f86d081…\"}; a file changed since is DOC_CHANGED_ON_DISK."
    • 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": {
+        "applied": {
+          "description": "One entry per style operation.",
+          "items": {
+            "description": "What one style operation did.",
+            "properties": {
+              "merged": {
+                "description": "Ids merged into this style.",
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "name": {
+                "description": "Display name.",
+                "type": "string"
+              },
+              "op": {
+                "description": "style.create, style.update, style.rename or style.merge.",
+                "type": "string"
+              },
+              "style": {
+                "description": "Style id.",
+                "type": "string"
+              },
+              "type": {
+                "description": "Style type.",
+                "type": "string"
+              },
+              "was": {
+                "description": "Id and name before a rename.",
+                "properties": {
+                  "id": {
+                    "description": "Old id.",
+                    "type": "string"
+                  },
+                  "name": {
+                    "description": "Old name.",
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "backup": {
+          "description": "Path of the backup taken before the write.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "changed_parts": {
+          "description": "Package parts rewritten.",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "dry_run": {
+          "description": "True when nothing was written (a preview).",
+          "type": "boolean"
+        },
+        "op_id": {
+          "description": "Undo-log id of this write (history.undo / history.restore).",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "paragraphs_changed": {
+          "description": "Paragraphs whose style reference was rewritten.",
+          "type": "integer"
+        },
+        "references_rewritten": {
+          "description": "Style references rewritten (renames, merges).",
+          "type": "integer"
+        },
+        "sha256": {
+          "description": "sha256 of the file after the write (pass as expect.sha256 next).",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "tracked": {
+          "description": "Always false: style definitions are not tracked changes.",
+          "type": "boolean"
+        },
+        "warnings": {
+          "description": "Notes on what the write could not do as asked.",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "applied",
+        "dry_run",
+        "tracked",
+        "changed_parts"
+      ],
+      "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. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Goes well beyond the destructiveHint=true annotation: it discloses that this is not a tracked change, that history.undo reverses it, that the file is backed up first, that it removes style definitions, and that STYLE_NOT_FOUND is raised for unknown styles. This is rich behavioral context an agent cannot get from the annotations 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?

The primary action is front-loaded, followed by usage, reversibility, and error semantics, and every sentence carries information. It is dense with parentheticals (the file is backed up first (`backup`); check with dry_run first), which slightly hurts readability but not to the point of waste.

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 destructive, nested-object, multi-parameter tool with an output schema, the description covers exactly the gaps the structured fields cannot: side effects, reversibility via history.undo, backup behavior, dry_run, and the failure code. Return values are appropriately left to the output schema.

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 each parameter, but the description still adds meaning: `from` is described as 'ids or names' and its re-pointing scope ('every use ... in the body, notes, headers and other styles') is spelled out, which clarifies the effect of the two core parameters beyond their schema text. The advantage over the baseline 3 is modest since expect/dry_run are fully covered by 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 ('Merge styles') and precisely defines the operation: re-point every use of `from` to `into` across body, notes, headers, and other styles, then delete `from`. It explicitly distinguishes itself from siblings style.rename and style.update, so an agent can select it without inspecting either 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 the when-to-use ('clean up duplicate styles'), names the two nearest alternatives and why they differ (rename only renames, update changes formatting), and prescribes the safe workflow ('check with dry_run first'). Nothing about tool selection is left to inference.

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