Skip to main content
Glama

Preview an edit plan

preview_plan
Read-onlyIdempotent

Validates a DocumentPlan against a Word document as a dry run, returning validity, planned changes, errors, and calculations so you can confirm edits before committing.

Instructions

Dry-run a DocumentPlan JSON against (connectionId, documentId). Returns {isValid, committed, receipt, sourceDocumentId, outputConnectionId, outputDocumentId, outputVersion, outputName, outputContentType, changes, errors, calculation}; the output fields are null and committed is false. Plan shape: { "snapshot": { "eTag": "" }, "revision": { "author": "Review Bot", "timestampUtc": "2026-09-09T10:00:00Z" }, "operations": [ ... ] }. revision controls Word's displayed revision identity; omit timestampUtc to use one engine timestamp for the whole apply. The snapshot detects drift in Word text-host XML, PowerPoint slide/notes XML, and Excel workbook, worksheet, table and note XML; other parts rely on anchors and provider version checks. Omit it only intentionally. Omit contractVersion for legacy 0.2 behavior, or set it to exactly "0.2". Other values fail with contract-mismatch. Unknown properties and enum values fail with invalid-json. Each operation is one object. Concrete examples:

// Replace text: { "op": "changeText", "target": { "paraId": "w14:...", "expect": "Acme Corp", "occurrence": 0 }, "with": "Globex Inc.", "mode": "Tracked" }

// Mark only the words that change (Word, Tracked): "granularity": "Minimal" keeps the words expect and with share at the start and end, so "thirty days" -> "forty-five days" marks only thirty -> forty-five, and "the cap" -> "125% of the cap" is a pure insertion. "Span", the default unless the connection sets one, marks the whole expect: { "op": "changeText", "target": { "paraId": "w14:...", "expect": "thirty days" }, "with": "forty-five days", "mode": "Tracked", "granularity": "Minimal" }

// Rewrite or translate a whole paragraph and keep its bold, italic, colour and links. inspect_document gives a paragraph whose words differ in formatting a markedText such as // "Payment is due within <1>30 days</1> of invoice." Keep each … around the words that should carry that formatting, wherever they land; untagged text takes the paragraph's usual formatting. // expect is the paragraph's complete text. Word and PowerPoint: { "op": "changeText", "target": { "paraId": "w14:...", "expect": "Payment is due within 30 days of invoice." }, "withMarked": "Betaling binnen <1>30 dagen</1> na factuurdatum.", "mode": "Direct" }

// Unified formatting (paragraph/run/table/row/cell/image): { "op": "format", "target": { "paraId": "w14:...", "expect": "important", "occurrence": 0 }, "highlight": "yellow", "bold": true, "color": "FF0000" } { "op": "format", "target": { "kind": "table", "path": "table#0" }, "styleId": "TableGrid", "borderStyle": "single" } { "op": "format", "target": { "kind": "image", "path": "image#0" }, "widthPx": 320, "heightPx": 200 }

// Fill / comment / insert paragraph / setProperty: { "op": "fill", "target": { "tag": "ClientName" }, "value": "Globex" } { "op": "comment", "target": { "paraId": "w14:...", "expect": "..." }, "text": "Confirm this." } { "op": "insert", "target": { "paraId": "w14:...", "expect": "..." }, "position": "After", "text": "New paragraph." } { "op": "insertParagraphs", "target": { "paraId": "w14:...", "expect": "..." }, "position": "After", "paragraphs": [{ "text": "First" }, { "text": "Second" }] } { "op": "removeParagraph", "target": { "paraId": "w14:...", "expect": "Complete paragraph text" } } { "op": "setProperty", "target": { "kind": "docProperty", "path": "core/title" }, "value": "My Title" }

// Every verb above that changes Word content also takes "mode": "Tracked" (the default - the edit lands as a redline a reviewer accepts or rejects) or "Direct". A deck refuses "Tracked": PresentationML has no revision markup.

// Review an existing redline. Revision paths come from inspect_document.nodes (kind "revision"): 'ins#7', 'del#7', 'markIns#7', 'rowIns#7', 'cellDel#7', 'runFormat#7', 'paraFormat#7'. 'all' takes every one; 'author:' takes one person's. An edit that spans a pending revision is refused with revision-overlap; resolve it here first, then re-inspect: { "op": "revision", "target": { "kind": "revision", "path": "all" }, "action": "Accept" } { "op": "revision", "target": { "kind": "revision", "path": "author:Jane Doe" }, "action": "Reject" }

