{ "contractVersion": "0.1.0", "generatedAt": null, "toolCount": 10, "tools": [ { "toolName": "superdoc_get_content", "description": "Read document content in various formats. Call this first in any workflow to understand document structure before making edits. Action \"blocks\" returns structured block data with nodeId, nodeType, textPreview, optional full text when includeText:true, formatting properties (fontFamily, fontSize, color, bold, underline, alignment), and ref handles for immediate use with superdoc_edit or superdoc_format. Paragraph-class blocks include tabCount, the number of U+0009 tabs in the complete text even if the 80-character preview trims or truncates them. If tabCount is positive, read includeText:true before editing; do not treat a preview space as proof that there is no tab. Its optional reviewMode selects final, original, or redline numbering metadata without filtering blocks. When you need to evaluate or rewrite existing paragraphs or clauses, prefer action \"blocks\" with includeText:true so you can identify the correct block and then target it by nodeId. Actions \"text\", \"markdown\", and \"html\" return compact strings. Actions \"markdown_projection\" and \"html_projection\" return detailed async projections with review modes, scopes, diagnostics, annotations, block maps, and optional source maps. Projection source targets use tracked coordinates and are valid only at evaluatedRevision; after any mutation, reproject before using them. Treat omitted or partially emitted annotations according to their status instead of guessing an anchor from rendered text. Action \"info\" returns document metadata: word count, paragraph count, page count, outline, available styles, and capability flags. The \"blocks\" action supports pagination via \"offset\" and \"limit\", filtering via \"nodeTypes\", and numbering projection via \"reviewMode\". Other actions ignore pagination and filtering parameters. This tool never modifies the document. Do NOT call superdoc_edit or superdoc_format without first reading blocks to get valid refs and formatting reference values.\n\nEXAMPLES:\n 1. {\"action\":\"blocks\"}\n 2. {\"action\":\"blocks\",\"includeText\":true,\"offset\":0,\"limit\":20,\"reviewMode\":\"final\"}\n 3. {\"action\":\"blocks\",\"offset\":0,\"limit\":20,\"nodeTypes\":[\"heading\",\"paragraph\"]}\n 4. {\"action\":\"text\"}\n 5. {\"action\":\"info\"}\n 6. {\"action\":\"html_projection\",\"reviewMode\":\"redline\",\"includeSourceMap\":true}\n 7. {\"action\":\"markdown_projection\",\"reviewMode\":\"original\",\"scope\":{\"kind\":\"block\",\"nodeType\":\"paragraph\",\"nodeId\":\"paragraph-id\"},\"includeSourceMap\":true}", "inputSchema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "blocks", "extract", "html", "html_projection", "info", "markdown", "markdown_projection", "text" ], "description": "The action to perform. One of: blocks, extract, html, html_projection, info, markdown, markdown_projection, text." }, "in": { "$ref": "#/$defs/StoryLocator", "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes." }, "unflattenLists": { "type": "boolean", "description": "Deprecated and ignored by V2. V2 always emits canonical nested semantic lists. Only for action 'html'. Omit for other actions." }, "reviewMode": { "$ref": "#/$defs/SDProjectionReviewMode", "description": "Only for actions 'markdown_projection', 'html_projection', 'blocks'. Omit for other actions." }, "scope": { "$ref": "#/$defs/SDProjectionScope", "description": "Only for actions 'markdown_projection', 'html_projection'. Omit for other actions." }, "includeSourceMap": { "type": "boolean", "description": "Only for actions 'markdown_projection', 'html_projection'. Omit for other actions." }, "nodeIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Top-level block identities to match before pagination. Only for action 'blocks'. Omit for other actions." }, "textSearch": { "type": "object", "properties": { "terms": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }, "match": { "enum": [ "all", "any" ] }, "caseSensitive": { "type": "boolean" } }, "additionalProperties": false, "required": [ "terms" ], "description": "Only for action 'blocks'. Omit for other actions." }, "offset": { "type": "number", "minimum": 0, "description": "Number of blocks to skip. Default: 0. Only for action 'blocks'. Omit for other actions." }, "limit": { "type": "number", "minimum": 1, "description": "Maximum blocks to return. Omit for all blocks. Only for action 'blocks'. Omit for other actions." }, "nodeTypes": { "type": "array", "items": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt" ] }, "description": "Filter by block types (e.g. ['paragraph', 'heading']). Omit for all types. Only for action 'blocks'. Omit for other actions." }, "includeText": { "type": "boolean", "description": "When true, includes the full flattened block text in each block entry. Only for action 'blocks'. Omit for other actions." } }, "required": [ "action" ], "additionalProperties": false, "$defs": { "BlockNodeAddress": { "type": "object", "properties": { "kind": { "const": "block", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt" ] }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "SDProjectionReviewMode": { "enum": [ "final", "original", "redline" ] }, "SDProjectionScope": { "oneOf": [ { "$ref": "#/$defs/BlockNodeAddress" }, { "$ref": "#/$defs/SelectionTarget" } ] }, "SectionAddress": { "type": "object", "properties": { "kind": { "const": "section", "type": "string" }, "sectionId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "sectionId" ] }, "SelectionEdgeNodeAddress": { "type": "object", "properties": { "kind": { "const": "block", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableOfContents", "sdt", "image" ] }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "SelectionPoint": { "description": "A point in the document. Use {kind:'text', blockId, offset} for character positions or {kind:'nodeEdge', node:{kind:'block', nodeType, nodeId}, edge:'before'|'after'} for block boundaries.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "text", "type": "string" }, "blockId": { "type": "string" }, "offset": { "type": "integer", "minimum": 0 }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "blockId", "offset" ] }, { "type": "object", "properties": { "kind": { "const": "nodeEdge", "type": "string" }, "node": { "$ref": "#/$defs/SelectionEdgeNodeAddress" }, "edge": { "enum": [ "before", "after" ] } }, "additionalProperties": false, "required": [ "kind", "node", "edge" ] } ] }, "SelectionTarget": { "type": "object", "properties": { "kind": { "const": "selection", "type": "string" }, "start": { "$ref": "#/$defs/SelectionPoint" }, "end": { "$ref": "#/$defs/SelectionPoint" }, "story": { "$ref": "#/$defs/StoryLocator" }, "coordinateSpace": { "$ref": "#/$defs/TextCoordinateSpace" } }, "additionalProperties": false, "required": [ "kind", "start", "end" ] }, "StoryLocator": { "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "body", "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "headerFooterSlot", "type": "string" }, "section": { "$ref": "#/$defs/SectionAddress" }, "headerFooterKind": { "enum": [ "header", "footer" ] }, "variant": { "enum": [ "default", "first", "even" ] }, "resolution": { "enum": [ "effective", "explicit" ] }, "onWrite": { "enum": [ "materializeIfInherited", "editResolvedPart", "error" ] } }, "additionalProperties": false, "required": [ "kind", "storyType", "section", "headerFooterKind", "variant" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "headerFooterPart", "type": "string" }, "refId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "refId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "footnote", "type": "string" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "endnote", "type": "string" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "textbox", "type": "string" }, "textboxId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "textboxId" ] } ] }, "TextCoordinateSpace": { "enum": [ "visible", "tracked" ] } } }, "mutates": false, "operations": [ { "operationId": "doc.getText", "intentAction": "text" }, { "operationId": "doc.getMarkdown", "intentAction": "markdown" }, { "operationId": "doc.getHtml", "intentAction": "html" }, { "operationId": "doc.projectMarkdown", "intentAction": "markdown_projection" }, { "operationId": "doc.projectHtml", "intentAction": "html_projection" }, { "operationId": "doc.info", "intentAction": "info" }, { "operationId": "doc.extract", "intentAction": "extract" }, { "operationId": "doc.blocks.list", "intentAction": "blocks" } ] }, { "toolName": "superdoc_edit", "description": "The primary tool for inserting content into documents. ALWAYS use action \"insert\" with type \"markdown\" to create headings, paragraphs, or any block content: this is faster and creates proper document structure in one call. Do NOT use superdoc_create for headings or paragraphs. The markdown parser creates headings from # markers (# = Heading1, ## = Heading2), bold from **text**, italic from *text*, and numbered/bullet lists. Position markdown inserts with \"target\" (a BlockNodeAddress like {kind:\"block\", nodeType, nodeId}) and \"placement\" (before, after, insideStart, insideEnd). Without a target, content appends at the end of the document. IMPORTANT: After a markdown insert, analyze the document context (what kind of document, how titles and body text are styled) and follow up with ONE superdoc_mutations call to format inserted blocks so they look like they belong. Each format.apply step accepts \"inline\" (fontFamily, fontSize, bold, underline, color), \"alignment\", and \"scope\" in the same step. Use scope: \"block\" so formatting covers the entire paragraph. Copy the exact property values from the existing get_content blocks (fontFamily, fontSize, color, alignment, bold, underline). Do NOT invent values: use what the blocks show. Also supports replace, delete, and undo/redo. For ordinary replace and delete, pass a \"ref\" from superdoc_search or superdoc_get_content blocks. Action \"delete\" removes a text range and leaves the block container in place. To remove a whole paragraph, heading, list item, or table, use action \"delete_block\" with target:{kind:\"block\", nodeType, nodeId} from superdoc_get_content action \"blocks\", or action \"delete_block_range\" with \"start\" and \"end\" block addresses to remove a contiguous span of top-level blocks (inclusive). A search ref covers only the matched substring; a block ref covers the entire block text, so use block refs when rewriting or shortening whole paragraphs. To replace every block in the main body, use action \"replace\" with target:{kind:\"story\",storyType:\"body\"}, one text/value/content payload, and changeMode:\"direct\". This replaces body content, not the DOCX package, and does not require a search first. Tracked whole-body replacement is unsupported. For multi-step redlines or whole-clause rewrites, prefer superdoc_mutations with where:{by:\"block\", nodeType, nodeId} from superdoc_get_content action \"blocks\" includeText:true rather than relying on text selectors. Refs expire after any mutation; always re-search before the next edit. For 2+ edits that must succeed or fail atomically, use superdoc_mutations instead. Before an exact HTML or Markdown insert/replace that must be fidelity-checked, use action \"check_support\", review its outcome and diagnostics, then pass its guard back as \"supportCheck\" on the unchanged write. Supports \"dryRun\" to preview changes and \"changeMode: tracked\" to record edits as tracked changes. Do NOT build \"target\" objects manually when a ref is available; prefer \"ref\" for simpler, more reliable targeting.\n\nEXAMPLES:\n 1. {\"action\":\"insert\",\"type\":\"markdown\",\"target\":{\"kind\":\"block\",\"nodeType\":\"paragraph\",\"nodeId\":\"\"},\"placement\":\"before\",\"value\":\"# Executive Summary\\n\\nThis agreement sets forth the principal terms...\",\"changeMode\":\"direct\"}\n 2. {\"action\":\"insert\",\"type\":\"html\",\"value\":\"

Review heading

Tracked rich content.

\",\"changeMode\":\"tracked\"}\n 3. {\"action\":\"insert\",\"type\":\"markdown\",\"value\":\"# Section Title\\n\\nParagraph content here.\\n\\n# Another Section\\n\\nMore content with **bold** and *italic*.\"}\n 4. {\"action\":\"replace\",\"ref\":\"\",\"text\":\"new text here\"}\n 5. {\"action\":\"replace\",\"ref\":\"\",\"value\":\"**Direct rich replacement**\",\"type\":\"markdown\",\"changeMode\":\"direct\"}\n 6. {\"action\":\"replace\",\"ref\":\"\",\"value\":\"Tracked rich replacement\",\"type\":\"html\",\"changeMode\":\"tracked\"}\n 7. {\"action\":\"check_support\",\"operation\":\"insert\",\"input\":{\"type\":\"markdown\",\"value\":\"# Checked section\"},\"options\":{\"changeMode\":\"direct\"}}\n 8. {\"action\":\"replace\",\"target\":{\"kind\":\"story\",\"storyType\":\"body\"},\"value\":\"# Replacement\\n\\nComplete new body.\",\"type\":\"markdown\",\"changeMode\":\"direct\"}\n 9. {\"action\":\"delete\",\"ref\":\"\"}\n 10. {\"action\":\"delete_block\",\"target\":{\"kind\":\"block\",\"nodeType\":\"heading\",\"nodeId\":\"\"}}\n 11. {\"action\":\"undo\"}", "inputSchema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "check_support", "delete", "delete_block", "delete_block_range", "insert", "redo", "replace", "undo" ], "description": "The action to perform. One of: check_support, delete, delete_block, delete_block_range, insert, redo, replace, undo." }, "force": { "type": "boolean", "description": "Bypass confirmation checks." }, "changeTag": { "type": "string", "description": "Caller correlation echoed only on this committed mutation; never stored in DOCX." }, "author": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ], "additionalProperties": false, "description": "Per-call tracked revision author. Does not change the session user. Only for actions 'insert', 'replace', 'delete'. Omit for other actions." }, "date": { "type": "string", "description": "Per-call tracked revision date as an ISO 8601 UTC timestamp. Only for actions 'insert', 'replace', 'delete'. Omit for other actions." }, "changeMode": { "type": "string", "description": "Edit mode: \"direct\" applies changes immediately, \"tracked\" records as suggestions." }, "dryRun": { "type": "boolean", "description": "Preview the result without applying changes." }, "supportCheck": { "type": "object", "properties": { "version": { "const": "sd-html-markdown-check/1", "type": "string" }, "operation": { "enum": [ "insert", "replace" ] }, "evaluatedRevision": { "type": "string" }, "requestSha256": { "type": "string" }, "analysisSha256": { "type": "string" } }, "required": [ "version", "operation", "evaluatedRevision", "requestSha256", "analysisSha256" ], "additionalProperties": false, "description": "Guard returned by capabilities check for this exact HTML or Markdown write. Only for actions 'insert', 'replace'. Omit for other actions." }, "value": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "string", "description": "Text content to insert." } ] }, { "type": "string", "description": "Text content to insert." } ] }, { "type": "string", "description": "Text content to insert." } ] }, { "type": "string", "description": "HTML or Markdown content to convert and insert." } ] }, { "type": "string", "description": "HTML or Markdown content to convert and insert." } ] }, { "type": "string", "description": "HTML or Markdown content to convert and insert." } ] }, { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "string", "description": "HTML or Markdown replacement content." } ] }, { "type": "string", "description": "HTML or Markdown replacement content." } ] }, { "type": "string", "description": "HTML or Markdown that replaces the complete main body." } ] } ], "description": "Only for actions 'insert', 'replace'. Omit for other actions." }, "type": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "const": "ooxml", "type": "string" }, { "const": "text", "description": "Plain-text content format. Omit for the same 'text' default.", "type": "string" } ] }, { "const": "text", "description": "Plain-text content format. Omit for the same 'text' default.", "type": "string" } ] }, { "const": "text", "description": "Plain-text content format. Omit for the same 'text' default.", "type": "string" } ] }, { "enum": [ "markdown", "html" ] } ] }, { "enum": [ "markdown", "html" ] } ] }, { "enum": [ "markdown", "html" ] } ] }, { "anyOf": [ { "anyOf": [ { "anyOf": [ { "const": "ooxml", "type": "string" }, { "enum": [ "html", "markdown" ] } ] }, { "enum": [ "html", "markdown" ] } ] }, { "enum": [ "html", "markdown" ] } ] } ], "description": "Only for actions 'insert', 'replace'. Omit for other actions." }, "namespaces": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Only for actions 'insert', 'replace'. Omit for other actions." }, "sourcePartUri": { "type": "string", "description": "Only for actions 'insert', 'replace'. Omit for other actions." }, "dependencies": { "type": "array", "items": { "type": "object", "properties": { "sourcePartUri": { "type": "string" }, "relationshipId": { "type": "string" }, "relationshipType": { "type": "string" }, "target": { "type": "string" }, "targetMode": { "enum": [ "Internal", "External" ] }, "contentType": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "dataBase64": { "type": "string" } }, "additionalProperties": false, "required": [ "sourcePartUri", "relationshipId", "relationshipType", "target", "targetMode", "contentType" ] }, "description": "Only for actions 'insert', 'replace'. Omit for other actions." }, "target": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "oneOf": [ { "$ref": "#/$defs/BlockNodeAddress" }, { "$ref": "#/$defs/SelectionTarget" } ] }, { "$ref": "#/$defs/BlockNodeAddress", "description": "Block address for structural insertion: {kind:'block', nodeType:'...', nodeId:'...'}." } ] }, { "$ref": "#/$defs/SelectionTarget", "description": "Selection target: {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}." } ] }, { "oneOf": [ { "$ref": "#/$defs/SelectionTarget" }, { "$ref": "#/$defs/BlockNodeAddress" } ] } ] }, { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "$ref": "#/$defs/BlockNodeAddress" }, { "oneOf": [ { "$ref": "#/$defs/BlockNodeAddress" }, { "$ref": "#/$defs/SelectionTarget" } ] } ] }, { "oneOf": [ { "$ref": "#/$defs/BlockNodeAddress" }, { "$ref": "#/$defs/SelectionTarget" } ] } ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "body", "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType" ] } ] }, { "$ref": "#/$defs/SelectionTarget" } ] }, { "oneOf": [ { "$ref": "#/$defs/BlockNodeAddress" }, { "$ref": "#/$defs/SelectionTarget" } ], "description": "Target block or selection to replace." } ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "body", "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType" ] } ] }, { "oneOf": [ { "$ref": "#/$defs/BlockNodeAddress" }, { "$ref": "#/$defs/SelectionTarget" } ] } ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "body", "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType" ] } ] } ] }, { "$ref": "#/$defs/SelectionTarget", "description": "Selection target: {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}. Use 'ref' instead when you have a search result handle." } ] }, { "$ref": "#/$defs/DeletableBlockNodeAddress" } ], "description": "Required for action 'delete_block'." }, "in": { "$ref": "#/$defs/StoryLocator", "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes. Only for actions 'insert', 'replace', 'delete'. Omit for other actions." }, "placement": { "enum": [ "before", "after", "insideStart", "insideEnd" ], "description": "Only for action 'insert'. Omit for other actions." }, "capture": { "type": "object", "properties": { "formatVersion": { "const": 1, "type": "number" }, "snapshotId": { "type": "string", "minLength": 1 }, "at": { "oneOf": [ { "$ref": "#/$defs/SelectionTarget" }, { "type": "object", "properties": { "kind": { "const": "tableCells", "type": "string" }, "selectionMode": { "const": "cells", "type": "string" }, "isRectangular": { "const": true, "type": "boolean" }, "tableId": { "type": "string" }, "start": { "type": "object", "properties": { "rowIndex": { "type": "integer" }, "columnIndex": { "type": "integer" } }, "additionalProperties": false, "required": [ "rowIndex", "columnIndex" ] }, "end": { "type": "object", "properties": { "rowIndex": { "type": "integer" }, "columnIndex": { "type": "integer" } }, "additionalProperties": false, "required": [ "rowIndex", "columnIndex" ] }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "tableId", "start", "end" ] } ] }, "evaluatedRevision": { "type": "string" }, "fragment": { "type": "object", "properties": { "placement": { "enum": [ "inline", "blocks", "table" ] }, "xml": { "type": "string" }, "namespaces": { "type": "object", "additionalProperties": { "type": "string" } }, "table": { "type": "object", "properties": { "tableId": { "type": "string" }, "gridColumnCount": { "type": "integer" }, "cells": { "type": "array", "items": { "type": "object", "properties": { "rowIndex": { "type": "integer" }, "columnIndex": { "type": "integer" }, "gridSpan": { "type": "integer" }, "vMerge": { "enum": [ "none", "restart", "continue" ] } }, "additionalProperties": false, "required": [ "rowIndex", "columnIndex", "gridSpan", "vMerge" ] } } }, "additionalProperties": false, "required": [ "tableId", "gridColumnCount", "cells" ] } }, "additionalProperties": false, "required": [ "placement", "xml", "namespaces" ] }, "source": { "type": "object", "properties": { "story": { "oneOf": [ { "$ref": "#/$defs/StoryLocator" }, { "type": "null" } ] }, "partUri": { "type": "string" }, "paragraphStyleId": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "packageRevision": { "type": "string" } }, "additionalProperties": false, "required": [ "story", "partUri", "paragraphStyleId" ] }, "context": { "type": "object", "properties": { "xml": { "type": "array", "items": { "type": "string" } }, "tableMerges": { "type": "array", "items": { "type": "object", "properties": { "selectedRowIndex": { "type": "integer" }, "columnIndex": { "type": "integer" }, "restartRowIndex": { "type": "integer" }, "restartCellPropertiesXml": { "type": "string" } }, "additionalProperties": false, "required": [ "selectedRowIndex", "columnIndex", "restartRowIndex", "restartCellPropertiesXml" ] } } }, "additionalProperties": false, "required": [ "xml" ] }, "dependencies": { "type": "array", "items": { "type": "object", "properties": { "sourcePartUri": { "type": "string" }, "relationshipId": { "type": "string" }, "relationshipType": { "type": "string" }, "target": { "type": "string" }, "targetMode": { "enum": [ "Internal", "External" ] }, "contentType": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "dataBase64": { "type": "string" } }, "additionalProperties": false, "required": [ "sourcePartUri", "relationshipId", "relationshipType", "target", "targetMode", "contentType" ] } }, "diagnostics": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false, "required": [ "code", "message" ] } } }, "additionalProperties": false, "required": [ "formatVersion", "at", "evaluatedRevision", "fragment", "source", "context", "dependencies", "diagnostics" ], "description": "Only for actions 'insert', 'replace'. Omit for other actions." }, "ref": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "string", "description": "Handle ref from superdoc_search result (pass handle.ref value directly). Preferred over building a target object." }, { "type": "string", "minLength": 1 } ], "description": "Handle ref from superdoc_search result (pass handle.ref value directly). Preferred over building a target object." }, { "anyOf": [ { "anyOf": [ { "type": "string", "description": "Search result handle." }, { "type": "string", "description": "Reference handle from a previous search result." } ], "description": "Search result handle." }, { "type": "string", "minLength": 1 } ], "description": "Search result handle." } ], "description": "Handle ref from superdoc_search result (pass handle.ref value directly). Preferred over building a target object." }, { "type": "string", "description": "Handle ref string from a superdoc_search result. Pass the handle.ref value directly (e.g. 'text:eyJ...'). Preferred over 'target' for inline formatting." } ], "description": "Handle ref from superdoc_search result (pass handle.ref value directly). Preferred over building a target object. Only for actions 'insert', 'replace', 'delete'. Omit for other actions." }, "content": { "anyOf": [ { "oneOf": [ { "type": "object" }, { "type": "array", "items": { "type": "object" } } ], "description": "Document fragment to insert (structured content)." }, { "anyOf": [ { "oneOf": [ { "type": "object" }, { "type": "array", "items": { "type": "object" } } ], "description": "Document fragment to replace with (structured content)." }, { "oneOf": [ { "type": "object" }, { "type": "array", "items": { "type": "object" } } ], "description": "Document fragment that replaces the complete main body." } ], "description": "Document fragment to replace with (structured content)." } ], "description": "Document fragment to insert (structured content). Only for actions 'insert', 'replace'. Omit for other actions." }, "nestingPolicy": { "type": "object", "properties": { "tables": { "enum": [ "forbid", "allow" ] } }, "additionalProperties": false, "description": "Controls nesting behavior. tables: 'allow' permits inserting tables inside other tables. Only for actions 'insert', 'replace'. Omit for other actions." }, "replaceMode": { "type": "string", "enum": [ "contents" ], "description": "Replace supported paragraph contents while preserving its container. Requires direct mode. Only for action 'replace'. Omit for other actions." }, "expectedSnapshotId": { "type": "string", "description": "Same-session snapshot of the unchanged paragraph required before contents replacement or restoration. Only for action 'replace'. Omit for other actions." }, "text": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "string", "description": "Complete replacement text for the main body." } ] }, { "type": "string", "description": "Replacement text content." } ] }, { "type": "string", "description": "Replacement text content." } ], "description": "Only for action 'replace'. Omit for other actions." }, "snapshotId": { "type": "string", "minLength": 1, "description": "Only for action 'replace'. Omit for other actions." }, "expectedText": { "type": "string", "description": "Require exact selected text before mutation. Only explicit single-paragraph text selections support this guard. Only for action 'replace'. Omit for other actions." }, "replacementGranularity": { "enum": [ "word", "phrase", "range" ], "description": "Tracked revision boundaries for an explicit single-paragraph text selection. word (default) preserves matching tokens; phrase joins edits separated only by spaces; range replaces the complete selection. Requires changeMode: tracked. Only for action 'replace'. Omit for other actions." }, "behavior": { "$ref": "#/$defs/DeleteBehavior", "description": "Delete behavior: 'selection' (default) or 'exact'. Only for action 'delete'. Omit for other actions." }, "start": { "$ref": "#/$defs/BlockNodeAddress", "description": "Required for action 'delete_block_range'." }, "end": { "$ref": "#/$defs/BlockNodeAddress", "description": "Required for action 'delete_block_range'." }, "operation": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "const": "insert", "type": "string" }, { "const": "replace", "type": "string" } ] }, { "const": "projectHtml", "type": "string" } ] }, { "const": "projectMarkdown", "type": "string" } ], "description": "Required for action 'check_support'." }, "input": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "in": { "$ref": "#/$defs/StoryLocator" }, "target": { "oneOf": [ { "$ref": "#/$defs/SelectionTarget" }, { "$ref": "#/$defs/BlockNodeAddress" } ] }, "value": { "type": "string" }, "type": { "enum": [ "html", "markdown" ] }, "placement": { "enum": [ "before", "after", "insideStart", "insideEnd" ] } }, "additionalProperties": false, "required": [ "target", "value", "type" ] }, { "type": "object", "properties": { "in": { "$ref": "#/$defs/StoryLocator" }, "ref": { "type": "string", "minLength": 1 }, "value": { "type": "string" }, "type": { "enum": [ "html", "markdown" ] }, "placement": { "enum": [ "before", "after", "insideStart", "insideEnd" ] } }, "additionalProperties": false, "required": [ "ref", "value", "type" ] }, { "type": "object", "properties": { "in": { "$ref": "#/$defs/StoryLocator" }, "value": { "type": "string" }, "type": { "enum": [ "html", "markdown" ] }, "placement": { "enum": [ "before", "after", "insideStart", "insideEnd" ] } }, "additionalProperties": false, "required": [ "value", "type" ] } ] }, { "oneOf": [ { "type": "object", "properties": { "in": { "$ref": "#/$defs/StoryLocator" }, "target": { "oneOf": [ { "$ref": "#/$defs/SelectionTarget" }, { "$ref": "#/$defs/BlockNodeAddress" } ] }, "value": { "type": "string" }, "type": { "enum": [ "html", "markdown" ] }, "nestingPolicy": { "type": "object", "properties": { "tables": { "enum": [ "forbid", "allow" ] } }, "additionalProperties": false, "description": "Controls nesting behavior. tables: 'allow' permits inserting tables inside other tables." } }, "additionalProperties": false, "required": [ "target", "value", "type" ] }, { "type": "object", "properties": { "in": { "$ref": "#/$defs/StoryLocator" }, "ref": { "type": "string", "minLength": 1 }, "value": { "type": "string" }, "type": { "enum": [ "html", "markdown" ] }, "nestingPolicy": { "type": "object", "properties": { "tables": { "enum": [ "forbid", "allow" ] } }, "additionalProperties": false, "description": "Controls nesting behavior. tables: 'allow' permits inserting tables inside other tables." } }, "additionalProperties": false, "required": [ "ref", "value", "type" ] } ] } ] }, { "type": "object", "properties": { "in": { "$ref": "#/$defs/StoryLocator" }, "reviewMode": { "$ref": "#/$defs/SDProjectionReviewMode" }, "scope": { "$ref": "#/$defs/SDProjectionScope" }, "includeSourceMap": { "type": "boolean" } }, "additionalProperties": false } ] }, { "type": "object", "properties": { "in": { "$ref": "#/$defs/StoryLocator" }, "reviewMode": { "$ref": "#/$defs/SDProjectionReviewMode" }, "scope": { "$ref": "#/$defs/SDProjectionScope" }, "includeSourceMap": { "type": "boolean" } }, "additionalProperties": false } ], "description": "Only for action 'check_support'. Omit for other actions." }, "options": { "anyOf": [ { "type": "object", "properties": { "changeMode": { "enum": [ "direct", "tracked" ] } }, "additionalProperties": false }, { "type": "object", "properties": { "changeMode": { "enum": [ "direct", "tracked" ] }, "replaceMode": { "const": "contents", "type": "string" }, "expectedSnapshotId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ], "description": "Only for action 'check_support'. Omit for other actions." } }, "required": [ "action" ], "additionalProperties": false, "$defs": { "BlockNodeAddress": { "type": "object", "properties": { "kind": { "const": "block", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt" ] }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "DeletableBlockNodeAddress": { "type": "object", "properties": { "kind": { "const": "block", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "sdt" ] }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "DeleteBehavior": { "enum": [ "selection", "exact" ] }, "SDProjectionReviewMode": { "enum": [ "final", "original", "redline" ] }, "SDProjectionScope": { "oneOf": [ { "$ref": "#/$defs/BlockNodeAddress" }, { "$ref": "#/$defs/SelectionTarget" } ] }, "SectionAddress": { "type": "object", "properties": { "kind": { "const": "section", "type": "string" }, "sectionId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "sectionId" ] }, "SelectionEdgeNodeAddress": { "type": "object", "properties": { "kind": { "const": "block", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableOfContents", "sdt", "image" ] }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "SelectionPoint": { "description": "A point in the document. Use {kind:'text', blockId, offset} for character positions or {kind:'nodeEdge', node:{kind:'block', nodeType, nodeId}, edge:'before'|'after'} for block boundaries.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "text", "type": "string" }, "blockId": { "type": "string" }, "offset": { "type": "integer", "minimum": 0 }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "blockId", "offset" ] }, { "type": "object", "properties": { "kind": { "const": "nodeEdge", "type": "string" }, "node": { "$ref": "#/$defs/SelectionEdgeNodeAddress" }, "edge": { "enum": [ "before", "after" ] } }, "additionalProperties": false, "required": [ "kind", "node", "edge" ] } ] }, "SelectionTarget": { "type": "object", "properties": { "kind": { "const": "selection", "type": "string" }, "start": { "$ref": "#/$defs/SelectionPoint" }, "end": { "$ref": "#/$defs/SelectionPoint" }, "story": { "$ref": "#/$defs/StoryLocator" }, "coordinateSpace": { "$ref": "#/$defs/TextCoordinateSpace" } }, "additionalProperties": false, "required": [ "kind", "start", "end" ] }, "StoryLocator": { "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "body", "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "headerFooterSlot", "type": "string" }, "section": { "$ref": "#/$defs/SectionAddress" }, "headerFooterKind": { "enum": [ "header", "footer" ] }, "variant": { "enum": [ "default", "first", "even" ] }, "resolution": { "enum": [ "effective", "explicit" ] }, "onWrite": { "enum": [ "materializeIfInherited", "editResolvedPart", "error" ] } }, "additionalProperties": false, "required": [ "kind", "storyType", "section", "headerFooterKind", "variant" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "headerFooterPart", "type": "string" }, "refId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "refId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "footnote", "type": "string" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "endnote", "type": "string" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "textbox", "type": "string" }, "textboxId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "textboxId" ] } ] }, "TextCoordinateSpace": { "enum": [ "visible", "tracked" ] } } }, "mutates": true, "operations": [ { "operationId": "doc.insert", "intentAction": "insert", "requiredOneOf": [ [ "value", "type", "namespaces" ], [ "capture" ], [ "target", "value" ], [ "ref", "value" ], [ "value" ], [ "target", "value", "type" ], [ "ref", "value", "type" ], [ "value", "type" ], [ "content" ] ] }, { "operationId": "doc.replace", "intentAction": "replace", "requiredOneOf": [ [ "target", "text" ], [ "target", "snapshotId" ], [ "target", "value", "type", "namespaces" ], [ "target", "capture" ], [ "target", "text" ], [ "ref", "text" ], [ "target", "text" ], [ "target", "content" ], [ "ref", "content" ], [ "target", "content" ], [ "target", "value", "type" ], [ "ref", "value", "type" ], [ "target", "value", "type" ] ] }, { "operationId": "doc.delete", "intentAction": "delete", "requiredOneOf": [ [ "target" ], [ "ref" ] ] }, { "operationId": "doc.blocks.delete", "intentAction": "delete_block", "required": [ "target" ] }, { "operationId": "doc.blocks.deleteRange", "intentAction": "delete_block_range", "required": [ "start", "end" ] }, { "operationId": "doc.capabilities.check", "intentAction": "check_support", "requiredOneOf": [ [ "operation", "input" ], [ "operation", "input" ], [ "operation" ], [ "operation" ] ] }, { "operationId": "doc.history.undo", "intentAction": "undo" }, { "operationId": "doc.history.redo", "intentAction": "redo" } ] }, { "toolName": "superdoc_format", "description": "Change text and paragraph formatting. To format multiple items at once, use superdoc_mutations with format.apply steps instead of calling this tool repeatedly. Use require \"all\" with a node selector to format every heading or paragraph in one batch. Use this tool for single-item formatting when you have a valid ref or nodeId. Action \"inline\" applies character formatting (bold, italic, underline, color, fontSize, fontFamily, highlight, strike, vertAlign) to a text range via \"ref\". Action \"set_style\" applies a named paragraph style by styleId (get available styles from superdoc_get_content info). Actions \"set_alignment\", \"set_indentation\", \"set_spacing\", \"set_direction\", and \"set_flow_options\" change paragraph-level properties and require a block target: {kind:\"block\", nodeType:\"paragraph\", nodeId:\"\"}, NOT a ref. Use \"set_flow_options\" with pageBreakBefore:true to start a paragraph on a new page. Supports \"dryRun\" and \"changeMode: tracked\" for inline formatting. Paragraph-level actions do NOT support tracked changes. Do NOT use a search ref for paragraph-level actions; they require a block target with nodeId. Do NOT use {kind:\"block\", start:{kind:\"nodeEdge\",...}} or selection-like structures for paragraph actions. ONLY {kind:\"block\", nodeType, nodeId} is accepted. Do NOT issue multiple superdoc_format calls in parallel; each call invalidates refs for subsequent calls.\n\nEXAMPLES:\n 1. {\"action\":\"inline\",\"ref\":\"\",\"inline\":{\"bold\":true}}\n 2. {\"action\":\"inline\",\"ref\":\"\",\"inline\":{\"fontFamily\":\"Calibri\",\"fontSize\":11,\"color\":\"#000000\",\"bold\":false}}\n 3. {\"action\":\"set_alignment\",\"target\":{\"kind\":\"block\",\"nodeType\":\"paragraph\",\"nodeId\":\"\"},\"alignment\":\"center\"}\n 4. {\"action\":\"set_flow_options\",\"target\":{\"kind\":\"block\",\"nodeType\":\"paragraph\",\"nodeId\":\"\"},\"pageBreakBefore\":true}\n 5. {\"action\":\"set_spacing\",\"target\":{\"kind\":\"block\",\"nodeType\":\"paragraph\",\"nodeId\":\"\"},\"lineSpacing\":{\"rule\":\"auto\",\"value\":1.5}}", "inputSchema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "inline", "set_alignment", "set_direction", "set_flow_options", "set_indentation", "set_spacing", "set_style", "set_style_ref" ], "description": "The action to perform. One of: inline, set_alignment, set_direction, set_flow_options, set_indentation, set_spacing, set_style, set_style_ref." }, "force": { "type": "boolean", "description": "Bypass confirmation checks." }, "changeTag": { "type": "string", "description": "Caller correlation echoed only on this committed mutation; never stored in DOCX." }, "author": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ], "additionalProperties": false, "description": "Per-call tracked revision author. Does not change the session user. Only for action 'inline'. Omit for other actions." }, "date": { "type": "string", "description": "Per-call tracked revision date as an ISO 8601 UTC timestamp. Only for action 'inline'. Omit for other actions." }, "changeMode": { "type": "string", "description": "Edit mode: \"direct\" applies changes immediately, \"tracked\" records as suggestions." }, "dryRun": { "type": "boolean", "description": "Preview the result without applying changes." }, "target": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "$ref": "#/$defs/SelectionTarget", "description": "Selection target: {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}. Use 'ref' instead when you have a search result handle." }, { "oneOf": [ { "$ref": "#/$defs/ParagraphAddress" }, { "$ref": "#/$defs/HeadingAddress" }, { "$ref": "#/$defs/ListItemAddress" } ] } ], "description": "Selection target: {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}. Use 'ref' instead when you have a search result handle." }, { "oneOf": [ { "$ref": "#/$defs/ParagraphAddress" }, { "$ref": "#/$defs/HeadingAddress" }, { "$ref": "#/$defs/ListItemAddress" } ] } ], "description": "Selection target: {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}. Use 'ref' instead when you have a search result handle." }, { "oneOf": [ { "$ref": "#/$defs/ParagraphAddress" }, { "$ref": "#/$defs/HeadingAddress" }, { "$ref": "#/$defs/ListItemAddress" } ] } ], "description": "Selection target: {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}. Use 'ref' instead when you have a search result handle." }, { "oneOf": [ { "$ref": "#/$defs/ParagraphAddress" }, { "$ref": "#/$defs/HeadingAddress" }, { "$ref": "#/$defs/ListItemAddress" } ] } ], "description": "Selection target: {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}. Use 'ref' instead when you have a search result handle." }, { "oneOf": [ { "$ref": "#/$defs/ParagraphAddress" }, { "$ref": "#/$defs/HeadingAddress" }, { "$ref": "#/$defs/ListItemAddress" } ] } ], "description": "Selection target: {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}. Use 'ref' instead when you have a search result handle." }, { "oneOf": [ { "$ref": "#/$defs/ParagraphAddress" }, { "$ref": "#/$defs/HeadingAddress" }, { "$ref": "#/$defs/ListItemAddress" } ] } ], "description": "Selection target: {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}. Use 'ref' instead when you have a search result handle." }, { "oneOf": [ { "$ref": "#/$defs/ParagraphAddress" }, { "$ref": "#/$defs/HeadingAddress" }, { "$ref": "#/$defs/ListItemAddress" } ] } ], "description": "Selection target: {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}. Use 'ref' instead when you have a search result handle. Required for actions 'set_style', 'set_style_ref', 'set_alignment', 'set_indentation', 'set_spacing', 'set_flow_options', 'set_direction'." }, "in": { "$ref": "#/$defs/StoryLocator", "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes. Only for action 'inline'. Omit for other actions." }, "inline": { "type": "object", "properties": { "bold": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "italic": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "strike": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "underline": { "oneOf": [ { "type": "boolean" }, { "type": "null" }, { "type": "object", "properties": { "style": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "color": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "themeColor": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 } ] }, "highlight": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "color": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "fontSize": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "fontFamily": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "letterSpacing": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "vertAlign": { "oneOf": [ { "enum": [ "superscript", "subscript", "baseline" ] }, { "type": "null" } ] }, "position": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "dstrike": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "smallCaps": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "caps": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "shading": { "oneOf": [ { "type": "object", "properties": { "fill": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "color": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "val": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 }, { "type": "null" } ] }, "border": { "oneOf": [ { "type": "object", "properties": { "val": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "sz": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "color": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "space": { "oneOf": [ { "type": "number" }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 }, { "type": "null" } ] }, "outline": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "shadow": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "emboss": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "imprint": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "charScale": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "kerning": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "vanish": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "webHidden": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "specVanish": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "rtl": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "cs": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "bCs": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "iCs": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "eastAsianLayout": { "oneOf": [ { "type": "object", "properties": { "id": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "combine": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "combineBrackets": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "vert": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "vertCompress": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 }, { "type": "null" } ] }, "em": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "fitText": { "oneOf": [ { "type": "object", "properties": { "val": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "id": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 }, { "type": "null" } ] }, "snapToGrid": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "lang": { "oneOf": [ { "type": "object", "properties": { "val": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "eastAsia": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "bidi": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 }, { "type": "null" } ] }, "oMath": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "rStyle": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "rFonts": { "oneOf": [ { "type": "object", "properties": { "ascii": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "hAnsi": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "eastAsia": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "cs": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "asciiTheme": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "hAnsiTheme": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "eastAsiaTheme": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "csTheme": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "hint": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 }, { "type": "null" } ] }, "fontSizeCs": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "ligatures": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "numForm": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "numSpacing": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "stylisticSets": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "val": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, "minItems": 1 }, { "type": "null" } ] }, "contextualAlternates": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1, "description": "Inline formatting properties to apply. Set a property to apply it, use null to clear it. Example: {bold: true, italic: true} or {bold: null} to remove bold. Only for action 'inline'. Omit for other actions." }, "ref": { "type": "string", "description": "Handle ref string from a superdoc_search result. Pass the handle.ref value directly (e.g. 'text:eyJ...'). Preferred over 'target' for inline formatting. Only for action 'inline'. Omit for other actions." }, "styleId": { "anyOf": [ { "type": "string", "minLength": 1, "description": "Named paragraph style ID (e.g. 'Normal', 'Heading1', 'BodyText'). Use superdoc_search to find a nearby paragraph, then inspect its style to determine the correct styleId." }, { "type": "string", "minLength": 1, "description": "Named paragraph style ID (e.g. 'Normal', 'Heading1'). Unlike setStyle, existing run formatting is preserved." } ], "description": "Named paragraph style ID (e.g. 'Normal', 'Heading1', 'BodyText'). Use superdoc_search to find a nearby paragraph, then inspect its style to determine the correct styleId. Required for action 'set_style_ref'." }, "role": { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "defaultParagraph", "type": "string" } }, "additionalProperties": false, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "const": "heading", "type": "string" }, "level": { "type": "integer", "minimum": 1, "maximum": 9 } }, "additionalProperties": false, "required": [ "kind", "level" ] }, { "type": "object", "properties": { "kind": { "const": "title", "type": "string" } }, "additionalProperties": false, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "const": "subtitle", "type": "string" } }, "additionalProperties": false, "required": [ "kind" ] } ], "description": "Semantic built-in style intent, resolved to the document authored style identity. Only for action 'set_style'. Omit for other actions." }, "alignment": { "enum": [ "left", "center", "right", "justify" ], "description": "Visual paragraph alignment. In RTL paragraphs, 'left' stores w:jc='right' and 'right' stores w:jc='left' so Word displays the requested side. Required for action 'set_alignment'." }, "left": { "type": "integer", "description": "Left indentation in twips (1440 = 1 inch). Only for action 'set_indentation'. Omit for other actions." }, "right": { "type": "integer", "description": "Right indentation in twips (1440 = 1 inch). Only for action 'set_indentation'. Omit for other actions." }, "firstLine": { "type": "integer", "minimum": 0, "description": "First line indent in twips. Cannot be combined with hanging. Only for action 'set_indentation'. Omit for other actions." }, "hanging": { "type": "integer", "minimum": 0, "description": "Hanging indent in twips. Cannot be combined with firstLine. Only for action 'set_indentation'. Omit for other actions." }, "before": { "type": "integer", "minimum": 0, "description": "Space before paragraph in twips (20 twips = 1pt). Only for action 'set_spacing'. Omit for other actions." }, "after": { "type": "integer", "minimum": 0, "description": "Space after paragraph in twips (20 twips = 1pt). Only for action 'set_spacing'. Omit for other actions." }, "line": { "type": "integer", "minimum": 1, "description": "Line spacing value. Meaning depends on lineRule. Must be provided together with lineRule. Only for action 'set_spacing'. Omit for other actions." }, "lineRule": { "enum": [ "auto", "exact", "atLeast" ], "description": "Line spacing rule. Required when 'line' is set. Only for action 'set_spacing'. Omit for other actions." }, "contextualSpacing": { "type": "boolean", "description": "Only for action 'set_flow_options'. Omit for other actions." }, "pageBreakBefore": { "type": "boolean", "description": "Only for action 'set_flow_options'. Omit for other actions." }, "suppressAutoHyphens": { "type": "boolean", "description": "Only for action 'set_flow_options'. Omit for other actions." }, "autoSpaceDE": { "type": "boolean", "description": "Only for action 'set_flow_options'. Omit for other actions." }, "autoSpaceDN": { "type": "boolean", "description": "Only for action 'set_flow_options'. Omit for other actions." }, "adjustRightInd": { "type": "boolean", "description": "Only for action 'set_flow_options'. Omit for other actions." }, "snapToGrid": { "type": "boolean", "description": "Only for action 'set_flow_options'. Omit for other actions." }, "direction": { "type": "string", "enum": [ "ltr", "rtl" ], "description": "Required for action 'set_direction'." }, "alignmentPolicy": { "type": "string", "enum": [ "preserve", "matchDirection" ], "description": "Only for action 'set_direction'. Omit for other actions." } }, "required": [ "action" ], "additionalProperties": false, "$defs": { "HeadingAddress": { "type": "object", "properties": { "kind": { "const": "block", "type": "string" }, "nodeType": { "const": "heading", "type": "string" }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "ListItemAddress": { "type": "object", "properties": { "kind": { "const": "block", "type": "string" }, "nodeType": { "const": "listItem", "type": "string" }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "ParagraphAddress": { "type": "object", "properties": { "kind": { "const": "block", "type": "string" }, "nodeType": { "const": "paragraph", "type": "string" }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "SectionAddress": { "type": "object", "properties": { "kind": { "const": "section", "type": "string" }, "sectionId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "sectionId" ] }, "SelectionEdgeNodeAddress": { "type": "object", "properties": { "kind": { "const": "block", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableOfContents", "sdt", "image" ] }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "SelectionPoint": { "description": "A point in the document. Use {kind:'text', blockId, offset} for character positions or {kind:'nodeEdge', node:{kind:'block', nodeType, nodeId}, edge:'before'|'after'} for block boundaries.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "text", "type": "string" }, "blockId": { "type": "string" }, "offset": { "type": "integer", "minimum": 0 }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "blockId", "offset" ] }, { "type": "object", "properties": { "kind": { "const": "nodeEdge", "type": "string" }, "node": { "$ref": "#/$defs/SelectionEdgeNodeAddress" }, "edge": { "enum": [ "before", "after" ] } }, "additionalProperties": false, "required": [ "kind", "node", "edge" ] } ] }, "SelectionTarget": { "type": "object", "properties": { "kind": { "const": "selection", "type": "string" }, "start": { "$ref": "#/$defs/SelectionPoint" }, "end": { "$ref": "#/$defs/SelectionPoint" }, "story": { "$ref": "#/$defs/StoryLocator" }, "coordinateSpace": { "$ref": "#/$defs/TextCoordinateSpace" } }, "additionalProperties": false, "required": [ "kind", "start", "end" ] }, "StoryLocator": { "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "body", "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "headerFooterSlot", "type": "string" }, "section": { "$ref": "#/$defs/SectionAddress" }, "headerFooterKind": { "enum": [ "header", "footer" ] }, "variant": { "enum": [ "default", "first", "even" ] }, "resolution": { "enum": [ "effective", "explicit" ] }, "onWrite": { "enum": [ "materializeIfInherited", "editResolvedPart", "error" ] } }, "additionalProperties": false, "required": [ "kind", "storyType", "section", "headerFooterKind", "variant" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "headerFooterPart", "type": "string" }, "refId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "refId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "footnote", "type": "string" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "endnote", "type": "string" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "textbox", "type": "string" }, "textboxId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "textboxId" ] } ] }, "TextCoordinateSpace": { "enum": [ "visible", "tracked" ] } } }, "mutates": true, "operations": [ { "operationId": "doc.format.apply", "intentAction": "inline", "requiredOneOf": [ [ "target", "inline" ], [ "ref", "inline" ] ] }, { "operationId": "doc.styles.paragraph.setStyle", "intentAction": "set_style", "required": [ "target" ] }, { "operationId": "doc.styles.paragraph.setStyleRef", "intentAction": "set_style_ref", "required": [ "target", "styleId" ] }, { "operationId": "doc.format.paragraph.setAlignment", "intentAction": "set_alignment", "required": [ "target", "alignment" ] }, { "operationId": "doc.format.paragraph.setIndentation", "intentAction": "set_indentation", "required": [ "target" ] }, { "operationId": "doc.format.paragraph.setSpacing", "intentAction": "set_spacing", "required": [ "target" ] }, { "operationId": "doc.format.paragraph.setFlowOptions", "intentAction": "set_flow_options", "required": [ "target" ] }, { "operationId": "doc.format.paragraph.setDirection", "intentAction": "set_direction", "required": [ "target", "direction" ] } ] }, { "toolName": "superdoc_create", "description": "IMPORTANT: For headings and paragraphs, use superdoc_edit with type \"markdown\" instead: it is faster, creates proper styles, and handles positioning via target + placement. Only use superdoc_create for tables or when markdown cannot express the content. Creates a single paragraph, heading, or table. Returns nodeId, an opaque handle.ref for the created block, and evaluatedRevision. handle.ref works directly with superdoc_format (pass expectedRevision as evaluatedRevision to avoid REVISION_MISMATCH) and already carries its story, including for a header/footer block — no need to pass story separately. It is valid for ONE immediate follow-up call only; for anything after that, re-fetch blocks with superdoc_get_content to get a fresh ref. If \"text\" is empty, handle.ref spans no characters and cannot be used with superdoc_format action \"inline\" (it needs at least one character); use a block target with nodeId for paragraph-level actions like set_style or set_alignment instead. When the user asks for a \"heading\", use action \"heading\" with a level (default 1). Use action \"paragraph\" for regular body text. Position with \"at\": {kind:\"documentEnd\"} (default), {kind:\"documentStart\"}, or {kind:\"after\"/\"before\", target:{kind:\"block\", nodeType, nodeId}} for relative placement. When creating multiple items in sequence, use the previous response nodeId as the next \"at\" target to maintain correct ordering. Do NOT use newlines in \"text\" to create multiple paragraphs; call this tool separately for each one.\n\nEXAMPLES:\n 1. {\"action\":\"paragraph\",\"text\":\"New paragraph content.\",\"at\":{\"kind\":\"documentEnd\"}}\n 2. {\"action\":\"heading\",\"text\":\"Section Title\",\"level\":2,\"at\":{\"kind\":\"after\",\"target\":{\"kind\":\"block\",\"nodeType\":\"paragraph\",\"nodeId\":\"\"}}}\n 3. {\"action\":\"paragraph\",\"text\":\"Chained item.\",\"at\":{\"kind\":\"after\",\"target\":{\"kind\":\"block\",\"nodeType\":\"paragraph\",\"nodeId\":\"\"}}}\n 4. {\"action\":\"table\",\"rows\":3,\"columns\":4,\"at\":{\"kind\":\"documentEnd\"}}", "inputSchema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "heading", "paragraph", "table" ], "description": "The action to perform. One of: heading, paragraph, table." }, "force": { "type": "boolean", "description": "Bypass confirmation checks." }, "changeTag": { "type": "string", "description": "Caller correlation echoed only on this committed mutation; never stored in DOCX." }, "changeMode": { "type": "string", "description": "Edit mode: \"direct\" applies changes immediately, \"tracked\" records as suggestions." }, "dryRun": { "type": "boolean", "description": "Preview the result without applying changes." }, "in": { "$ref": "#/$defs/StoryLocator", "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes." }, "at": { "anyOf": [ { "description": "Position: {kind:'documentEnd'} to append, {kind:'documentStart'} to prepend, or {kind:'before'|'after', target:{kind:'block', nodeType:'...', nodeId:'...'}} for relative placement.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "documentStart", "type": "string" } }, "additionalProperties": false, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "const": "documentEnd", "type": "string" } }, "additionalProperties": false, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "const": "before", "type": "string" }, "target": { "$ref": "#/$defs/BlockNodeAddress" } }, "additionalProperties": false, "required": [ "kind", "target" ] }, { "type": "object", "properties": { "kind": { "const": "after", "type": "string" }, "target": { "$ref": "#/$defs/BlockNodeAddress" } }, "additionalProperties": false, "required": [ "kind", "target" ] } ] }, { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "documentStart", "type": "string" } }, "additionalProperties": false, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "const": "documentEnd", "type": "string" } }, "additionalProperties": false, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "const": "before", "type": "string" }, "target": { "$ref": "#/$defs/BlockNodeAddress" } }, "additionalProperties": false, "required": [ "kind", "target" ] }, { "type": "object", "properties": { "kind": { "const": "after", "type": "string" }, "target": { "$ref": "#/$defs/BlockNodeAddress" } }, "additionalProperties": false, "required": [ "kind", "target" ] }, { "type": "object", "properties": { "kind": { "const": "before", "type": "string" }, "nodeId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "nodeId" ] }, { "type": "object", "properties": { "kind": { "const": "after", "type": "string" }, "nodeId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "nodeId" ] }, { "type": "object", "properties": { "kind": { "const": "inParagraph", "type": "string" }, "target": { "$ref": "#/$defs/BlockNodeAddress" }, "offset": { "type": "integer", "minimum": 0 }, "coordinateSpace": { "enum": [ "visible", "tracked" ] } }, "additionalProperties": false, "required": [ "kind", "target", "offset" ] } ] } ], "description": "Position: {kind:'documentEnd'} to append, {kind:'documentStart'} to prepend, or {kind:'before'|'after', target:{kind:'block', nodeType:'...', nodeId:'...'}} for relative placement." }, "text": { "anyOf": [ { "type": "string", "description": "Paragraph text content. Each call creates ONE paragraph. For multiple items (e.g. list items), call superdoc_create separately for each item: do NOT use newlines to put multiple items in one paragraph." }, { "type": "string", "description": "Heading text content." } ], "description": "Paragraph text content. Each call creates ONE paragraph. For multiple items (e.g. list items), call superdoc_create separately for each item: do NOT use newlines to put multiple items in one paragraph." }, "styleId": { "anyOf": [ { "type": "string", "description": "Explicit paragraph style id (e.g. \"BodyText\") to apply instead of the default resolved from the anchor/document. An unknown style id fails with INVALID_INPUT and does not mutate the document." }, { "type": "string", "description": "Explicit paragraph style id to apply instead of the Heading{level} style normally derived from level. level still controls numbering suppression regardless of this override. An unknown style id fails with INVALID_INPUT and does not mutate the document." } ], "description": "Explicit paragraph style id (e.g. \"BodyText\") to apply instead of the default resolved from the anchor/document. An unknown style id fails with INVALID_INPUT and does not mutate the document." }, "input": { "anyOf": [ { "type": "object", "description": "Full paragraph input as JSON (alternative to individual text/at params)." }, { "type": "object", "description": "Full heading input as JSON (alternative to individual text/level/at params)." } ], "description": "Full paragraph input as JSON (alternative to individual text/at params)." }, "level": { "type": "integer", "minimum": 1, "maximum": 6, "description": "Heading level (1-6). Required for action 'heading'." }, "rows": { "type": "integer", "minimum": 1, "description": "Required for action 'table'." }, "columns": { "type": "integer", "minimum": 1, "description": "Required for action 'table'." } }, "required": [ "action" ], "additionalProperties": false, "$defs": { "BlockNodeAddress": { "type": "object", "properties": { "kind": { "const": "block", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt" ] }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "SectionAddress": { "type": "object", "properties": { "kind": { "const": "section", "type": "string" }, "sectionId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "sectionId" ] }, "StoryLocator": { "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "body", "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "headerFooterSlot", "type": "string" }, "section": { "$ref": "#/$defs/SectionAddress" }, "headerFooterKind": { "enum": [ "header", "footer" ] }, "variant": { "enum": [ "default", "first", "even" ] }, "resolution": { "enum": [ "effective", "explicit" ] }, "onWrite": { "enum": [ "materializeIfInherited", "editResolvedPart", "error" ] } }, "additionalProperties": false, "required": [ "kind", "storyType", "section", "headerFooterKind", "variant" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "headerFooterPart", "type": "string" }, "refId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "refId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "footnote", "type": "string" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "endnote", "type": "string" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "textbox", "type": "string" }, "textboxId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "textboxId" ] } ] } } }, "mutates": true, "operations": [ { "operationId": "doc.create.paragraph", "intentAction": "paragraph" }, { "operationId": "doc.create.heading", "intentAction": "heading", "required": [ "level" ] }, { "operationId": "doc.create.table", "intentAction": "table", "required": [ "rows", "columns" ] } ] }, { "toolName": "superdoc_list", "description": "Create and manipulate bullet and numbered lists. Most actions require a list-item target: {kind:\"block\", nodeType:\"listItem\", nodeId:\"\"}. Exceptions: \"create\" and \"attach\" operate on paragraph targets (they turn paragraphs into list items). Find nodeIds via superdoc_get_content({action:\"blocks\"}): pick listItem blocks for most actions, paragraph blocks for create/attach.\n\nCREATE & CONVERT:\n• \"create\": make a NEW list from paragraphs. Two modes: mode:\"empty\" with at:{kind:\"block\", nodeType:\"paragraph\", nodeId} converts a single paragraph; mode:\"fromParagraphs\" with target:{from:{...paragraph block address}, to:{...paragraph block address}} converts a range: ALL paragraphs between from and to become items, so make sure no other content sits between them. Pass a preset (\"disc\"|\"circle\"|\"square\"|\"dash\" for bullets; \"decimal\"|\"decimalParenthesis\"|\"lowerLetter\"|\"lowerLetterParenthesis\"|\"upperLetter\"|\"upperLetterParenthesis\"|\"lowerRoman\"|\"upperRoman\" for ordered) or a custom style. Use \"create\" to start a fresh list: NOT to extend an existing one (use \"attach\" for that).\n• \"attach\": add paragraphs to an EXISTING list, inheriting its numbering definition. Pass target:{paragraph block address} (or {from, to} range of paragraphs) + attachTo:{kind:\"block\", nodeType:\"listItem\", nodeId:\"\"} + optional level:0..8. Use this to extend a list or as the second half of a merge workflow (see \"join\" below).\n• \"set_type\": convert an existing list between ordered and bullet. Pass target:{listItem} + kind:\"ordered\" or \"bullet\". Adjacent compatible sequences are merged automatically to preserve continuous numbering.\n• \"detach\": convert a list item back to a plain paragraph. Pass target:{listItem}.\n\nITEMS & NESTING:\n• \"insert\": add a new list item adjacent to an existing item in the same list. Pass target:{listItem} + position:\"before\"|\"after\" + optional text. Use this (NOT superdoc_create) to add items to an existing list.\n• \"indent\" / \"outdent\": bump the target item's nesting level by one (0-8 range). Pass target:{listItem}.\n• \"set_level\": jump the target item to an explicit level. Pass target:{listItem} + level:0..8.\n\nNUMBERING (ordered lists):\n• \"set_value\": restart numbering at the target. Pass target:{listItem} + value: (e.g. value:1 to start over) or value:null to clear a previous override. Mid-sequence targets are atomically split off into their own sequence.\n• \"continue_previous\": make the target's sequence continue numbering from the nearest compatible previous sequence (same abstract definition). Pass target:{listItem of the sequence you want to renumber}. Fails with NO_COMPATIBLE_PREVIOUS or INCOMPATIBLE_DEFINITIONS if no matching prior sequence exists.\n\nSEQUENCE SHAPE (merge / split):\n• \"merge\": merge the target's sequence with an adjacent one into one continuous list. Pass target:{listItem} + direction:\"withPrevious\" or \"withNext\". Absorbed items adopt the absorbing sequence's numbering definition, and empty paragraphs between the two sequences are removed so numbering flows continuously.\n• \"split\": split the target's sequence at the target item into two independent lists. The target and everything after become a new sequence that restarts numbering at 1. Pass target:{listItem}; add restartNumbering:false to keep the count continuing instead of restarting.\n\nEXAMPLES:\n 1. {\"action\":\"create\",\"mode\":\"fromParagraphs\",\"preset\":\"disc\",\"target\":{\"from\":{\"kind\":\"block\",\"nodeType\":\"paragraph\",\"nodeId\":\"\"},\"to\":{\"kind\":\"block\",\"nodeType\":\"paragraph\",\"nodeId\":\"\"}}}\n 2. {\"action\":\"set_type\",\"target\":{\"kind\":\"block\",\"nodeType\":\"listItem\",\"nodeId\":\"\"},\"kind\":\"ordered\"}\n 3. {\"action\":\"insert\",\"target\":{\"kind\":\"block\",\"nodeType\":\"listItem\",\"nodeId\":\"\"},\"position\":\"after\",\"text\":\"New list item\"}\n 4. {\"action\":\"indent\",\"target\":{\"kind\":\"block\",\"nodeType\":\"listItem\",\"nodeId\":\"\"}}\n 5. {\"action\":\"merge\",\"target\":{\"kind\":\"block\",\"nodeType\":\"listItem\",\"nodeId\":\"\"},\"direction\":\"withPrevious\"}\n 6. {\"action\":\"split\",\"target\":{\"kind\":\"block\",\"nodeType\":\"listItem\",\"nodeId\":\"\"}}\n 7. {\"action\":\"set_value\",\"target\":{\"kind\":\"block\",\"nodeType\":\"listItem\",\"nodeId\":\"\"},\"value\":1}\n 8. {\"action\":\"continue_previous\",\"target\":{\"kind\":\"block\",\"nodeType\":\"listItem\",\"nodeId\":\"\"}}", "inputSchema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "attach", "continue_previous", "create", "delete", "detach", "indent", "insert", "merge", "outdent", "set_level", "set_type", "set_value", "split" ], "description": "The action to perform. One of: attach, continue_previous, create, delete, detach, indent, insert, merge, outdent, set_level, set_type, set_value, split." }, "force": { "type": "boolean", "description": "Bypass confirmation checks." }, "changeTag": { "type": "string", "description": "Caller correlation echoed only on this committed mutation; never stored in DOCX." }, "changeMode": { "type": "string", "description": "Edit mode: \"direct\" applies changes immediately, \"tracked\" records as suggestions." }, "dryRun": { "type": "boolean", "description": "Preview the result without applying changes." }, "target": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "$ref": "#/$defs/ListItemAddress", "description": "The target list item. For 'insert': the item to insert relative to. For 'create' with mode 'fromParagraphs': use nodeType 'paragraph' instead. Format: {kind:'block', nodeType:'listItem', nodeId:''}." }, { "$ref": "#/$defs/BlockAddressOrRange", "description": "Required when mode is 'fromParagraphs'. Each call converts ONE paragraph into a list item. To make a list with N items, create N separate paragraphs first, then call superdoc_list create for EACH one. Format: {kind:'block', nodeType:'paragraph', nodeId:''}." } ], "description": "The target list item. For 'insert': the item to insert relative to. For 'create' with mode 'fromParagraphs': use nodeType 'paragraph' instead. Format: {kind:'block', nodeType:'listItem', nodeId:''}." }, { "$ref": "#/$defs/BlockAddressOrRange" } ], "description": "The target list item. For 'insert': the item to insert relative to. For 'create' with mode 'fromParagraphs': use nodeType 'paragraph' instead. Format: {kind:'block', nodeType:'listItem', nodeId:''}." }, { "$ref": "#/$defs/ListItemAddress" } ], "description": "The target list item. For 'insert': the item to insert relative to. For 'create' with mode 'fromParagraphs': use nodeType 'paragraph' instead. Format: {kind:'block', nodeType:'listItem', nodeId:''}." }, { "$ref": "#/$defs/ListItemAddress" } ], "description": "The target list item. For 'insert': the item to insert relative to. For 'create' with mode 'fromParagraphs': use nodeType 'paragraph' instead. Format: {kind:'block', nodeType:'listItem', nodeId:''}." }, { "$ref": "#/$defs/ListItemAddress" } ], "description": "The target list item. For 'insert': the item to insert relative to. For 'create' with mode 'fromParagraphs': use nodeType 'paragraph' instead. Format: {kind:'block', nodeType:'listItem', nodeId:''}." }, { "$ref": "#/$defs/ListItemAddress" } ], "description": "The target list item. For 'insert': the item to insert relative to. For 'create' with mode 'fromParagraphs': use nodeType 'paragraph' instead. Format: {kind:'block', nodeType:'listItem', nodeId:''}." }, { "$ref": "#/$defs/ListItemAddress" } ], "description": "The target list item. For 'insert': the item to insert relative to. For 'create' with mode 'fromParagraphs': use nodeType 'paragraph' instead. Format: {kind:'block', nodeType:'listItem', nodeId:''}." }, { "$ref": "#/$defs/ListItemAddress" } ], "description": "The target list item. For 'insert': the item to insert relative to. For 'create' with mode 'fromParagraphs': use nodeType 'paragraph' instead. Format: {kind:'block', nodeType:'listItem', nodeId:''}." }, { "$ref": "#/$defs/ListItemAddress" } ], "description": "The target list item. For 'insert': the item to insert relative to. For 'create' with mode 'fromParagraphs': use nodeType 'paragraph' instead. Format: {kind:'block', nodeType:'listItem', nodeId:''}." }, { "$ref": "#/$defs/ListItemAddress" } ], "description": "The target list item. For 'insert': the item to insert relative to. For 'create' with mode 'fromParagraphs': use nodeType 'paragraph' instead. Format: {kind:'block', nodeType:'listItem', nodeId:''}." }, { "$ref": "#/$defs/ListItemAddress" } ], "description": "The target list item. For 'insert': the item to insert relative to. For 'create' with mode 'fromParagraphs': use nodeType 'paragraph' instead. Format: {kind:'block', nodeType:'listItem', nodeId:''}." }, { "$ref": "#/$defs/ListItemAddress" } ], "description": "The target list item. For 'insert': the item to insert relative to. For 'create' with mode 'fromParagraphs': use nodeType 'paragraph' instead. Format: {kind:'block', nodeType:'listItem', nodeId:''}. Required for actions 'insert', 'attach', 'detach', 'delete', 'indent', 'outdent', 'merge', 'split', 'set_level', 'set_value', 'continue_previous', 'set_type'." }, "position": { "enum": [ "before", "after" ], "description": "Required. Insert position relative to target: 'before' or 'after'. Required for action 'insert'." }, "text": { "type": "string", "description": "Text content for the new list item. Only for action 'insert'. Omit for other actions." }, "inheritFrom": { "$ref": "#/$defs/ListItemAddress", "description": "Optional same-story list item to inherit paragraph and run formatting from without changing placement or numbering. When omitted, existing paragraph-creation formatting behavior, including next-style handling, is preserved. Only for action 'insert'. Omit for other actions." }, "input": { "type": "object", "description": "Operation input as JSON object." }, "nodeId": { "type": "string", "description": "Node ID of the target list item." }, "mode": { "enum": [ "empty", "fromParagraphs" ], "description": "Required. 'fromParagraphs' converts existing paragraphs into list items: each paragraph becomes one item, so create one paragraph per item first. 'empty' creates a new empty list at 'at'. Required for action 'create'." }, "at": { "$ref": "#/$defs/BlockAddress", "description": "Required when mode is 'empty'. The paragraph to create the list at. Format: {kind:'block', nodeType:'paragraph', nodeId:''}. Only for action 'create'. Omit for other actions." }, "kind": { "enum": [ "ordered", "bullet" ], "description": "List type: 'bullet' for bullet points, 'ordered' for numbered lists. Required for action 'set_type'." }, "level": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 8, "description": "List nesting level (0-8). 0 is the top level." }, { "type": "integer", "minimum": 0, "maximum": 8 } ], "description": "List nesting level (0-8). 0 is the top level." }, { "type": "integer", "minimum": 0, "maximum": 8 } ], "description": "List nesting level (0-8). 0 is the top level. Required for action 'set_level'." }, "preset": { "enum": [ "decimal", "decimalParenthesis", "lowerLetter", "lowerLetterParenthesis", "upperLetter", "upperLetterParenthesis", "lowerRoman", "upperRoman", "disc", "circle", "square", "dash" ], "description": "Predefined list style preset. Overrides 'kind' with a specific numbering or bullet format. Only for action 'create'. Omit for other actions." }, "style": { "type": "object", "properties": { "version": { "const": 1, "type": "number" }, "levels": { "type": "array", "items": { "type": "object", "properties": { "level": { "type": "integer", "minimum": 0, "maximum": 8 }, "numFmt": { "type": "string" }, "lvlText": { "type": "string" }, "start": { "type": "integer" }, "alignment": { "enum": [ "left", "center", "right" ] }, "indents": { "type": "object", "properties": { "left": { "type": "integer" }, "hanging": { "type": "integer" }, "firstLine": { "type": "integer" } }, "additionalProperties": false }, "trailingCharacter": { "enum": [ "tab", "space", "nothing" ] }, "markerFont": { "type": "string" }, "pictureBulletId": { "type": "integer" }, "tabStopAt": { "type": [ "integer", "null" ] } }, "additionalProperties": false, "required": [ "level" ] } } }, "additionalProperties": false, "required": [ "version", "levels" ], "description": "Only for action 'create'. Omit for other actions." }, "sequence": { "oneOf": [ { "type": "object", "properties": { "mode": { "const": "new", "type": "string" }, "startAt": { "type": "integer", "minimum": 1 } }, "additionalProperties": false, "required": [ "mode" ] }, { "type": "object", "properties": { "mode": { "const": "continuePrevious", "type": "string" } }, "additionalProperties": false, "required": [ "mode" ] } ], "description": "Only for action 'create'. Omit for other actions." }, "attachTo": { "$ref": "#/$defs/ListItemAddress", "description": "Required for action 'attach'." }, "direction": { "enum": [ "withPrevious", "withNext" ], "description": "Required for action 'merge'." }, "restartNumbering": { "type": "boolean", "description": "Only for action 'split'. Omit for other actions." }, "value": { "type": [ "integer", "null" ], "description": "Required for action 'set_value'." }, "continuity": { "enum": [ "preserve", "none" ], "description": "Numbering continuity: 'preserve' keeps numbering; 'none' restarts. Only for action 'set_type'. Omit for other actions." } }, "required": [ "action" ], "additionalProperties": false, "$defs": { "BlockAddress": { "type": "object", "properties": { "kind": { "const": "block", "type": "string" }, "nodeType": { "const": "paragraph", "type": "string" }, "nodeId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "BlockAddressOrRange": { "oneOf": [ { "$ref": "#/$defs/BlockAddress" }, { "$ref": "#/$defs/BlockRange" } ] }, "BlockRange": { "type": "object", "properties": { "from": { "$ref": "#/$defs/BlockAddress" }, "to": { "$ref": "#/$defs/BlockAddress" } }, "additionalProperties": false, "required": [ "from", "to" ] }, "ListItemAddress": { "type": "object", "properties": { "kind": { "const": "block", "type": "string" }, "nodeType": { "const": "listItem", "type": "string" }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "SectionAddress": { "type": "object", "properties": { "kind": { "const": "section", "type": "string" }, "sectionId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "sectionId" ] }, "StoryLocator": { "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "body", "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "headerFooterSlot", "type": "string" }, "section": { "$ref": "#/$defs/SectionAddress" }, "headerFooterKind": { "enum": [ "header", "footer" ] }, "variant": { "enum": [ "default", "first", "even" ] }, "resolution": { "enum": [ "effective", "explicit" ] }, "onWrite": { "enum": [ "materializeIfInherited", "editResolvedPart", "error" ] } }, "additionalProperties": false, "required": [ "kind", "storyType", "section", "headerFooterKind", "variant" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "headerFooterPart", "type": "string" }, "refId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "refId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "footnote", "type": "string" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "endnote", "type": "string" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "textbox", "type": "string" }, "textboxId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "textboxId" ] } ] } } }, "mutates": true, "operations": [ { "operationId": "doc.lists.insert", "intentAction": "insert", "required": [ "target", "position" ] }, { "operationId": "doc.lists.create", "intentAction": "create", "required": [ "mode" ] }, { "operationId": "doc.lists.attach", "intentAction": "attach", "required": [ "target", "attachTo" ] }, { "operationId": "doc.lists.detach", "intentAction": "detach", "required": [ "target" ] }, { "operationId": "doc.lists.delete", "intentAction": "delete", "required": [ "target" ] }, { "operationId": "doc.lists.indent", "intentAction": "indent", "required": [ "target" ] }, { "operationId": "doc.lists.outdent", "intentAction": "outdent", "required": [ "target" ] }, { "operationId": "doc.lists.merge", "intentAction": "merge", "required": [ "target", "direction" ] }, { "operationId": "doc.lists.split", "intentAction": "split", "required": [ "target" ] }, { "operationId": "doc.lists.setLevel", "intentAction": "set_level", "required": [ "target", "level" ] }, { "operationId": "doc.lists.setValue", "intentAction": "set_value", "required": [ "target", "value" ] }, { "operationId": "doc.lists.continuePrevious", "intentAction": "continue_previous", "required": [ "target" ] }, { "operationId": "doc.lists.setType", "intentAction": "set_type", "required": [ "target", "kind" ] } ] }, { "toolName": "superdoc_comment", "description": "Manage document comment threads: create, read, update, and delete. To create a comment, first use superdoc_search to find the target text, then pass action \"create\" with the comment text and a target built from items[0].blocks. For a single-block match use {kind:\"text\", blockId: items[0].blocks[0].blockId, range: items[0].blocks[0].range}. For a cross-block match use {kind:\"text\", segments: items[0].blocks.map(b => ({blockId: b.blockId, range: b.range}))}. Do NOT use items[0].highlightRange (snippet-relative, not block-relative) or items[0].target (a SelectionTarget, not accepted by comments.create). For threaded replies, pass \"parentId\" with the parent comment ID. Action \"list\" returns all comments with optional pagination (limit, offset) and filtering (includeResolved:true to include resolved). Action \"get\" retrieves a single comment by ID. Action \"update\" changes comment text, re-anchors the thread, changes status to \"resolved\", or toggles the legacy `sdcom:internal` flag for v1 compatibility. Action \"delete\" removes a comment or reply by ID. Do NOT pass \"ref\", \"id\", or \"parentId\" when creating a new top-level comment; \"action\", \"text\", and \"target\" are required, while commentId (the v1 compatibility alias for externalId), externalId, author fields, and metadata are optional correlation fields.\n\nEXAMPLES:\n 1. {\"action\":\"create\",\"text\":\"Please review this section.\",\"target\":{\"kind\":\"text\",\"blockId\":\"\",\"range\":{\"start\":5,\"end\":25}}}\n 2. {\"action\":\"list\",\"limit\":20,\"offset\":0}\n 3. {\"action\":\"update\",\"id\":\"\",\"status\":\"resolved\"}\n 4. {\"action\":\"delete\",\"id\":\"\"}", "inputSchema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "create", "delete", "get", "list", "update" ], "description": "The action to perform. One of: create, delete, get, list, update." }, "force": { "type": "boolean", "description": "Bypass confirmation checks." }, "changeTag": { "type": "string", "description": "Caller correlation echoed only on this committed mutation; never stored in DOCX." }, "changeMode": { "type": "string", "description": "Edit mode: \"direct\" applies changes immediately, \"tracked\" records as suggestions." }, "text": { "anyOf": [ { "type": "string", "description": "Comment text content." }, { "type": "string", "description": "Updated comment text." } ], "description": "Comment text content. Required for action 'create'." }, "target": { "anyOf": [ { "description": "Text range to anchor the comment. Accepts either a single-block TextAddress {kind:'text', blockId, range}, a multi-segment TextTarget {kind:'text', segments:[{blockId, range}, ...]} for selections that span blocks, a SelectionTarget {kind:'selection', start, end} returned by query.match, a TextSearchCommentTarget {text, story?}, or a TrackedChangeCommentTarget ({kind:'trackedChange', trackedChangeId, side?} or {trackedChangeId, side?}) that names a logical tracked-change id as a convenience anchor .", "oneOf": [ { "$ref": "#/$defs/TextAddress" }, { "$ref": "#/$defs/TextTarget" }, { "$ref": "#/$defs/SelectionTarget" }, { "$ref": "#/$defs/CommentTrackedChangeTarget" }, { "type": "object", "properties": { "text": { "type": "string", "description": "Text to find and anchor the comment to. The adapter resolves the first body/story match." }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "text" ] } ] }, { "oneOf": [ { "$ref": "#/$defs/TextAddress" }, { "$ref": "#/$defs/SelectionTarget" }, { "$ref": "#/$defs/CommentTrackedChangeTarget" }, { "type": "object", "properties": { "text": { "type": "string", "description": "Text to find and anchor the comment to. The adapter resolves the first body/story match." }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "text" ] } ], "description": "New anchor for the comment. Accepts a plain TextAddress, a SelectionTarget {kind:'selection', start, end}, a TextSearchCommentTarget {text, story?}, or a TrackedChangeCommentTarget, with or without kind, that names a logical tracked-change id as a convenience re-anchor target ." } ], "description": "Text range to anchor the comment. Accepts either a single-block TextAddress {kind:'text', blockId, range}, a multi-segment TextTarget {kind:'text', segments:[{blockId, range}, ...]} for selections that span blocks, a SelectionTarget {kind:'selection', start, end} returned by query.match, a TextSearchCommentTarget {text, story?}, or a TrackedChangeCommentTarget ({kind:'trackedChange', trackedChangeId, side?} or {trackedChangeId, side?}) that names a logical tracked-change id as a convenience anchor . Only for actions 'create', 'update'. Omit for other actions." }, "trackedChangeId": { "type": "string", "description": "Compatibility shorthand for target: { trackedChangeId }. Used only when target is omitted. Only for action 'create'. Omit for other actions." }, "side": { "enum": [ "inserted", "deleted", "source", "destination" ], "description": "Optional side for the top-level trackedChangeId shorthand. Only for action 'create'. Omit for other actions." }, "story": { "$ref": "#/$defs/StoryLocator", "description": "Optional story for the top-level trackedChangeId shorthand. Only for action 'create'. Omit for other actions." }, "parentId": { "type": "string", "description": "Parent comment ID for creating a threaded reply. Only for action 'create'. Omit for other actions." }, "commentId": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Compatibility alias for externalId, matching the caller-supplied commentId accepted by the v1 editor. V2 still generates a separate Word-compatible commentId. Only for action 'create'. Omit for other actions." }, "externalId": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Caller-owned durable, document-unique integration id. Kept separate from the generated Word-compatible commentId. Only for action 'create'. Omit for other actions." }, "author": { "type": "string", "minLength": 1, "description": "Author display name. Defaults to the configured session author. Only for action 'create'. Omit for other actions." }, "authorId": { "type": "string", "minLength": 1, "description": "Stable caller-owned author id. Only for action 'create'. Omit for other actions." }, "authorEmail": { "type": "string", "minLength": 1, "description": "Caller-owned author email. Only for action 'create'. Omit for other actions." }, "authorImage": { "type": "string", "minLength": 1, "description": "Caller-owned author image URL. Only for action 'create'. Omit for other actions." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Caller-owned JSON metadata persisted with the comment. Only for action 'create'. Omit for other actions." }, "id": { "type": "string", "description": "Required for actions 'delete', 'get'." }, "status": { "enum": [ "resolved", "active" ], "description": "Set comment status. Use 'resolved' to resolve a comment, or 'active' to reopen a previously resolved comment (lifecycle inverse). Only for action 'update'. Omit for other actions." }, "isInternal": { "type": "boolean", "description": "Legacy v1/document-api compatibility field. V2 adapters set or clear the target comment `sdcom:internal` attribute and preserve the field in the schema so v1 callers keep their input shape. Only for action 'update'. Omit for other actions." }, "includeResolved": { "type": "boolean", "description": "When true, includes resolved comments in results. Default: false. Only for action 'list'. Omit for other actions." }, "limit": { "type": "integer", "description": "Maximum number of comments to return. Only for action 'list'. Omit for other actions." }, "offset": { "type": "integer", "description": "Number of comments to skip for pagination. Only for action 'list'. Omit for other actions." } }, "required": [ "action" ], "additionalProperties": false, "$defs": { "CommentTrackedChangeTarget": { "type": "object", "properties": { "kind": { "const": "trackedChange", "description": "Optional discriminator. Omit it for the Labs-compatible { trackedChangeId } shape.", "type": "string" }, "trackedChangeId": { "type": "string" }, "side": { "enum": [ "inserted", "deleted", "source", "destination" ], "description": "Which revision side to anchor the comment on. Optional for grouped replacements (defaults to inserted) and paired moves (defaults to destination); required for separate replacements where both sides are reviewed independently." }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "trackedChangeId" ] }, "Range": { "type": "object", "properties": { "start": { "type": "integer" }, "end": { "type": "integer" } }, "additionalProperties": false, "required": [ "start", "end" ] }, "SectionAddress": { "type": "object", "properties": { "kind": { "const": "section", "type": "string" }, "sectionId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "sectionId" ] }, "SelectionEdgeNodeAddress": { "type": "object", "properties": { "kind": { "const": "block", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableOfContents", "sdt", "image" ] }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "SelectionPoint": { "description": "A point in the document. Use {kind:'text', blockId, offset} for character positions or {kind:'nodeEdge', node:{kind:'block', nodeType, nodeId}, edge:'before'|'after'} for block boundaries.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "text", "type": "string" }, "blockId": { "type": "string" }, "offset": { "type": "integer", "minimum": 0 }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "blockId", "offset" ] }, { "type": "object", "properties": { "kind": { "const": "nodeEdge", "type": "string" }, "node": { "$ref": "#/$defs/SelectionEdgeNodeAddress" }, "edge": { "enum": [ "before", "after" ] } }, "additionalProperties": false, "required": [ "kind", "node", "edge" ] } ] }, "SelectionTarget": { "type": "object", "properties": { "kind": { "const": "selection", "type": "string" }, "start": { "$ref": "#/$defs/SelectionPoint" }, "end": { "$ref": "#/$defs/SelectionPoint" }, "story": { "$ref": "#/$defs/StoryLocator" }, "coordinateSpace": { "$ref": "#/$defs/TextCoordinateSpace" } }, "additionalProperties": false, "required": [ "kind", "start", "end" ] }, "StoryLocator": { "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "body", "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "headerFooterSlot", "type": "string" }, "section": { "$ref": "#/$defs/SectionAddress" }, "headerFooterKind": { "enum": [ "header", "footer" ] }, "variant": { "enum": [ "default", "first", "even" ] }, "resolution": { "enum": [ "effective", "explicit" ] }, "onWrite": { "enum": [ "materializeIfInherited", "editResolvedPart", "error" ] } }, "additionalProperties": false, "required": [ "kind", "storyType", "section", "headerFooterKind", "variant" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "headerFooterPart", "type": "string" }, "refId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "refId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "footnote", "type": "string" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "endnote", "type": "string" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "textbox", "type": "string" }, "textboxId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "textboxId" ] } ] }, "TextAddress": { "type": "object", "properties": { "kind": { "const": "text", "type": "string" }, "blockId": { "type": "string" }, "range": { "$ref": "#/$defs/Range" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "blockId", "range" ] }, "TextCoordinateSpace": { "enum": [ "visible", "tracked" ] }, "TextSegment": { "type": "object", "properties": { "blockId": { "type": "string" }, "range": { "$ref": "#/$defs/Range" } }, "additionalProperties": false, "required": [ "blockId", "range" ] }, "TextTarget": { "type": "object", "properties": { "kind": { "const": "text", "type": "string" }, "segments": { "type": "array", "items": { "$ref": "#/$defs/TextSegment" }, "minItems": 1 }, "story": { "$ref": "#/$defs/StoryLocator" }, "coordinateSpace": { "$ref": "#/$defs/TextCoordinateSpace" } }, "additionalProperties": false, "required": [ "kind", "segments" ] } } }, "mutates": true, "operations": [ { "operationId": "doc.comments.create", "intentAction": "create", "required": [ "text" ] }, { "operationId": "doc.comments.patch", "intentAction": "update" }, { "operationId": "doc.comments.delete", "intentAction": "delete", "required": [ "id" ] }, { "operationId": "doc.comments.get", "intentAction": "get", "required": [ "id" ] }, { "operationId": "doc.comments.list", "intentAction": "list" } ] }, { "toolName": "superdoc_track_changes", "description": "Review and resolve tracked changes (insertions, deletions, replacements, format changes) in the document. Action \"list\" returns all tracked changes with optional filtering by type (insert, delete, replacement, format) and pagination (limit, offset). Each change includes an ID, type, author, timestamp, and content preview. Action \"decide\" accepts or rejects changes. Pass decision:\"accept\" to apply the change permanently, or decision:\"reject\" to discard it. Target a single change with {id:\"\"}, several whole changes atomically with {kind:\"ids\", ids:[...]}, a partial selection with {kind:\"range\", range:{...}}, or all changes at once with {scope:\"all\"} (optionally plus story). Do NOT use this tool unless the document has tracked changes. Use superdoc_get_content info to check the tracked change count first.\n\nEXAMPLES:\n 1. {\"action\":\"list\"}\n 2. {\"action\":\"list\",\"type\":\"insertion\",\"limit\":10}\n 3. {\"action\":\"list\",\"type\":\"replacement\",\"limit\":10}\n 4. {\"action\":\"decide\",\"decision\":\"accept\",\"target\":{\"id\":\"\"}}\n 5. {\"action\":\"decide\",\"decision\":\"accept\",\"target\":{\"kind\":\"ids\",\"ids\":[\"\",\"\"]}}\n 6. {\"action\":\"decide\",\"decision\":\"reject\",\"target\":{\"kind\":\"range\",\"range\":{\"kind\":\"text\",\"segments\":[{\"blockId\":\"\",\"range\":{\"start\":0,\"end\":5}}]}}}\n 7. {\"action\":\"decide\",\"decision\":\"reject\",\"target\":{\"scope\":\"all\"}}", "inputSchema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "decide", "list" ], "description": "The action to perform. One of: decide, list." }, "limit": { "type": "integer", "description": "Maximum number of tracked changes to return. Only for action 'list'. Omit for other actions." }, "offset": { "type": "integer", "description": "Number of tracked changes to skip for pagination. Only for action 'list'. Omit for other actions." }, "type": { "enum": [ "insertion", "deletion", "replacement", "formatting", "move", "structural", "insert", "delete", "format" ], "description": "Filter by change type. Canonical values: 'insertion', 'deletion', 'replacement', 'formatting', 'move', 'structural'. Legacy aliases 'insert', 'delete', and 'format' remain accepted during migration. Only for action 'list'. Omit for other actions." }, "in": { "oneOf": [ { "$ref": "#/$defs/StoryLocator" }, { "const": "all", "type": "string" } ], "description": "Story scope. Omit for body only, pass a StoryLocator for a single story, or 'all' for body + every revision-capable non-body story. Only for action 'list'. Omit for other actions." }, "force": { "type": "boolean", "description": "Bypass confirmation checks. Only for action 'decide'. Omit for other actions." }, "changeTag": { "type": "string", "description": "Caller correlation echoed only on this committed mutation; never stored in DOCX. Only for action 'decide'. Omit for other actions." }, "changeMode": { "type": "string", "description": "Edit mode: \"direct\" applies changes immediately, \"tracked\" records as suggestions. Only for action 'decide'. Omit for other actions." }, "decision": { "enum": [ "accept", "reject" ], "description": "Required for action 'decide'." }, "commentRetention": { "const": "point", "type": "string", "description": "Keep erased comment anchors as points instead of deleting their threads. Only for action 'decide'. Omit for other actions." }, "expectedRevision": { "type": "string", "description": "Backward-compatible alias for options.expectedRevision. Explicit mutation options take precedence when both are supplied. Only for action 'decide'. Omit for other actions." }, "target": { "description": "Decision target. Canonical shapes: { kind: 'id', id, story? } (one whole logical tracked change), { kind: 'ids', ids } (several whole logical tracked changes in one atomic history unit), { kind: 'range', range: TextTarget, coordinateSpace?, overlap?, side?, story?, part? } or { kind: 'range', range: { anchor, relativeStart, relativeEnd }, overlap?, side?, story?, part? } (resolves only the selected overlap; may split fragments), { kind: 'all' } (every active tracked change). Legacy { id, story? } / { id, range: { kind: 'partial', start, end } } / { scope: 'all' } shapes are accepted and transparently promoted to canonical targets. Required for action 'decide'.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "id", "type": "string" }, "id": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" }, "side": { "enum": [ "insert", "inserted", "delete", "deleted" ] }, "moveRole": { "enum": [ "pair", "source", "destination" ], "description": "Optional move pairing assertion. 'pair' requires the resolved tracked change to be a paired move; 'source' / 'destination' further narrow to a specific half. When the assertion does not hold the decide adapter fails closed." } }, "additionalProperties": false, "required": [ "kind", "id" ] }, { "type": "object", "properties": { "kind": { "const": "ids", "type": "string" }, "ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Logical tracked-change ids resolved atomically in one decision and history unit." } }, "additionalProperties": false, "required": [ "kind", "ids" ] }, { "type": "object", "properties": { "kind": { "const": "range", "type": "string" }, "range": { "$ref": "#/$defs/TextTarget" }, "coordinateSpace": { "enum": [ "visible", "tracked" ], "description": "Coordinate space of the TextTarget offsets. Omitted preserves legacy tracked-space behavior." }, "overlap": { "type": "string", "description": "Optional logical overlap selector for callers that already resolved an ambiguous overlap surface. Adapter-owned interpretation." }, "side": { "enum": [ "insert", "inserted", "delete", "deleted", "source", "destination" ], "description": "Optional revision side for grouped replacement or move targets." }, "story": { "$ref": "#/$defs/StoryLocator", "description": "Optional story containing the range target." }, "part": { "type": "string", "description": "Compatibility alias used by older range callers; interpretation is adapter-owned." } }, "additionalProperties": false, "required": [ "kind", "range" ] }, { "type": "object", "properties": { "kind": { "const": "range", "type": "string" }, "range": { "type": "object", "properties": { "anchor": { "type": "string" }, "relativeStart": { "type": "integer", "minimum": 0 }, "relativeEnd": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "anchor", "relativeStart", "relativeEnd" ] }, "overlap": { "type": "string", "description": "Optional logical overlap selector for callers that already resolved an ambiguous overlap surface. Adapter-owned interpretation." }, "side": { "enum": [ "insert", "inserted", "delete", "deleted", "source", "destination" ], "description": "Optional revision side for grouped replacement or move targets." }, "story": { "$ref": "#/$defs/StoryLocator", "description": "Optional story containing the range target." }, "part": { "type": "string", "description": "Compatibility alias used by older range callers; interpretation is adapter-owned." } }, "additionalProperties": false, "required": [ "kind", "range" ] }, { "type": "object", "properties": { "kind": { "const": "range", "type": "string" }, "anchor": { "type": "string" }, "relativeStart": { "type": "integer", "minimum": 0 }, "relativeEnd": { "type": "integer", "minimum": 0 }, "overlap": { "type": "string", "description": "Optional logical overlap selector for callers that already resolved an ambiguous overlap surface. Adapter-owned interpretation." }, "side": { "enum": [ "insert", "inserted", "delete", "deleted", "source", "destination" ], "description": "Optional revision side for grouped replacement or move targets." }, "story": { "$ref": "#/$defs/StoryLocator", "description": "Optional story containing the range target." }, "part": { "type": "string", "description": "Compatibility alias used by older range callers; interpretation is adapter-owned." } }, "additionalProperties": false, "required": [ "kind", "anchor", "relativeStart", "relativeEnd" ] }, { "type": "object", "properties": { "kind": { "const": "all", "type": "string" }, "story": { "oneOf": [ { "$ref": "#/$defs/StoryLocator" }, { "const": "all", "type": "string" } ], "description": "Optional explicit bulk filter. Omit or pass 'all' to target every revision-capable story, or pass a StoryLocator to scope the decision to one story." } }, "additionalProperties": false, "required": [ "kind" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" }, "moveRole": { "enum": [ "pair", "source", "destination" ], "description": "Optional move pairing assertion. 'pair' requires the resolved tracked change to be a paired move; 'source' / 'destination' further narrow to a specific half. When the assertion does not hold the decide adapter fails closed." } }, "additionalProperties": false, "required": [ "id" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "range": { "type": "object", "properties": { "kind": { "const": "partial", "type": "string" }, "start": { "type": "integer", "minimum": 0 }, "end": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "kind", "start", "end" ] }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "id", "range" ] }, { "type": "object", "properties": { "scope": { "enum": [ "all" ] }, "story": { "oneOf": [ { "$ref": "#/$defs/StoryLocator" }, { "const": "all", "type": "string" } ], "description": "Optional explicit bulk filter. Omit or pass 'all' to target every revision-capable story, or pass a StoryLocator to scope the decision to one story." } }, "additionalProperties": false, "required": [ "scope" ] } ] } }, "required": [ "action" ], "additionalProperties": false, "$defs": { "Range": { "type": "object", "properties": { "start": { "type": "integer" }, "end": { "type": "integer" } }, "additionalProperties": false, "required": [ "start", "end" ] }, "SectionAddress": { "type": "object", "properties": { "kind": { "const": "section", "type": "string" }, "sectionId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "sectionId" ] }, "StoryLocator": { "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "body", "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "headerFooterSlot", "type": "string" }, "section": { "$ref": "#/$defs/SectionAddress" }, "headerFooterKind": { "enum": [ "header", "footer" ] }, "variant": { "enum": [ "default", "first", "even" ] }, "resolution": { "enum": [ "effective", "explicit" ] }, "onWrite": { "enum": [ "materializeIfInherited", "editResolvedPart", "error" ] } }, "additionalProperties": false, "required": [ "kind", "storyType", "section", "headerFooterKind", "variant" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "headerFooterPart", "type": "string" }, "refId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "refId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "footnote", "type": "string" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "endnote", "type": "string" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "textbox", "type": "string" }, "textboxId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "textboxId" ] } ] }, "TextCoordinateSpace": { "enum": [ "visible", "tracked" ] }, "TextSegment": { "type": "object", "properties": { "blockId": { "type": "string" }, "range": { "$ref": "#/$defs/Range" } }, "additionalProperties": false, "required": [ "blockId", "range" ] }, "TextTarget": { "type": "object", "properties": { "kind": { "const": "text", "type": "string" }, "segments": { "type": "array", "items": { "$ref": "#/$defs/TextSegment" }, "minItems": 1 }, "story": { "$ref": "#/$defs/StoryLocator" }, "coordinateSpace": { "$ref": "#/$defs/TextCoordinateSpace" } }, "additionalProperties": false, "required": [ "kind", "segments" ] } } }, "mutates": true, "operations": [ { "operationId": "doc.trackChanges.list", "intentAction": "list" }, { "operationId": "doc.trackChanges.decide", "intentAction": "decide", "required": [ "decision", "target" ] } ] }, { "toolName": "superdoc_search", "description": "Find text patterns or nodes in the document and get ref handles for targeting edits and formatting. Refs expire after any mutation that changes the document. Re-search before the next edit when using individual tools (superdoc_edit, superdoc_format). Within a superdoc_mutations batch, selectors in \"where\" clauses resolve automatically at compile time; no manual re-searching needed between steps. Text search returns handle.ref covering only the matched substring. Node search finds blocks by type (paragraph, heading, table, listItem, etc.). The \"require\" parameter controls match cardinality: \"first\" returns one match, \"last\" returns the final match (without limit/offset), \"all\" returns every match, \"exactlyOne\" fails if not exactly one match. Supports scoping via \"within\" to search inside a single block. Patterns are plain text by default; pass select.mode: \"regex\" for regular-expression search (g/gi semantics, 1024-char cap, no wholeWord, capture groups returned on matches). Invalid or unsafe patterns fail with INVALID_INPUT. Do NOT use markdown formatting markers (#, **, etc.) in search patterns. Do NOT use this tool when you already have a ref from superdoc_get_content blocks or superdoc_create; use that ref directly.\n\nEXAMPLES:\n 1. {\"select\":{\"type\":\"text\",\"pattern\":\"Introduction\"},\"require\":\"first\"}\n 2. {\"select\":{\"type\":\"text\",\"pattern\":\"total amount\"},\"require\":\"all\"}\n 3. {\"select\":{\"type\":\"node\",\"nodeType\":\"heading\"},\"require\":\"all\"}\n 4. {\"select\":{\"type\":\"text\",\"pattern\":\"contract\"},\"within\":{\"kind\":\"block\",\"nodeType\":\"paragraph\",\"nodeId\":\"abc123\"},\"require\":\"first\"}", "inputSchema": { "type": "object", "properties": { "in": { "$ref": "#/$defs/StoryLocator", "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes." }, "select": { "description": "Search selector. Use {type:'text', pattern:'...'} for text search or {type:'node', nodeType:'paragraph'|'heading'|...} for node search.", "oneOf": [ { "type": "object", "properties": { "type": { "const": "text", "description": "Must be 'text' for text pattern search.", "type": "string" }, "pattern": { "type": "string", "description": "Text to match. In regex mode, patterns are validated for syntax, maximum length, and safety before execution." }, "mode": { "enum": [ "contains", "regex" ], "description": "Match mode: 'contains' (literal substring, recommended for literal text) or 'regex' (validated regular expression)." }, "caseSensitive": { "type": "boolean", "description": "Case-sensitive matching. Default: false." }, "wholeWord": { "type": "boolean", "description": "Require word-boundary matches. Default: false." }, "includeDeletedText": { "type": "boolean", "description": "When true, includes text from pending tracked deletions. Default: false." } }, "additionalProperties": false, "required": [ "type", "pattern" ] }, { "type": "object", "properties": { "type": { "const": "node", "description": "Must be 'node' for node type search.", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt", "run", "bookmark", "comment", "hyperlink", "footnoteRef", "endnoteRef", "crossRef", "indexEntry", "citation", "authorityEntry", "sequenceField", "tab", "lineBreak" ], "description": "Block type to match (paragraph, heading, table, listItem, etc.)." }, "kind": { "enum": [ "block", "inline" ], "description": "Filter: 'block' or 'inline'." } }, "additionalProperties": false, "required": [ "type" ] } ] }, "within": { "$ref": "#/$defs/BlockNodeAddress", "description": "Limit search scope to within a specific block: {kind:'block', nodeType:'...', nodeId:'...'}." }, "require": { "enum": [ "any", "first", "last", "exactlyOne", "all" ], "description": "Match cardinality: 'any' (all matches), 'first' (only first), 'last' (final scoped match, without limit/offset), 'exactlyOne' (fail if != 1), 'all' (fail if 0). For 'last', page.offset reports the selected match's ordinal in the full set." }, "mode": { "enum": [ "strict", "candidates" ], "description": "Search mode: 'strict' (default, exact matching) or 'candidates' (returns scored potential matches)." }, "includeNodes": { "type": "boolean", "description": "When true, includes full node data in results. Default: false." }, "limit": { "type": "integer", "minimum": 1, "description": "Maximum number of matches to return." }, "offset": { "type": "integer", "minimum": 0, "description": "Number of matches to skip for pagination." } }, "required": [ "select" ], "additionalProperties": false, "$defs": { "BlockNodeAddress": { "type": "object", "properties": { "kind": { "const": "block", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt" ] }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "SectionAddress": { "type": "object", "properties": { "kind": { "const": "section", "type": "string" }, "sectionId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "sectionId" ] }, "StoryLocator": { "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "body", "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "headerFooterSlot", "type": "string" }, "section": { "$ref": "#/$defs/SectionAddress" }, "headerFooterKind": { "enum": [ "header", "footer" ] }, "variant": { "enum": [ "default", "first", "even" ] }, "resolution": { "enum": [ "effective", "explicit" ] }, "onWrite": { "enum": [ "materializeIfInherited", "editResolvedPart", "error" ] } }, "additionalProperties": false, "required": [ "kind", "storyType", "section", "headerFooterKind", "variant" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "headerFooterPart", "type": "string" }, "refId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "refId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "footnote", "type": "string" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "endnote", "type": "string" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "textbox", "type": "string" }, "textboxId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "textboxId" ] } ] } } }, "mutates": false, "operations": [ { "operationId": "doc.query.match", "intentAction": "match", "required": [ "select" ] } ] }, { "toolName": "superdoc_mutations", "description": "All steps succeed or all fail; no partial application. Execute multiple operations atomically in one batch. Use this for any workflow needing 2+ changes. Supported step types: text (text.rewrite, text.insert, text.delete), format (format.apply), create (create.heading, create.paragraph, create.table), assert. Each step has an id, an op, a \"where\" clause for targeting ({by:\"select\", select:{...}, require:\"first\"|\"exactlyOne\"|\"all\"} or {by:\"ref\", ref:\"...\"} or {by:\"block\", nodeType:\"paragraph\", nodeId:\"...\"}), and \"args\" with operation-specific parameters. Use {by:\"block\", nodeType, nodeId} when you want to rewrite, delete, format, or anchor against a whole known block from superdoc_get_content action \"blocks\" without relying on text matching. For full-paragraph or full-clause rewrites, first call superdoc_get_content with action:\"blocks\" and includeText:true, then rewrite the matching block by nodeId. For a placeholder or name within a tab-separated paragraph, use a text.rewrite where.by:\"select\" targeting only the exact placeholder; a whole-block plain-text rewrite omitting tabs deletes those controls. Use {by:\"select\"} only for substring edits, discovery, or insertion relative to a sentence fragment; do NOT use a shortened text selector to replace an entire known block. For create steps, \"where\" targets an existing anchor block and args.position (\"before\" or \"after\") controls placement. Sequential creates targeting the same anchor maintain correct order via internal position mapping. For format.apply with require \"all\", use a node selector to format every heading or paragraph at once: {by:\"select\", select:{type:\"node\", nodeType:\"heading\"}, require:\"all\"}. Selectors resolve at compile time (before execution). This means format.apply steps CANNOT target content created by earlier create steps in the same batch. Split creates and formatting into separate batches: first a mutations call with creates, then a mutations call with format.apply. Action \"preview\" dry-runs the plan. Action \"apply\" executes it. If a selector matches nothing, the failure reports the step id plus selector details so you can retry with a shorter or more distinctive anchor. Do NOT create two steps that target overlapping text in the same block; combine them into a single text.rewrite step.\n\nEXAMPLES:\n 1. {\"action\":\"apply\",\"atomic\":true,\"changeMode\":\"direct\",\"steps\":[{\"id\":\"s1\",\"op\":\"text.rewrite\",\"where\":{\"by\":\"select\",\"select\":{\"type\":\"text\",\"pattern\":\"old term\"},\"require\":\"all\"},\"args\":{\"replacement\":{\"text\":\"new term\"}}},{\"id\":\"s2\",\"op\":\"text.delete\",\"where\":{\"by\":\"select\",\"select\":{\"type\":\"text\",\"pattern\":\" (deprecated)\"},\"require\":\"all\"},\"args\":{}}]}\n 2. {\"action\":\"apply\",\"steps\":[{\"id\":\"r1\",\"op\":\"text.rewrite\",\"where\":{\"by\":\"block\",\"nodeType\":\"paragraph\",\"nodeId\":\"\"},\"args\":{\"replacement\":{\"text\":\"Updated clause text.\"}}},{\"id\":\"f1\",\"op\":\"format.apply\",\"where\":{\"by\":\"select\",\"select\":{\"type\":\"node\",\"nodeType\":\"heading\"},\"require\":\"all\"},\"args\":{\"inline\":{\"color\":\"#FF0000\"}}},{\"id\":\"f2\",\"op\":\"format.apply\",\"where\":{\"by\":\"select\",\"select\":{\"type\":\"text\",\"pattern\":\"Confidential Information\"},\"require\":\"all\"},\"args\":{\"inline\":{\"bold\":true}}}]}", "inputSchema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "apply", "preview" ], "description": "The action to perform. One of: apply, preview." }, "in": { "$ref": "#/$defs/StoryLocator", "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes." }, "expectedRevision": { "type": "string", "description": "Document revision for optimistic concurrency. Mutation fails if document was modified since this revision. Only for action 'preview'. Omit for other actions." }, "atomic": { "const": true, "type": "boolean", "description": "Must be true. All steps execute as one atomic transaction." }, "changeMode": { "enum": [ "direct", "tracked" ], "description": "Required. Use 'direct' for immediate edits or 'tracked' for suggestions. Must always be provided." }, "steps": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "op": { "const": "text.rewrite", "type": "string" }, "where": { "oneOf": [ { "type": "object", "properties": { "by": { "const": "select", "type": "string" }, "select": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "text", "description": "Must be 'text' for text pattern search.", "type": "string" }, "pattern": { "type": "string", "description": "Text to match. In regex mode, patterns are validated for syntax, maximum length, and safety before execution." }, "mode": { "enum": [ "contains", "regex" ], "description": "Match mode: 'contains' (literal substring, recommended for literal text) or 'regex' (validated regular expression)." }, "caseSensitive": { "type": "boolean", "description": "Case-sensitive matching. Default: false." }, "wholeWord": { "type": "boolean", "description": "Require word-boundary matches. Default: false." }, "includeDeletedText": { "type": "boolean", "description": "When true, includes text from pending tracked deletions. Default: false." } }, "additionalProperties": false, "required": [ "type", "pattern" ] }, { "type": "object", "properties": { "type": { "const": "node", "description": "Must be 'node' for node type search.", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt", "run", "bookmark", "comment", "hyperlink", "footnoteRef", "endnoteRef", "crossRef", "indexEntry", "citation", "authorityEntry", "sequenceField", "tab", "lineBreak" ], "description": "Block type to match (paragraph, heading, table, listItem, etc.)." }, "kind": { "enum": [ "block", "inline" ], "description": "Filter: 'block' or 'inline'." } }, "additionalProperties": false, "required": [ "type" ] } ] }, "within": { "$ref": "#/$defs/BlockNodeAddress" }, "require": { "enum": [ "first", "exactlyOne", "all" ] } }, "additionalProperties": false, "required": [ "by", "select", "require" ] }, { "type": "object", "properties": { "by": { "const": "ref", "type": "string" }, "ref": { "type": "string" }, "within": { "$ref": "#/$defs/BlockNodeAddress" } }, "additionalProperties": false, "required": [ "by", "ref" ] }, { "type": "object", "properties": { "by": { "const": "target", "type": "string" }, "target": { "$ref": "#/$defs/SelectionTarget" } }, "additionalProperties": false, "required": [ "by", "target" ] }, { "type": "object", "properties": { "by": { "const": "block", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt" ] }, "nodeId": { "type": "string" } }, "additionalProperties": false, "required": [ "by", "nodeType", "nodeId" ] } ] }, "args": { "type": "object", "properties": { "replacement": { "oneOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "additionalProperties": false, "required": [ "text" ] }, { "type": "object", "properties": { "blocks": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" } }, "additionalProperties": false, "required": [ "text" ] } } }, "additionalProperties": false, "required": [ "blocks" ] } ] }, "replacementMode": { "enum": [ "literal", "regex-template" ], "type": "string" }, "caseHandling": { "enum": [ "exact", "preserve-match" ], "type": "string" }, "style": { "type": "object", "properties": { "inline": { "type": "object", "properties": { "mode": { "enum": [ "preserve", "set", "clear", "merge" ], "type": "string" }, "requireUniform": { "type": "boolean" }, "onNonUniform": { "enum": [ "error", "useLeadingRun", "majority", "union" ] }, "setMarks": { "type": "object", "properties": { "bold": { "enum": [ "on", "off", "clear" ] }, "italic": { "enum": [ "on", "off", "clear" ] }, "underline": { "enum": [ "on", "off", "clear" ] }, "strike": { "enum": [ "on", "off", "clear" ] } }, "additionalProperties": false } }, "additionalProperties": false, "required": [ "mode" ] }, "paragraph": { "type": "object", "properties": { "mode": { "enum": [ "preserve", "set", "clear" ], "type": "string" } }, "additionalProperties": false, "required": [ "mode" ] } }, "additionalProperties": false, "required": [ "inline" ] } }, "additionalProperties": false, "required": [ "replacement" ] } }, "additionalProperties": false, "required": [ "id", "op", "where", "args" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "op": { "const": "text.insert", "type": "string" }, "where": { "oneOf": [ { "type": "object", "properties": { "by": { "const": "select", "type": "string" }, "select": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "text", "description": "Must be 'text' for text pattern search.", "type": "string" }, "pattern": { "type": "string", "description": "Text to match. In regex mode, patterns are validated for syntax, maximum length, and safety before execution." }, "mode": { "enum": [ "contains", "regex" ], "description": "Match mode: 'contains' (literal substring, recommended for literal text) or 'regex' (validated regular expression)." }, "caseSensitive": { "type": "boolean", "description": "Case-sensitive matching. Default: false." }, "wholeWord": { "type": "boolean", "description": "Require word-boundary matches. Default: false." }, "includeDeletedText": { "type": "boolean", "description": "When true, includes text from pending tracked deletions. Default: false." } }, "additionalProperties": false, "required": [ "type", "pattern" ] }, { "type": "object", "properties": { "type": { "const": "node", "description": "Must be 'node' for node type search.", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt", "run", "bookmark", "comment", "hyperlink", "footnoteRef", "endnoteRef", "crossRef", "indexEntry", "citation", "authorityEntry", "sequenceField", "tab", "lineBreak" ], "description": "Block type to match (paragraph, heading, table, listItem, etc.)." }, "kind": { "enum": [ "block", "inline" ], "description": "Filter: 'block' or 'inline'." } }, "additionalProperties": false, "required": [ "type" ] } ] }, "within": { "$ref": "#/$defs/BlockNodeAddress" }, "require": { "enum": [ "first", "exactlyOne" ] } }, "additionalProperties": false, "required": [ "by", "select", "require" ] }, { "type": "object", "properties": { "by": { "const": "ref", "type": "string" }, "ref": { "type": "string" }, "within": { "$ref": "#/$defs/BlockNodeAddress" } }, "additionalProperties": false, "required": [ "by", "ref" ] }, { "type": "object", "properties": { "by": { "const": "target", "type": "string" }, "target": { "$ref": "#/$defs/SelectionTarget" } }, "additionalProperties": false, "required": [ "by", "target" ] }, { "type": "object", "properties": { "by": { "const": "block", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt" ] }, "nodeId": { "type": "string" } }, "additionalProperties": false, "required": [ "by", "nodeType", "nodeId" ] } ] }, "args": { "type": "object", "properties": { "position": { "enum": [ "before", "after" ] }, "content": { "type": "object", "properties": { "text": { "type": "string" } }, "additionalProperties": false, "required": [ "text" ] }, "style": { "type": "object", "properties": { "inline": { "type": "object", "properties": { "mode": { "enum": [ "inherit", "set", "clear" ], "type": "string" }, "setMarks": { "type": "object", "properties": { "bold": { "enum": [ "on", "off", "clear" ] }, "italic": { "enum": [ "on", "off", "clear" ] }, "underline": { "enum": [ "on", "off", "clear" ] }, "strike": { "enum": [ "on", "off", "clear" ] } }, "additionalProperties": false } }, "additionalProperties": false, "required": [ "mode" ] } }, "additionalProperties": false, "required": [ "inline" ] } }, "additionalProperties": false, "required": [ "position", "content" ] } }, "additionalProperties": false, "required": [ "id", "op", "where", "args" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "op": { "const": "text.delete", "type": "string" }, "where": { "oneOf": [ { "type": "object", "properties": { "by": { "const": "select", "type": "string" }, "select": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "text", "description": "Must be 'text' for text pattern search.", "type": "string" }, "pattern": { "type": "string", "description": "Text to match. In regex mode, patterns are validated for syntax, maximum length, and safety before execution." }, "mode": { "enum": [ "contains", "regex" ], "description": "Match mode: 'contains' (literal substring, recommended for literal text) or 'regex' (validated regular expression)." }, "caseSensitive": { "type": "boolean", "description": "Case-sensitive matching. Default: false." }, "wholeWord": { "type": "boolean", "description": "Require word-boundary matches. Default: false." }, "includeDeletedText": { "type": "boolean", "description": "When true, includes text from pending tracked deletions. Default: false." } }, "additionalProperties": false, "required": [ "type", "pattern" ] }, { "type": "object", "properties": { "type": { "const": "node", "description": "Must be 'node' for node type search.", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt", "run", "bookmark", "comment", "hyperlink", "footnoteRef", "endnoteRef", "crossRef", "indexEntry", "citation", "authorityEntry", "sequenceField", "tab", "lineBreak" ], "description": "Block type to match (paragraph, heading, table, listItem, etc.)." }, "kind": { "enum": [ "block", "inline" ], "description": "Filter: 'block' or 'inline'." } }, "additionalProperties": false, "required": [ "type" ] } ] }, "within": { "$ref": "#/$defs/BlockNodeAddress" }, "require": { "enum": [ "first", "exactlyOne", "all" ] } }, "additionalProperties": false, "required": [ "by", "select", "require" ] }, { "type": "object", "properties": { "by": { "const": "ref", "type": "string" }, "ref": { "type": "string" }, "within": { "$ref": "#/$defs/BlockNodeAddress" } }, "additionalProperties": false, "required": [ "by", "ref" ] }, { "type": "object", "properties": { "by": { "const": "target", "type": "string" }, "target": { "$ref": "#/$defs/SelectionTarget" } }, "additionalProperties": false, "required": [ "by", "target" ] }, { "type": "object", "properties": { "by": { "const": "block", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt" ] }, "nodeId": { "type": "string" } }, "additionalProperties": false, "required": [ "by", "nodeType", "nodeId" ] } ] }, "args": { "type": "object", "properties": { "behavior": { "$ref": "#/$defs/DeleteBehavior" } }, "additionalProperties": false } }, "additionalProperties": false, "required": [ "id", "op", "where", "args" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "op": { "const": "format.apply", "type": "string" }, "where": { "oneOf": [ { "type": "object", "properties": { "by": { "const": "select", "type": "string" }, "select": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "text", "description": "Must be 'text' for text pattern search.", "type": "string" }, "pattern": { "type": "string", "description": "Text to match. In regex mode, patterns are validated for syntax, maximum length, and safety before execution." }, "mode": { "enum": [ "contains", "regex" ], "description": "Match mode: 'contains' (literal substring, recommended for literal text) or 'regex' (validated regular expression)." }, "caseSensitive": { "type": "boolean", "description": "Case-sensitive matching. Default: false." }, "wholeWord": { "type": "boolean", "description": "Require word-boundary matches. Default: false." }, "includeDeletedText": { "type": "boolean", "description": "When true, includes text from pending tracked deletions. Default: false." } }, "additionalProperties": false, "required": [ "type", "pattern" ] }, { "type": "object", "properties": { "type": { "const": "node", "description": "Must be 'node' for node type search.", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt", "run", "bookmark", "comment", "hyperlink", "footnoteRef", "endnoteRef", "crossRef", "indexEntry", "citation", "authorityEntry", "sequenceField", "tab", "lineBreak" ], "description": "Block type to match (paragraph, heading, table, listItem, etc.)." }, "kind": { "enum": [ "block", "inline" ], "description": "Filter: 'block' or 'inline'." } }, "additionalProperties": false, "required": [ "type" ] } ] }, "within": { "$ref": "#/$defs/BlockNodeAddress" }, "require": { "enum": [ "first", "exactlyOne", "all" ] } }, "additionalProperties": false, "required": [ "by", "select", "require" ] }, { "type": "object", "properties": { "by": { "const": "ref", "type": "string" }, "ref": { "type": "string" }, "within": { "$ref": "#/$defs/BlockNodeAddress" } }, "additionalProperties": false, "required": [ "by", "ref" ] }, { "type": "object", "properties": { "by": { "const": "target", "type": "string" }, "target": { "$ref": "#/$defs/SelectionTarget" } }, "additionalProperties": false, "required": [ "by", "target" ] }, { "type": "object", "properties": { "by": { "const": "block", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt" ] }, "nodeId": { "type": "string" } }, "additionalProperties": false, "required": [ "by", "nodeType", "nodeId" ] } ] }, "args": { "type": "object", "properties": { "inline": { "type": "object", "properties": { "bold": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "italic": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "strike": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "underline": { "oneOf": [ { "type": "boolean" }, { "type": "null" }, { "type": "object", "properties": { "style": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "color": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "themeColor": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 } ] }, "highlight": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "color": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "fontSize": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "fontFamily": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "letterSpacing": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "vertAlign": { "oneOf": [ { "enum": [ "superscript", "subscript", "baseline" ] }, { "type": "null" } ] }, "position": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "dstrike": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "smallCaps": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "caps": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "shading": { "oneOf": [ { "type": "object", "properties": { "fill": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "color": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "val": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 }, { "type": "null" } ] }, "border": { "oneOf": [ { "type": "object", "properties": { "val": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "sz": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "color": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "space": { "oneOf": [ { "type": "number" }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 }, { "type": "null" } ] }, "outline": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "shadow": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "emboss": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "imprint": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "charScale": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "kerning": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "vanish": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "webHidden": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "specVanish": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "rtl": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "cs": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "bCs": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "iCs": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "eastAsianLayout": { "oneOf": [ { "type": "object", "properties": { "id": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "combine": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "combineBrackets": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "vert": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "vertCompress": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 }, { "type": "null" } ] }, "em": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "fitText": { "oneOf": [ { "type": "object", "properties": { "val": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "id": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 }, { "type": "null" } ] }, "snapToGrid": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "lang": { "oneOf": [ { "type": "object", "properties": { "val": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "eastAsia": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "bidi": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 }, { "type": "null" } ] }, "oMath": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "rStyle": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "rFonts": { "oneOf": [ { "type": "object", "properties": { "ascii": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "hAnsi": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "eastAsia": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "cs": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "asciiTheme": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "hAnsiTheme": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "eastAsiaTheme": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "csTheme": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "hint": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 }, { "type": "null" } ] }, "fontSizeCs": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "ligatures": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "numForm": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "numSpacing": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "stylisticSets": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "val": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, "minItems": 1 }, { "type": "null" } ] }, "contextualAlternates": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 }, "alignment": { "type": "string", "enum": [ "left", "center", "right", "justify" ], "description": "Set paragraph alignment on the target block(s). Can be combined with inline formatting in the same step." }, "scope": { "type": "string", "enum": [ "match", "block" ], "description": "When \"block\", inline formatting expands to cover the entire parent paragraph(s), not just the matched text. Use \"block\" after markdown inserts to format whole paragraphs with a short identifying pattern. Default: \"match\"." } }, "additionalProperties": false, "minProperties": 1 } }, "additionalProperties": false, "required": [ "id", "op", "where", "args" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "op": { "const": "structural.replace", "type": "string" }, "where": { "oneOf": [ { "type": "object", "properties": { "by": { "const": "select", "type": "string" }, "select": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "text", "description": "Must be 'text' for text pattern search.", "type": "string" }, "pattern": { "type": "string", "description": "Text to match. In regex mode, patterns are validated for syntax, maximum length, and safety before execution." }, "mode": { "enum": [ "contains", "regex" ], "description": "Match mode: 'contains' (literal substring, recommended for literal text) or 'regex' (validated regular expression)." }, "caseSensitive": { "type": "boolean", "description": "Case-sensitive matching. Default: false." }, "wholeWord": { "type": "boolean", "description": "Require word-boundary matches. Default: false." }, "includeDeletedText": { "type": "boolean", "description": "When true, includes text from pending tracked deletions. Default: false." } }, "additionalProperties": false, "required": [ "type", "pattern" ] }, { "type": "object", "properties": { "type": { "const": "node", "description": "Must be 'node' for node type search.", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt", "run", "bookmark", "comment", "hyperlink", "footnoteRef", "endnoteRef", "crossRef", "indexEntry", "citation", "authorityEntry", "sequenceField", "tab", "lineBreak" ], "description": "Block type to match (paragraph, heading, table, listItem, etc.)." }, "kind": { "enum": [ "block", "inline" ], "description": "Filter: 'block' or 'inline'." } }, "additionalProperties": false, "required": [ "type" ] } ] }, "within": { "$ref": "#/$defs/BlockNodeAddress" }, "require": { "enum": [ "first", "exactlyOne", "all" ] } }, "additionalProperties": false, "required": [ "by", "select", "require" ] }, { "type": "object", "properties": { "by": { "const": "ref", "type": "string" }, "ref": { "type": "string" }, "within": { "$ref": "#/$defs/BlockNodeAddress" } }, "additionalProperties": false, "required": [ "by", "ref" ] }, { "type": "object", "properties": { "by": { "const": "target", "type": "string" }, "target": { "$ref": "#/$defs/SelectionTarget" } }, "additionalProperties": false, "required": [ "by", "target" ] }, { "type": "object", "properties": { "by": { "const": "block", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt" ] }, "nodeId": { "type": "string" } }, "additionalProperties": false, "required": [ "by", "nodeType", "nodeId" ] } ] }, "args": { "type": "object", "properties": { "content": { "oneOf": [ { "type": "object" }, { "type": "array", "items": { "type": "object" } } ] }, "nestingPolicy": { "type": "object", "properties": { "tables": { "enum": [ "forbid", "allow" ] } }, "additionalProperties": false, "description": "Controls nesting behavior. tables: 'allow' permits inserting tables inside other tables." } }, "additionalProperties": false, "required": [ "content" ] } }, "additionalProperties": false, "required": [ "id", "op", "where", "args" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "op": { "const": "assert", "type": "string" }, "where": { "type": "object", "properties": { "by": { "const": "select", "type": "string" }, "select": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "text", "description": "Must be 'text' for text pattern search.", "type": "string" }, "pattern": { "type": "string", "description": "Text to match. In regex mode, patterns are validated for syntax, maximum length, and safety before execution." }, "mode": { "enum": [ "contains", "regex" ], "description": "Match mode: 'contains' (literal substring, recommended for literal text) or 'regex' (validated regular expression)." }, "caseSensitive": { "type": "boolean", "description": "Case-sensitive matching. Default: false." }, "wholeWord": { "type": "boolean", "description": "Require word-boundary matches. Default: false." }, "includeDeletedText": { "type": "boolean", "description": "When true, includes text from pending tracked deletions. Default: false." } }, "additionalProperties": false, "required": [ "type", "pattern" ] }, { "type": "object", "properties": { "type": { "const": "node", "description": "Must be 'node' for node type search.", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt", "run", "bookmark", "comment", "hyperlink", "footnoteRef", "endnoteRef", "crossRef", "indexEntry", "citation", "authorityEntry", "sequenceField", "tab", "lineBreak" ], "description": "Block type to match (paragraph, heading, table, listItem, etc.)." }, "kind": { "enum": [ "block", "inline" ], "description": "Filter: 'block' or 'inline'." } }, "additionalProperties": false, "required": [ "type" ] } ] }, "within": { "$ref": "#/$defs/BlockNodeAddress" } }, "additionalProperties": false, "required": [ "by", "select" ] }, "args": { "type": "object", "properties": { "expectCount": { "type": "number" } }, "additionalProperties": false, "required": [ "expectCount" ] } }, "additionalProperties": false, "required": [ "id", "op", "where", "args" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "op": { "const": "comments.patch", "type": "string" }, "args": { "type": "object", "properties": { "commentId": { "type": "string", "minLength": 1 }, "target": { "oneOf": [ { "$ref": "#/$defs/TextAddress" }, { "$ref": "#/$defs/SelectionTarget" } ] } }, "additionalProperties": false, "required": [ "commentId", "target" ] } }, "additionalProperties": false, "required": [ "id", "op", "args" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "op": { "const": "trackChanges.decide", "type": "string" }, "args": { "type": "object", "properties": { "decision": { "enum": [ "accept", "reject" ], "type": "string" }, "commentRetention": { "const": "point", "type": "string" }, "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "id", "type": "string" }, "id": { "type": "string", "minLength": 1 } }, "additionalProperties": false, "required": [ "kind", "id" ] }, { "type": "object", "properties": { "kind": { "const": "ids", "type": "string" }, "ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } }, "additionalProperties": false, "required": [ "kind", "ids" ] } ] } }, "additionalProperties": false, "required": [ "decision", "target" ] } }, "additionalProperties": false, "required": [ "id", "op", "args" ] } ] }, "description": "Ordered array of mutation steps. Each step needs 'op' (text.rewrite, text.insert, text.delete, format.apply, structural.replace, assert, comments.patch, or trackChanges.decide). Core steps use 'where'; review steps use explicit native args and require direct body-only plans with relocations before decisions. Check runtime capabilities for operation-specific content and targeting restrictions." }, "detail": { "type": "object", "properties": { "offset": { "type": "number", "minimum": 0 }, "limit": { "type": "number", "minimum": 0, "maximum": 1000 } }, "additionalProperties": false, "description": "Only for action 'preview'. Omit for other actions." }, "force": { "type": "boolean", "description": "Bypass confirmation checks. Only for action 'apply'. Omit for other actions." }, "changeTag": { "type": "string", "description": "Caller correlation echoed only on this committed mutation; never stored in DOCX. Only for action 'apply'. Omit for other actions." } }, "required": [ "action", "atomic", "changeMode", "steps" ], "additionalProperties": false, "$defs": { "BlockNodeAddress": { "type": "object", "properties": { "kind": { "const": "block", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt" ] }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "DeleteBehavior": { "enum": [ "selection", "exact" ] }, "Range": { "type": "object", "properties": { "start": { "type": "integer" }, "end": { "type": "integer" } }, "additionalProperties": false, "required": [ "start", "end" ] }, "SectionAddress": { "type": "object", "properties": { "kind": { "const": "section", "type": "string" }, "sectionId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "sectionId" ] }, "SelectionEdgeNodeAddress": { "type": "object", "properties": { "kind": { "const": "block", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableOfContents", "sdt", "image" ] }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "SelectionPoint": { "description": "A point in the document. Use {kind:'text', blockId, offset} for character positions or {kind:'nodeEdge', node:{kind:'block', nodeType, nodeId}, edge:'before'|'after'} for block boundaries.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "text", "type": "string" }, "blockId": { "type": "string" }, "offset": { "type": "integer", "minimum": 0 }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "blockId", "offset" ] }, { "type": "object", "properties": { "kind": { "const": "nodeEdge", "type": "string" }, "node": { "$ref": "#/$defs/SelectionEdgeNodeAddress" }, "edge": { "enum": [ "before", "after" ] } }, "additionalProperties": false, "required": [ "kind", "node", "edge" ] } ] }, "SelectionTarget": { "type": "object", "properties": { "kind": { "const": "selection", "type": "string" }, "start": { "$ref": "#/$defs/SelectionPoint" }, "end": { "$ref": "#/$defs/SelectionPoint" }, "story": { "$ref": "#/$defs/StoryLocator" }, "coordinateSpace": { "$ref": "#/$defs/TextCoordinateSpace" } }, "additionalProperties": false, "required": [ "kind", "start", "end" ] }, "StoryLocator": { "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "body", "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "headerFooterSlot", "type": "string" }, "section": { "$ref": "#/$defs/SectionAddress" }, "headerFooterKind": { "enum": [ "header", "footer" ] }, "variant": { "enum": [ "default", "first", "even" ] }, "resolution": { "enum": [ "effective", "explicit" ] }, "onWrite": { "enum": [ "materializeIfInherited", "editResolvedPart", "error" ] } }, "additionalProperties": false, "required": [ "kind", "storyType", "section", "headerFooterKind", "variant" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "headerFooterPart", "type": "string" }, "refId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "refId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "footnote", "type": "string" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "endnote", "type": "string" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "textbox", "type": "string" }, "textboxId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "textboxId" ] } ] }, "TextAddress": { "type": "object", "properties": { "kind": { "const": "text", "type": "string" }, "blockId": { "type": "string" }, "range": { "$ref": "#/$defs/Range" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "blockId", "range" ] }, "TextCoordinateSpace": { "enum": [ "visible", "tracked" ] } } }, "mutates": true, "operations": [ { "operationId": "doc.mutations.preview", "intentAction": "preview", "required": [ "atomic", "changeMode", "steps" ] }, { "operationId": "doc.mutations.apply", "intentAction": "apply", "required": [ "atomic", "steps", "changeMode" ] } ] }, { "toolName": "superdoc_table", "description": "Create and modify table structure, content, and styling. Find table/row/cell nodeIds via superdoc_get_content({action:\"blocks\"}) or superdoc_search.\n\nACTIONS:\n• Structure: delete, insert_row, delete_row, insert_column, delete_column, merge_cells, unmerge_cells.\n• Cell content: set_cell_text (text). set_cell (vAlign / wrap / fit / preferred width).\n• Row / column: set_row (height + rule), set_row_options (repeat-header, allow-break), set_column (widthPt).\n• Table styling: set_borders, set_shading, set_style_options (headerRow / bandedRows / firstColumn / lastColumn / lastRow / bandedColumns), set_layout (autofit / alignment / direction / preferredWidth), set_options (default cell margins + cell spacing).\n\nLOCATORS (the shapes ops accept):\n• insert_row append shorthand: { nodeId: \"\" } with no rowIndex/position appends at the end. Three other forms: target a row + position, table + rowIndex + position, or any of the above with count:N for multiple.\n• insert_column shorthand: position:\"first\"|\"last\" with no columnIndex. Otherwise columnIndex + position:\"left\"|\"right\".\n• merge_cells: table target + start:{rowIndex, columnIndex} + end:{rowIndex, columnIndex}.\n• set_cell_text: table target + rowIndex + columnIndex (preferred) OR cell target.\n• set_cell: cell target only. Does NOT accept table+rowIndex+columnIndex.\n• set_borders / set_shading: table OR cell target. NOT a row target.\n\nCOLOR FORMAT:\nHex strings accept #RRGGBB, RRGGBB, #RGB, or 3-digit RGB; also \"auto\"; also null to clear (where supported). Stored canonically as uppercase RRGGBB. Always pass a concrete color when one is implied. Never call set_borders with `auto` for a \"make it look [X]\" ask.\n\nSTYLING (TWO MODES):\n\nA. STRUCTURAL CHANGE → re-apply the existing styling.\n Triggers: insert_row / insert_column / delete_row / delete_column / merge_cells / unmerge_cells. (NOT set_cell_text or set_cell: those don't disturb borders/shading.)\n Recipe: read the current borders/shading/cnf flags via superdoc_get_content({action:\"blocks\"}) before the change, then re-apply the SAME values after with set_borders + set_shading + set_style_options. The goal is consistency, not a redesign.\n Skip on a freshly created table. A new table starts un-styled.\n\nB. STYLE-CHANGE REQUEST (\"make it look [X]\" / \"style the whole table\") → apply the FULL set with concrete colors.\n Touch every axis: borders, shading, text alignment, font color/weight, cnf flags, spacing. A single set_borders call without shading and font tweaks always looks half-finished. That's the #1 cause of \"no visual change\" complaints.\n Color palette: discover the document's palette by reading superdoc_get_content({action:\"blocks\"}) and reusing the colors on existing tables/headings. When no palette is obvious, default to corporate blue \"1F3864\" or dark grey \"444444\" for accents and \"F2F2F2\" / \"E7E6E6\" for banding.\n Recipe (call ALL of these):\n 1. set_borders applyTo:\"all\" with an explicit color and weight.\n 2. set_shading on the header row cells with the accent color. Add banding on alternate body rows if appropriate.\n 3. set_style_options { headerRow: true, bandedRows?: true } so cnf regions are recognized.\n 4. Cell-text alignment via superdoc_format action:\"set_alignment\". Center the header, left-align body, right-align numeric columns. Paragraph-level: target the paragraph inside each cell.\n 5. Font color + weight via superdoc_format action:\"inline\". Header gets a contrasting color (white on dark fill, accent on light fill) plus bold:true.\n 6. set_options if the user asks for tighter or looser spacing.\n Steps 4–5 cross to superdoc_format. Use superdoc_mutations to batch many format.apply steps in one call.\n\nAFTER set_cell_text, match the new cell to its siblings:\nset_cell_text writes plain text with the document's default font/size/color and no weight. Always follow up with one superdoc_format inline call copying fontFamily/fontSize/color/bold from a sibling cell (or any non-empty body paragraph if the table is fresh and has no sibling content). If sibling cells show a bold-prefix pattern like \"Label: value\", replicate it on the new cell via superdoc_search + superdoc_format inline (or one superdoc_mutations batch with format.apply steps).\n\nLIST-TO-TABLE:\n(1) superdoc_create action:\"table\" with the desired rows/columns. (2) Populate cells with set_cell_text using rowIndex/columnIndex (one call per cell). (3) DELETE THE WHOLE LIST in one call: superdoc_list({action:\"delete\", target:{kind:\"block\", nodeType:\"listItem\", nodeId:\"\"}}). The op walks the contiguous list and removes all items.\nWrong paths for list deletion (all leave bullets/empty paragraphs behind): text.delete, superdoc_edit action:\"delete\" on text refs, lists.detach, lists.convertToText.\n\nEXAMPLES:\n 1. {\"action\":\"insert_row\",\"nodeId\":\"\"}\n 2. {\"action\":\"insert_column\",\"nodeId\":\"\",\"position\":\"last\"}\n 3. {\"action\":\"merge_cells\",\"nodeId\":\"\",\"start\":{\"rowIndex\":0,\"columnIndex\":0},\"end\":{\"rowIndex\":1,\"columnIndex\":1}}\n 4. {\"action\":\"set_cell_text\",\"nodeId\":\"\",\"rowIndex\":0,\"columnIndex\":0,\"text\":\"Q1 Revenue\"}\n 5. {\"action\":\"set_row\",\"nodeId\":\"\",\"rowIndex\":0,\"heightPt\":24,\"rule\":\"atLeast\"}\n 6. {\"action\":\"set_borders\",\"nodeId\":\"\",\"mode\":\"applyTo\",\"applyTo\":\"all\",\"border\":{\"lineStyle\":\"single\",\"lineWeightPt\":1,\"color\":\"#000000\"}}\n 7. {\"action\":\"set_shading\",\"target\":{\"kind\":\"block\",\"nodeType\":\"tableCell\",\"nodeId\":\"\"},\"color\":\"#E3F2FD\"}\n 8. {\"action\":\"set_style_options\",\"nodeId\":\"\",\"styleOptions\":{\"headerRow\":true,\"bandedRows\":true}}", "inputSchema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "delete", "delete_column", "delete_row", "insert_column", "insert_row", "merge_cells", "move_column", "move_row", "set_borders", "set_cell", "set_cell_text", "set_column", "set_layout", "set_options", "set_row", "set_row_options", "set_shading", "set_style_options", "unmerge_cells" ], "description": "The action to perform. One of: delete, delete_column, delete_row, insert_column, insert_row, merge_cells, move_column, move_row, set_borders, set_cell, set_cell_text, set_column, set_layout, set_options, set_row, set_row_options, set_shading, set_style_options, unmerge_cells." }, "force": { "type": "boolean", "description": "Bypass confirmation checks." }, "changeTag": { "type": "string", "description": "Caller correlation echoed only on this committed mutation; never stored in DOCX." }, "changeMode": { "type": "string", "description": "Edit mode: \"direct\" applies changes immediately, \"tracked\" records as suggestions." }, "dryRun": { "type": "boolean", "description": "Preview the result without applying changes." }, "target": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "$ref": "#/$defs/TableAddress" }, { "anyOf": [ { "anyOf": [ { "$ref": "#/$defs/TableRowAddress" }, { "$ref": "#/$defs/TableAddress" } ] }, { "$ref": "#/$defs/TableAddress" } ] } ] }, { "anyOf": [ { "$ref": "#/$defs/TableRowAddress" }, { "$ref": "#/$defs/TableAddress" } ] } ] }, { "anyOf": [ { "$ref": "#/$defs/TableRowAddress" }, { "$ref": "#/$defs/TableAddress" } ] } ] }, { "anyOf": [ { "$ref": "#/$defs/TableRowAddress" }, { "$ref": "#/$defs/TableAddress" } ] } ] }, { "anyOf": [ { "$ref": "#/$defs/TableRowAddress" }, { "$ref": "#/$defs/TableAddress" } ] } ] }, { "$ref": "#/$defs/TableAddress" } ] }, { "$ref": "#/$defs/TableAddress" } ] }, { "$ref": "#/$defs/TableAddress" } ] }, { "$ref": "#/$defs/TableAddress" } ] }, { "$ref": "#/$defs/TableAddress" } ] }, { "anyOf": [ { "$ref": "#/$defs/TableCellAddress" }, { "$ref": "#/$defs/TableAddress" } ] } ] }, { "$ref": "#/$defs/TableCellAddress" } ] }, { "anyOf": [ { "$ref": "#/$defs/TableCellAddress" }, { "$ref": "#/$defs/TableAddress" } ] } ] }, { "$ref": "#/$defs/TableOrCellAddress" } ] }, { "$ref": "#/$defs/BlockNodeAddress" } ] }, { "$ref": "#/$defs/BlockNodeAddress" } ] }, { "$ref": "#/$defs/BlockNodeAddress" } ], "description": "Target address. For inline/set_style: prefer 'ref' from superdoc_search, or use {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}. For paragraph actions (set_alignment, set_indentation, set_spacing, set_direction, set_flow_options): use {kind:'block', nodeType:'paragraph'|'heading'|'listItem', nodeId:''}." }, "nodeId": { "type": "string" }, "preferredWidth": { "type": "number", "description": "Only for action 'set_layout'. Omit for other actions." }, "preferredWidthType": { "enum": [ "dxa", "auto", "pct" ], "description": "Only for actions 'set_layout', 'set_cell'. Omit for other actions." }, "alignment": { "enum": [ "left", "center", "right" ], "description": "Only for action 'set_layout'. Omit for other actions." }, "leftIndentPt": { "type": "number", "description": "Only for action 'set_layout'. Omit for other actions." }, "autoFitMode": { "enum": [ "fixedWidth", "fitContents", "fitWindow" ], "description": "Only for action 'set_layout'. Omit for other actions." }, "tableDirection": { "enum": [ "ltr", "rtl" ], "description": "Only for action 'set_layout'. Omit for other actions." }, "position": { "enum": [ "above", "below", "left", "right", "first", "last" ], "description": "Required for action 'insert_column'." }, "count": { "type": "integer", "minimum": 1, "description": "Only for actions 'insert_row', 'insert_column'. Omit for other actions." }, "rowIndex": { "type": "integer", "minimum": 0, "description": "Only for actions 'insert_row', 'delete_row', 'move_row', 'set_row', 'set_row_options', 'unmerge_cells', 'set_cell_text'. Omit for other actions." }, "destination": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "first", "type": "string" } }, "additionalProperties": false, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "const": "last", "type": "string" } }, "additionalProperties": false, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "const": "before", "type": "string" }, "rowIndex": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "kind", "rowIndex" ] }, { "type": "object", "properties": { "kind": { "const": "after", "type": "string" }, "rowIndex": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "kind", "rowIndex" ] }, { "type": "object", "properties": { "kind": { "const": "before", "type": "string" }, "target": { "$ref": "#/$defs/TableRowAddress" } }, "additionalProperties": false, "required": [ "kind", "target" ] }, { "type": "object", "properties": { "kind": { "const": "after", "type": "string" }, "target": { "$ref": "#/$defs/TableRowAddress" } }, "additionalProperties": false, "required": [ "kind", "target" ] }, { "type": "object", "properties": { "kind": { "const": "before", "type": "string" }, "nodeId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "nodeId" ] }, { "type": "object", "properties": { "kind": { "const": "after", "type": "string" }, "nodeId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "nodeId" ] } ] }, { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "first", "type": "string" } }, "additionalProperties": false, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "const": "last", "type": "string" } }, "additionalProperties": false, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "const": "before", "type": "string" }, "columnIndex": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "kind", "columnIndex" ] }, { "type": "object", "properties": { "kind": { "const": "after", "type": "string" }, "columnIndex": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "kind", "columnIndex" ] } ] } ], "description": "Required for actions 'move_row', 'move_column'." }, "heightPt": { "type": "number", "exclusiveMinimum": 0, "description": "Required for action 'set_row'." }, "rule": { "enum": [ "atLeast", "exact", "auto" ], "description": "Only for action 'set_row'. Omit for other actions." }, "allowBreakAcrossPages": { "type": "boolean", "description": "Only for action 'set_row_options'. Omit for other actions." }, "repeatHeader": { "type": "boolean", "description": "Only for action 'set_row_options'. Omit for other actions." }, "gridBefore": { "type": "integer", "minimum": 0, "description": "Only for action 'set_row_options'. Omit for other actions." }, "gridAfter": { "type": "integer", "minimum": 0, "description": "Only for action 'set_row_options'. Omit for other actions." }, "wBefore": { "type": "object", "properties": { "value": { "type": "integer", "minimum": 0 }, "type": { "enum": [ "auto", "dxa", "nil", "pct" ] } }, "additionalProperties": false, "required": [ "value", "type" ], "description": "Only for action 'set_row_options'. Omit for other actions." }, "wAfter": { "type": "object", "properties": { "value": { "type": "integer", "minimum": 0 }, "type": { "enum": [ "auto", "dxa", "nil", "pct" ] } }, "additionalProperties": false, "required": [ "value", "type" ], "description": "Only for action 'set_row_options'. Omit for other actions." }, "columnIndex": { "type": "integer", "minimum": 0, "description": "Required for actions 'delete_column', 'move_column', 'set_column'." }, "widthPt": { "type": "number", "exclusiveMinimum": 0, "description": "Required for action 'set_column'." }, "start": { "type": "object", "properties": { "rowIndex": { "type": "integer", "minimum": 0 }, "columnIndex": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "rowIndex", "columnIndex" ], "description": "Required for action 'merge_cells'." }, "end": { "type": "object", "properties": { "rowIndex": { "type": "integer", "minimum": 0 }, "columnIndex": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "rowIndex", "columnIndex" ], "description": "Required for action 'merge_cells'." }, "preferredWidthPt": { "type": "number", "description": "Only for action 'set_cell'. Omit for other actions." }, "verticalAlign": { "enum": [ "top", "center", "bottom" ], "description": "Only for action 'set_cell'. Omit for other actions." }, "wrapText": { "type": "boolean", "description": "Only for action 'set_cell'. Omit for other actions." }, "fitText": { "type": "boolean", "description": "Only for action 'set_cell'. Omit for other actions." }, "text": { "type": "string", "description": "Required for action 'set_cell_text'." }, "color": { "oneOf": [ { "type": "string", "pattern": "^(#?([0-9A-Fa-f]{6}|[0-9A-Fa-f]{3})|auto)$" }, { "type": "null" } ], "description": "Required for action 'set_shading'." }, "styleId": { "type": "string", "description": "Only for action 'set_style_options'. Omit for other actions." }, "styleOptions": { "type": "object", "properties": { "headerRow": { "type": "boolean" }, "lastRow": { "type": "boolean" }, "totalRow": { "type": "boolean" }, "firstColumn": { "type": "boolean" }, "lastColumn": { "type": "boolean" }, "bandedRows": { "type": "boolean" }, "bandedColumns": { "type": "boolean" } }, "additionalProperties": false, "description": "Only for action 'set_style_options'. Omit for other actions." }, "mode": { "anyOf": [ { "const": "applyTo", "type": "string" }, { "const": "edges", "type": "string" } ], "description": "Required for action 'set_borders'." }, "applyTo": { "enum": [ "all", "outside", "inside", "top", "bottom", "left", "right", "insideH", "insideV" ], "description": "Only for action 'set_borders'. Omit for other actions." }, "border": { "oneOf": [ { "type": "object", "properties": { "lineStyle": { "type": "string" }, "lineWeightPt": { "type": "number", "exclusiveMinimum": 0 }, "color": { "type": "string", "pattern": "^(#?([0-9A-Fa-f]{6}|[0-9A-Fa-f]{3})|auto)$" } }, "additionalProperties": false, "required": [ "lineStyle", "lineWeightPt", "color" ] }, { "type": "null" } ], "description": "Only for action 'set_borders'. Omit for other actions." }, "edges": { "type": "object", "properties": { "top": { "oneOf": [ { "type": "object", "properties": { "lineStyle": { "type": "string" }, "lineWeightPt": { "type": "number", "exclusiveMinimum": 0 }, "color": { "type": "string", "pattern": "^(#?([0-9A-Fa-f]{6}|[0-9A-Fa-f]{3})|auto)$" } }, "additionalProperties": false, "required": [ "lineStyle", "lineWeightPt", "color" ] }, { "type": "null" } ] }, "bottom": { "oneOf": [ { "type": "object", "properties": { "lineStyle": { "type": "string" }, "lineWeightPt": { "type": "number", "exclusiveMinimum": 0 }, "color": { "type": "string", "pattern": "^(#?([0-9A-Fa-f]{6}|[0-9A-Fa-f]{3})|auto)$" } }, "additionalProperties": false, "required": [ "lineStyle", "lineWeightPt", "color" ] }, { "type": "null" } ] }, "left": { "oneOf": [ { "type": "object", "properties": { "lineStyle": { "type": "string" }, "lineWeightPt": { "type": "number", "exclusiveMinimum": 0 }, "color": { "type": "string", "pattern": "^(#?([0-9A-Fa-f]{6}|[0-9A-Fa-f]{3})|auto)$" } }, "additionalProperties": false, "required": [ "lineStyle", "lineWeightPt", "color" ] }, { "type": "null" } ] }, "right": { "oneOf": [ { "type": "object", "properties": { "lineStyle": { "type": "string" }, "lineWeightPt": { "type": "number", "exclusiveMinimum": 0 }, "color": { "type": "string", "pattern": "^(#?([0-9A-Fa-f]{6}|[0-9A-Fa-f]{3})|auto)$" } }, "additionalProperties": false, "required": [ "lineStyle", "lineWeightPt", "color" ] }, { "type": "null" } ] }, "insideH": { "oneOf": [ { "type": "object", "properties": { "lineStyle": { "type": "string" }, "lineWeightPt": { "type": "number", "exclusiveMinimum": 0 }, "color": { "type": "string", "pattern": "^(#?([0-9A-Fa-f]{6}|[0-9A-Fa-f]{3})|auto)$" } }, "additionalProperties": false, "required": [ "lineStyle", "lineWeightPt", "color" ] }, { "type": "null" } ] }, "insideV": { "oneOf": [ { "type": "object", "properties": { "lineStyle": { "type": "string" }, "lineWeightPt": { "type": "number", "exclusiveMinimum": 0 }, "color": { "type": "string", "pattern": "^(#?([0-9A-Fa-f]{6}|[0-9A-Fa-f]{3})|auto)$" } }, "additionalProperties": false, "required": [ "lineStyle", "lineWeightPt", "color" ] }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Only for action 'set_borders'. Omit for other actions." }, "defaultCellMargins": { "type": "object", "properties": { "topPt": { "type": "number", "minimum": 0 }, "rightPt": { "type": "number", "minimum": 0 }, "bottomPt": { "type": "number", "minimum": 0 }, "leftPt": { "type": "number", "minimum": 0 } }, "additionalProperties": false, "required": [ "topPt", "rightPt", "bottomPt", "leftPt" ], "description": "Only for action 'set_options'. Omit for other actions." }, "cellSpacingPt": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ], "description": "Only for action 'set_options'. Omit for other actions." } }, "required": [ "action" ], "additionalProperties": false, "$defs": { "BlockNodeAddress": { "type": "object", "properties": { "kind": { "const": "block", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt" ] }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "SectionAddress": { "type": "object", "properties": { "kind": { "const": "section", "type": "string" }, "sectionId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "sectionId" ] }, "StoryLocator": { "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "body", "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "headerFooterSlot", "type": "string" }, "section": { "$ref": "#/$defs/SectionAddress" }, "headerFooterKind": { "enum": [ "header", "footer" ] }, "variant": { "enum": [ "default", "first", "even" ] }, "resolution": { "enum": [ "effective", "explicit" ] }, "onWrite": { "enum": [ "materializeIfInherited", "editResolvedPart", "error" ] } }, "additionalProperties": false, "required": [ "kind", "storyType", "section", "headerFooterKind", "variant" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "headerFooterPart", "type": "string" }, "refId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "refId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "footnote", "type": "string" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "endnote", "type": "string" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story", "type": "string" }, "storyType": { "const": "textbox", "type": "string" }, "textboxId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "textboxId" ] } ] }, "TableAddress": { "type": "object", "properties": { "kind": { "const": "block", "type": "string" }, "nodeType": { "const": "table", "type": "string" }, "nodeId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "TableCellAddress": { "type": "object", "properties": { "kind": { "const": "block", "type": "string" }, "nodeType": { "const": "tableCell", "type": "string" }, "nodeId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "TableOrCellAddress": { "type": "object", "properties": { "kind": { "const": "block", "type": "string" }, "nodeType": { "enum": [ "table", "tableCell" ] }, "nodeId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "TableRowAddress": { "type": "object", "properties": { "kind": { "const": "block", "type": "string" }, "nodeType": { "const": "tableRow", "type": "string" }, "nodeId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] } } }, "mutates": true, "operations": [ { "operationId": "doc.tables.delete", "intentAction": "delete", "requiredOneOf": [ [ "target" ], [ "nodeId" ] ] }, { "operationId": "doc.tables.setLayout", "intentAction": "set_layout", "requiredOneOf": [ [ "target" ], [ "nodeId" ] ] }, { "operationId": "doc.tables.insertRow", "intentAction": "insert_row", "requiredOneOf": [ [ "target", "position" ], [ "target", "rowIndex", "position" ], [ "nodeId", "rowIndex", "position" ], [ "target" ], [ "nodeId" ] ] }, { "operationId": "doc.tables.deleteRow", "intentAction": "delete_row", "requiredOneOf": [ [ "target" ], [ "target", "rowIndex" ], [ "nodeId", "rowIndex" ] ] }, { "operationId": "doc.tables.moveRow", "intentAction": "move_row", "requiredOneOf": [ [ "target", "destination" ], [ "target", "rowIndex", "destination" ], [ "nodeId", "rowIndex", "destination" ] ] }, { "operationId": "doc.tables.setRowHeight", "intentAction": "set_row", "requiredOneOf": [ [ "target", "heightPt" ], [ "target", "rowIndex", "heightPt" ], [ "nodeId", "rowIndex", "heightPt" ] ] }, { "operationId": "doc.tables.setRowOptions", "intentAction": "set_row_options", "requiredOneOf": [ [ "target" ], [ "target", "rowIndex" ], [ "nodeId", "rowIndex" ] ] }, { "operationId": "doc.tables.insertColumn", "intentAction": "insert_column", "requiredOneOf": [ [ "position", "target" ], [ "position", "nodeId" ] ] }, { "operationId": "doc.tables.deleteColumn", "intentAction": "delete_column", "requiredOneOf": [ [ "columnIndex", "target" ], [ "columnIndex", "nodeId" ] ] }, { "operationId": "doc.tables.moveColumn", "intentAction": "move_column", "requiredOneOf": [ [ "columnIndex", "destination", "target" ], [ "columnIndex", "destination", "nodeId" ] ] }, { "operationId": "doc.tables.setColumnWidth", "intentAction": "set_column", "requiredOneOf": [ [ "columnIndex", "widthPt", "target" ], [ "columnIndex", "widthPt", "nodeId" ] ] }, { "operationId": "doc.tables.mergeCells", "intentAction": "merge_cells", "requiredOneOf": [ [ "start", "end", "target" ], [ "start", "end", "nodeId" ] ] }, { "operationId": "doc.tables.unmergeCells", "intentAction": "unmerge_cells", "requiredOneOf": [ [ "target" ], [ "nodeId" ], [ "target", "rowIndex", "columnIndex" ], [ "nodeId", "rowIndex", "columnIndex" ] ] }, { "operationId": "doc.tables.setCellProperties", "intentAction": "set_cell", "requiredOneOf": [ [ "target" ], [ "nodeId" ] ] }, { "operationId": "doc.tables.setCellText", "intentAction": "set_cell_text", "requiredOneOf": [ [ "target", "text" ], [ "nodeId", "text" ], [ "target", "rowIndex", "columnIndex", "text" ], [ "nodeId", "rowIndex", "columnIndex", "text" ] ] }, { "operationId": "doc.tables.setShading", "intentAction": "set_shading", "requiredOneOf": [ [ "color", "target" ], [ "color", "nodeId" ] ] }, { "operationId": "doc.tables.applyStyle", "intentAction": "set_style_options", "requiredOneOf": [ [ "target" ], [ "nodeId" ] ] }, { "operationId": "doc.tables.setBorders", "intentAction": "set_borders", "requiredOneOf": [ [ "mode", "applyTo", "border", "target" ], [ "mode", "applyTo", "border", "nodeId" ], [ "mode", "edges", "target" ], [ "mode", "edges", "nodeId" ] ] }, { "operationId": "doc.tables.setTableOptions", "intentAction": "set_options", "requiredOneOf": [ [ "target" ], [ "nodeId" ] ] } ] } ] }