// Reply to, resolve, or delete an existing comment (comment paths from inspect_document.nodes, kind "comment"): { "op": "comment", "target": { "kind": "comment", "path": "comment#1" }, "action": "Reply", "text": "Forty-five, per the MSA." } { "op": "comment", "target": { "kind": "comment", "path": "comment#1" }, "action": "Resolve" } { "op": "comment", "target": { "kind": "comment", "path": "comment#1" }, "action": "Remove" }

// Link existing text (Word only, Direct; http, https or mailto): { "op": "link", "target": { "paraId": "w14:...", "expect": "the price list" }, "url": "https://example.com/prices" } // Continue a list the document already defines (numbering id from a "list#N" node in inspect_document.nodes): { "op": "format", "target": { "paraId": "w14:...", "expect": "" }, "numberingId": 42, "listLevel": 1 }

// Use the document's own styles: styleId takes a style id or the name Word shows ("Heading 2", a template's "Body Text Blue"), as inspect_document lists them under styles. // A style the document does not define is refused with the ones it does; Normal, Heading 1-3, List Paragraph and Table Grid are added when missing, as Word adds them. Word only. { "op": "format", "target": { "paraId": "w14:...", "expect": "" }, "styleId": "Clause Heading" }

// Define a style once instead of repeating direct formatting on every paragraph. Word only. // Define it first, then apply it with format's styleId - both can sit in the same plan: { "op": "defineStyle", "styleId": "Quote", "name": "Pull Quote", "basedOn": "Normal", "next": "Normal", "fontFamily": "Georgia", "sizeHalfPoints": 24, "italic": true, "color": "444444", "alignment": "center", "indentLeftTwips": 720, "spacingBeforeTwips": 240 } { "op": "format", "target": { "paraId": "w14:...", "expect": "" }, "styleId": "Quote" } // type is paragraph (default), character or table. outlineLevel 1-9 puts a heading in the outline. // Defining a style that exists updates it; properties you leave out keep their values. Styles are // never deleted. A style cannot carry a highlight - w:highlight belongs to a run, so use color here.

// Word page geometry, breaks, and notes. All measurements are twips (1440 to the inch). Word only: { "op": "pageSetup", "paperSize": "A4", "orientation": "Landscape", "marginTopTwips": 720, "marginLeftTwips": 1080 } { "op": "insertBreak", "target": { "paraId": "w14:...", "expect": "..." }, "kind": "Page", "position": "After" } { "op": "insertBreak", "target": { "paraId": "w14:...", "expect": "..." }, "kind": "SectionNextPage" } // then pageSetup with a target inside the new section { "op": "note", "target": { "paraId": "w14:...", "expect": "thirty days" }, "kind": "Footnote", "text": "Subject to clause 8.2." } { "op": "note", "target": { "kind": "note", "path": "footnote#1" }, "action": "Update", "text": "Revised wording." } { "op": "note", "target": { "kind": "note", "path": "footnote#1" }, "action": "Remove" }

// Insert a whole new table after a paragraph, or remove an entire table (table path from inspect_document.nodes): { "op": "insertTable", "target": { "paraId": "w14:...", "expect": "..." }, "position": "After", "table": { "headers": ["Region", "Q1"], "rows": [["NL", "41850"]] } } { "op": "removeTable", "target": { "kind": "table", "path": "table#0" } }

// Add or remove table rows / columns; insert or remove image; copy or clear styles. Paths come from inspect_document.nodes: { "op": "insertTableRows", "target": { "kind": "table", "path": "table#0" }, "rows": [["NL","17","41850"]], "position": "End" } { "op": "repeatTableRow", "target": { "kind": "table", "path": "table#0" }, "templateRowIndex": 1, "records": [{ "Description": "Consulting", "Amount": "1200.00" }] } { "op": "removeTableRows", "target": { "kind": "table", "path": "table#0" }, "onlyIfEmpty": true } { "op": "mergeTableCells", "target": { "kind": "tableCell", "path": "table#0/cell#0/1" }, "columnSpan": 2 } // Word only, Direct: merges with the cells to its right { "op": "insertImage", "target": { "paraId": "w14:...", "expect": "..." }, "base64Bytes": "iVBORw0KGgo...", "imageType": "png", "widthPx": 200, "heightPx": 80 } { "op": "insertImage", "target": { "paraId": "w14:...", "expect": "..." }, "imageConnectionId": "images", "imageDocumentId": "", "imageType": "png", "widthPx": 200, "heightPx": 80 } { "op": "removeImage", "target": { "kind": "image", "path": "image#0" } } { "op": "replaceImage", "target": { "kind": "image", "path": "image#0" }, "base64Bytes": "iVBORw0KGgo...", "imageType": "png", "fit": "cover" } // keeps the frame, position and effects; fit cover (crop to fill) or contain { "op": "backgroundImage", "base64Bytes": "iVBORw0KGgo...", "imageType": "png", "opacity": 0.2 } { "op": "backgroundImage", "target": { "kind": "slide", "path": "slide#256" }, "base64Bytes": "iVBORw0KGgo...", "opacity": 0.15 } { "op": "headerFooter", "header": "Northwind Traders", "footer": "Confidential", "showPageNumber": true, "alignment": "edges", "differentFirstPage": true }

// Refresh data. fillTable replaces every cell of a table row by row, keeping cell formatting; rows must match the table's columns, and the table grows or shrinks by rows. { "op": "fillTable", "target": { "kind": "table", "path": "table#0" }, "rows": [["Region","Revenue"],["North","$1.2M"]] } // setChartData replaces any chart's data and keeps its type, colours and layout (PowerPoint; not scatter or bubble): { "op": "setChartData", "target": { "kind": "chart", "path": "chart#256/4" }, "categories": ["Jan","Feb"], "series": [{ "name": "Revenue", "values": [10,12] }] } // bindData links a Word text span or table, or a PowerPoint shape, table or chart node, to a workbook range so refresh_document can update it next time: { "op": "bindData", "target": { "paraId": "w14:...", "expect": "$4.2M" }, "source": "Summary!B2" } { "op": "bindData", "target": { "kind": "chart", "path": "chart#256/4" }, "source": "'Monthly Sales'!A1:D13" }

// Native PowerPoint chart with an editable embedded workbook: { "op": "insertChart", "target": { "kind": "slide", "path": "slide#256" }, "kind": "ClusteredColumn", "categories": ["Q1","Q2"], "series": [{ "name": "Revenue", "values": [10,12] }], "title": "Revenue", "description": "Quarterly revenue" }

// Excel cells and table rows; sheet ids and table paths come from inspection: { "op": "setCell", "target": { "sheetId": 7, "address": "B2" }, "formula": "SUM(B3:B8)" } { "op": "appendTableRows", "target": { "kind": "spreadsheetTable", "path": "table#7/Sales" }, "rows": [["APAC","15"]] }

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "connectionId": "<connectionId>",
      "documentId": "<documentId>",
      "planJson": "<planJson>"
    },
    "name": "preview_plan"
  }
}

Input Schema

NameRequiredDescriptionDefault
planJsonYes
documentIdYes
connectionIdYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.2/5.0
Behavior5/5

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

Annotations already declare readOnly, idempotent and non-destructive, but the description adds substantial context beyond them: the exact result envelope with committed=false and null output fields, the specific failure modes (contract-mismatch, invalid-json, revision-overlap), and which document parts the snapshot can and cannot detect drift in. That is real behavioral value for a dry-run tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is well front-loaded — return envelope, then plan shape, then per-operation examples — and the commented examples are readable. But the volume is far beyond what a tool description should carry, effectively embedding an entire DSL reference, while omitting shorter high-value routing information such as the apply_plan relationship and id provenance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool whose input is a full operation DSL with no output schema and no schema descriptions, the description supplies most of what an agent needs: return shape, error semantics, drift-detection scope, and a wide operation catalog. What keeps it short of complete is the unaddressed origin of connectionId/documentId and the absent link to apply_plan as the follow-up call.

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 0%, so the description must carry the load, and it thoroughly documents planJson: the snapshot/revision/operations shape, contractVersion semantics, and per-operation examples. It is weaker on the other two required parameters — connectionId and documentId are only named parenthetically, with no hint about where ids come from (list_connections, inspect_document), which is the notable gap.

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?

"Dry-run a DocumentPlan JSON against (connectionId, documentId)" gives a precise verb and resource, and the word "dry-run" plus "committed is false" immediately separates it from the write-side apply sibling. An agent knows exactly what this tool does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage guidance is implied rather than stated: it names inspect_document as the source of eTags, revision paths and style ids, and says to resolve revision overlaps here before re-inspecting, which implies a preview-then-apply loop. However, it never names apply_plan or states "use this before applying edits," and gives no explicit when-not-to-use conditions.

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