@superdoc-dev/sdk 1.3.0-next.8 → 1.3.0-next.80

package/tools/tools.generic.json

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "superdoc_get_content",
-      "description": "Read document content. Use action \"info\" for structure and styles, \"blocks\" for all block IDs and types, \"text\" or \"markdown\" for content. Call info or blocks before editing.",
+      "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, formatting properties (fontFamily, fontSize, color, bold, underline, alignment), and ref handles for immediate use with superdoc_edit or superdoc_format. Action \"text\" and \"markdown\" return the full document as plain text or Markdown. Action \"html\" returns HTML. 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\", and filtering via \"nodeTypes\". Other actions ignore these 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.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -63,11 +63,20 @@
           "doc.info",
           "doc.blocks.list"
         ]
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false,
+        "reversible": false,
+        "supportsDryRun": false,
+        "supportsTrackedChanges": false
       }
     },
     {
       "name": "superdoc_edit",
-      "description": "Insert, replace, delete text, or undo/redo",
+      "description": "Refs expire after any mutation; always re-search before the next edit. Modify document text: insert new content, replace existing text, delete a range, or undo/redo. Use this for single text modifications. For 2+ edits that must succeed or fail atomically, use superdoc_mutations instead. For replace and delete, pass a \"ref\" from superdoc_search or superdoc_get_content blocks. 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. Insert supports plain text (default), markdown, or html via the \"type\" parameter. Use \"placement\" (before, after, insideStart, insideEnd) to control position relative to the target. 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.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -289,7 +298,7 @@
                 ]
               }
             ],
-            "description": "Target address object. Use 'ref' instead if you have a search handle. Format: {kind:'text', blockId, range:{start,end}} or {kind:'block', nodeType, nodeId}."
+            "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 from blocks list>'}."
           },
           "value": {
             "type": "string",
@@ -306,7 +315,7 @@
           },
           "ref": {
             "type": "string",
-            "description": "Handle ref string returned by a prior search/query result."
+            "description": "Handle ref from superdoc_search result (pass handle.ref value directly). Preferred over building a target object."
           },
           "content": {
             "oneOf": [
@@ -346,22 +355,6 @@
             },
             "description": "Controls nesting behavior. tables: 'allow' permits inserting tables inside other tables. Only for actions 'insert', 'replace'. Omit for other actions."
           },
-          "blockId": {
-            "type": "string",
-            "description": "Block ID of the target paragraph."
-          },
-          "start": {
-            "type": "number",
-            "description": "Start offset within the block (character index)."
-          },
-          "end": {
-            "type": "number",
-            "description": "End offset within the block (character index)."
-          },
-          "offset": {
-            "type": "number",
-            "description": "Character offset for insertion (alias for --start/--end with same value). Only for action 'insert'. Omit for other actions."
-          },
           "text": {
             "type": "string",
             "description": "Replacement text content. Only for action 'replace'. Omit for other actions."
@@ -390,11 +383,20 @@
           "doc.history.undo",
           "doc.history.redo"
         ]
+      },
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": false,
+        "idempotentHint": false,
+        "openWorldHint": false,
+        "reversible": true,
+        "supportsDryRun": true,
+        "supportsTrackedChanges": true
       }
     },
     {
       "name": "superdoc_format",
-      "description": "Change text and paragraph formatting. Use action \"inline\" with a search ref for bold/italic/etc. Use action \"set_style\" with a styleId from superdoc_get_content info to apply a named paragraph style.",
+      "description": "Change text and paragraph formatting. Use this after superdoc_create to style new content, or with a search ref to restyle existing text. 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:\"<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. Format one block at a time. Do NOT hardcode formatting values; always read them from superdoc_get_content blocks and replicate.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -404,11 +406,12 @@
               "inline",
               "set_alignment",
               "set_direction",
+              "set_flow_options",
               "set_indentation",
               "set_spacing",
               "set_style"
             ],
-            "description": "The action to perform. One of: inline, set_alignment, set_direction, set_indentation, set_spacing, set_style."
+            "description": "The action to perform. One of: inline, set_alignment, set_direction, set_flow_options, set_indentation, set_spacing, set_style."
           },
           "force": {
             "type": "boolean",
@@ -583,7 +586,7 @@
               "start",
               "end"
             ],
-            "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_alignment', 'set_indentation', 'set_spacing', 'set_direction'."
+            "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_alignment', 'set_indentation', 'set_spacing', 'set_flow_options', 'set_direction'."
           },
           "inline": {
             "type": "object",
@@ -901,6 +904,18 @@
               "atLeast"
             ]
           },
+          "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."
+          },
           "direction": {
             "type": "string",
             "enum": [
@@ -925,20 +940,30 @@
       },
       "metadata": {
         "mutates": true,
-        "operationCount": 6,
+        "operationCount": 7,
         "operations": [
           "doc.format.apply",
           "doc.styles.paragraph.setStyle",
           "doc.format.paragraph.setAlignment",
           "doc.format.paragraph.setIndentation",
           "doc.format.paragraph.setSpacing",
+          "doc.format.paragraph.setFlowOptions",
           "doc.format.paragraph.setDirection"
         ]
+      },
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": false,
+        "idempotentHint": false,
+        "openWorldHint": false,
+        "reversible": true,
+        "supportsDryRun": true,
+        "supportsTrackedChanges": true
       }
     },
     {
       "name": "superdoc_create",
-      "description": "Create one paragraph or heading per call. After creating, search for it and apply formatting (fontFamily, fontSize) from neighboring blocks. For multiple paragraphs, use superdoc_mutations with text.insert steps instead of calling create repeatedly.",
+      "description": "You MUST call superdoc_format after this tool to match document styling. Create a single paragraph, heading, or table in the document. Returns a nodeId for chaining subsequent creates and for use as a block target in superdoc_format. When the user asks for a \"heading\", use action \"heading\" with a level (default 1). Use action \"paragraph\" only when the user asks for regular body text. Before creating, call superdoc_get_content blocks to read formatting from regular body text paragraphs (non-empty, non-title blocks with alignment \"justify\" or \"left\"). After creating, re-fetch blocks with superdoc_get_content to get a fresh ref for the new block, then apply TWO format calls: (1) superdoc_format action \"inline\" for character styling, AND (2) superdoc_format action \"set_alignment\" with the block target for paragraph alignment. Both calls are REQUIRED. For body paragraphs: inline {bold:false, underline:false, fontFamily, fontSize, color from body blocks}, alignment \"justify\". Ignore underline:true from blocks data for body text; it is a style artifact. For headings: inline {bold:true, underline:true, fontSize scaled up, fontFamily, color}, alignment \"center\". 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.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -946,9 +971,10 @@
             "type": "string",
             "enum": [
               "heading",
-              "paragraph"
+              "paragraph",
+              "table"
             ],
-            "description": "The action to perform. One of: heading, paragraph."
+            "description": "The action to perform. One of: heading, paragraph, table."
           },
           "force": {
             "type": "boolean",
@@ -1092,6 +1118,14 @@
           "level": {
             "type": "number",
             "description": "Heading level (1-6). Required for action 'heading'."
+          },
+          "rows": {
+            "type": "number",
+            "description": "Required for action 'table'."
+          },
+          "columns": {
+            "type": "number",
+            "description": "Required for action 'table'."
           }
         },
         "required": [
@@ -1101,16 +1135,26 @@
       },
       "metadata": {
         "mutates": true,
-        "operationCount": 2,
+        "operationCount": 3,
         "operations": [
           "doc.create.paragraph",
-          "doc.create.heading"
+          "doc.create.heading",
+          "doc.create.table"
         ]
+      },
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": false,
+        "idempotentHint": false,
+        "openWorldHint": false,
+        "reversible": true,
+        "supportsDryRun": true,
+        "supportsTrackedChanges": true
       }
     },
     {
       "name": "superdoc_list",
-      "description": "Create and manipulate lists",
+      "description": "Create and manipulate bullet and numbered lists. To create a list: first create all paragraphs at the SAME location using superdoc_create (chain each using the previous nodeId as the \"at\" target). Then call action \"create\" with mode:\"fromParagraphs\", a preset (\"disc\" for bullet, \"decimal\" for numbered), and a range target: {from:{kind:\"block\", nodeType:\"paragraph\", nodeId:\"<first>\"}, to:{kind:\"block\", nodeType:\"paragraph\", nodeId:\"<last>\"}}. The range converts ALL paragraphs between from and to into list items. Make sure no other content exists between them. Action \"set_type\" converts between bullet and ordered (target any item in the list, kind:\"ordered\" or \"bullet\"). Action \"insert\" adds a new item before/after a target list item. Actions \"indent\" and \"outdent\" change nesting level; \"set_level\" jumps to a specific level (0-8). Action \"detach\" converts a list item back to a plain paragraph. Do NOT target paragraphs with indent/outdent/set_type; these actions require a listItem target.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -1373,11 +1417,20 @@
           "doc.lists.setLevel",
           "doc.lists.setType"
         ]
+      },
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": false,
+        "idempotentHint": false,
+        "openWorldHint": false,
+        "reversible": true,
+        "supportsDryRun": true,
+        "supportsTrackedChanges": true
       }
     },
     {
       "name": "superdoc_comment",
-      "description": "Comment threads — create, edit, delete",
+      "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: {kind:\"text\", blockId:\"<blockId>\", range:{start:<N>, end:<N>}} using the blockId and highlightRange from the search result. 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 status to \"resolved\" or marks as internal. Action \"delete\" removes a comment or reply by ID. Do NOT pass \"ref\", \"id\", or \"parentId\" when creating a new top-level comment; only \"action\", \"text\", and \"target\" are needed.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -1488,11 +1541,20 @@
           "doc.comments.get",
           "doc.comments.list"
         ]
+      },
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": true,
+        "idempotentHint": false,
+        "openWorldHint": false,
+        "reversible": false,
+        "supportsDryRun": false,
+        "supportsTrackedChanges": false
       }
     },
     {
       "name": "superdoc_track_changes",
-      "description": "Review and resolve tracked changes",
+      "description": "Review and resolve tracked changes (insertions, deletions, format changes) in the document. Action \"list\" returns all tracked changes with optional filtering by type (insert, delete, 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:\"<changeId>\"} or all changes at once with {scope:\"all\"}. Do NOT use this tool unless the document has tracked changes. Use superdoc_get_content info to check the tracked change count first.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -1583,11 +1645,20 @@
           "doc.trackChanges.list",
           "doc.trackChanges.decide"
         ]
+      },
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": true,
+        "idempotentHint": false,
+        "openWorldHint": false,
+        "reversible": false,
+        "supportsDryRun": false,
+        "supportsTrackedChanges": false
       }
     },
     {
       "name": "superdoc_search",
-      "description": "Find text or nodes in the document",
+      "description": "Refs expire after any mutation; always re-search before the next edit. Find text patterns or nodes in the document and get ref handles for targeting edits and formatting. Use this to locate content before calling superdoc_edit or superdoc_format. 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, \"all\" returns every match, \"exactlyOne\" fails if not exactly one match. Supports scoping via \"within\" to search inside a single block. Do NOT use regex or markdown formatting markers (#, **, etc.) in search patterns; patterns are plain text only. Do NOT use this tool when you already have a ref from superdoc_get_content blocks or superdoc_create; use that ref directly.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -1745,11 +1816,20 @@
         "operations": [
           "doc.query.match"
         ]
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false,
+        "reversible": false,
+        "supportsDryRun": false,
+        "supportsTrackedChanges": false
       }
     },
     {
       "name": "superdoc_mutations",
-      "description": "Atomic multi-step batch edits (escape hatch)",
+      "description": "All steps succeed or all fail; no partial application. Execute multiple text edits atomically in a single batch. Use this INSTEAD OF multiple sequential superdoc_edit calls when you need 2+ text changes that should succeed or fail together. Each step has an id (e.g. \"s1\"), an op (text.rewrite, text.insert, text.delete, format.apply, assert), a \"where\" clause for targeting ({by:\"select\", select:{...}, require:\"first\"|\"exactlyOne\"|\"all\"} or {by:\"ref\", ref:\"...\"}), and \"args\" with operation-specific parameters. Action \"preview\" dry-runs the plan without modifying the document. Action \"apply\" executes it. CRITICAL: split mutations by phase. Text mutations (text.rewrite, text.insert, text.delete) go in one call. Formatting (format.apply) goes in a separate call with fresh refs from a new superdoc_search. Do NOT create two steps that target overlapping text in the same block; combine them into a single text.rewrite step. Overlapping steps fail with PLAN_CONFLICT_OVERLAP. Do NOT use this for single edits; use superdoc_edit instead. Do NOT mix text mutations and formatting in the same call.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -3704,6 +3784,15 @@
           "doc.mutations.preview",
           "doc.mutations.apply"
         ]
+      },
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": false,
+        "idempotentHint": false,
+        "openWorldHint": false,
+        "reversible": false,
+        "supportsDryRun": false,
+        "supportsTrackedChanges": true
       }
     }
   ]

package/tools/tools.openai.json

@@ -5,7 +5,7 @@
       "type": "function",
       "function": {
         "name": "superdoc_get_content",
-        "description": "Read document content. Use action \"info\" for structure and styles, \"blocks\" for all block IDs and types, \"text\" or \"markdown\" for content. Call info or blocks before editing.",
+        "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, formatting properties (fontFamily, fontSize, color, bold, underline, alignment), and ref handles for immediate use with superdoc_edit or superdoc_format. Action \"text\" and \"markdown\" return the full document as plain text or Markdown. Action \"html\" returns HTML. 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\", and filtering via \"nodeTypes\". Other actions ignore these 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.",
         "parameters": {
           "type": "object",
           "properties": {
@@ -61,7 +61,7 @@
       "type": "function",
       "function": {
         "name": "superdoc_edit",
-        "description": "Insert, replace, delete text, or undo/redo",
+        "description": "Refs expire after any mutation; always re-search before the next edit. Modify document text: insert new content, replace existing text, delete a range, or undo/redo. Use this for single text modifications. For 2+ edits that must succeed or fail atomically, use superdoc_mutations instead. For replace and delete, pass a \"ref\" from superdoc_search or superdoc_get_content blocks. 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. Insert supports plain text (default), markdown, or html via the \"type\" parameter. Use \"placement\" (before, after, insideStart, insideEnd) to control position relative to the target. 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.",
         "parameters": {
           "type": "object",
           "properties": {
@@ -283,7 +283,7 @@
                   ]
                 }
               ],
-              "description": "Target address object. Use 'ref' instead if you have a search handle. Format: {kind:'text', blockId, range:{start,end}} or {kind:'block', nodeType, nodeId}."
+              "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 from blocks list>'}."
             },
             "value": {
               "type": "string",
@@ -300,7 +300,7 @@
             },
             "ref": {
               "type": "string",
-              "description": "Handle ref string returned by a prior search/query result."
+              "description": "Handle ref from superdoc_search result (pass handle.ref value directly). Preferred over building a target object."
             },
             "content": {
               "oneOf": [
@@ -340,22 +340,6 @@
               },
               "description": "Controls nesting behavior. tables: 'allow' permits inserting tables inside other tables. Only for actions 'insert', 'replace'. Omit for other actions."
             },
-            "blockId": {
-              "type": "string",
-              "description": "Block ID of the target paragraph."
-            },
-            "start": {
-              "type": "number",
-              "description": "Start offset within the block (character index)."
-            },
-            "end": {
-              "type": "number",
-              "description": "End offset within the block (character index)."
-            },
-            "offset": {
-              "type": "number",
-              "description": "Character offset for insertion (alias for --start/--end with same value). Only for action 'insert'. Omit for other actions."
-            },
             "text": {
               "type": "string",
               "description": "Replacement text content. Only for action 'replace'. Omit for other actions."
@@ -380,7 +364,7 @@
       "type": "function",
       "function": {
         "name": "superdoc_format",
-        "description": "Change text and paragraph formatting. Use action \"inline\" with a search ref for bold/italic/etc. Use action \"set_style\" with a styleId from superdoc_get_content info to apply a named paragraph style.",
+        "description": "Change text and paragraph formatting. Use this after superdoc_create to style new content, or with a search ref to restyle existing text. 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:\"<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. Format one block at a time. Do NOT hardcode formatting values; always read them from superdoc_get_content blocks and replicate.",
         "parameters": {
           "type": "object",
           "properties": {
@@ -390,11 +374,12 @@
                 "inline",
                 "set_alignment",
                 "set_direction",
+                "set_flow_options",
                 "set_indentation",
                 "set_spacing",
                 "set_style"
               ],
-              "description": "The action to perform. One of: inline, set_alignment, set_direction, set_indentation, set_spacing, set_style."
+              "description": "The action to perform. One of: inline, set_alignment, set_direction, set_flow_options, set_indentation, set_spacing, set_style."
             },
             "force": {
               "type": "boolean",
@@ -569,7 +554,7 @@
                 "start",
                 "end"
               ],
-              "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_alignment', 'set_indentation', 'set_spacing', 'set_direction'."
+              "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_alignment', 'set_indentation', 'set_spacing', 'set_flow_options', 'set_direction'."
             },
             "inline": {
               "type": "object",
@@ -887,6 +872,18 @@
                 "atLeast"
               ]
             },
+            "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."
+            },
             "direction": {
               "type": "string",
               "enum": [
@@ -915,7 +912,7 @@
       "type": "function",
       "function": {
         "name": "superdoc_create",
-        "description": "Create one paragraph or heading per call. After creating, search for it and apply formatting (fontFamily, fontSize) from neighboring blocks. For multiple paragraphs, use superdoc_mutations with text.insert steps instead of calling create repeatedly.",
+        "description": "You MUST call superdoc_format after this tool to match document styling. Create a single paragraph, heading, or table in the document. Returns a nodeId for chaining subsequent creates and for use as a block target in superdoc_format. When the user asks for a \"heading\", use action \"heading\" with a level (default 1). Use action \"paragraph\" only when the user asks for regular body text. Before creating, call superdoc_get_content blocks to read formatting from regular body text paragraphs (non-empty, non-title blocks with alignment \"justify\" or \"left\"). After creating, re-fetch blocks with superdoc_get_content to get a fresh ref for the new block, then apply TWO format calls: (1) superdoc_format action \"inline\" for character styling, AND (2) superdoc_format action \"set_alignment\" with the block target for paragraph alignment. Both calls are REQUIRED. For body paragraphs: inline {bold:false, underline:false, fontFamily, fontSize, color from body blocks}, alignment \"justify\". Ignore underline:true from blocks data for body text; it is a style artifact. For headings: inline {bold:true, underline:true, fontSize scaled up, fontFamily, color}, alignment \"center\". 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.",
         "parameters": {
           "type": "object",
           "properties": {
@@ -923,9 +920,10 @@
               "type": "string",
               "enum": [
                 "heading",
-                "paragraph"
+                "paragraph",
+                "table"
               ],
-              "description": "The action to perform. One of: heading, paragraph."
+              "description": "The action to perform. One of: heading, paragraph, table."
             },
             "force": {
               "type": "boolean",
@@ -1069,6 +1067,14 @@
             "level": {
               "type": "number",
               "description": "Heading level (1-6). Required for action 'heading'."
+            },
+            "rows": {
+              "type": "number",
+              "description": "Required for action 'table'."
+            },
+            "columns": {
+              "type": "number",
+              "description": "Required for action 'table'."
             }
           },
           "required": [
@@ -1082,7 +1088,7 @@
       "type": "function",
       "function": {
         "name": "superdoc_list",
-        "description": "Create and manipulate lists",
+        "description": "Create and manipulate bullet and numbered lists. To create a list: first create all paragraphs at the SAME location using superdoc_create (chain each using the previous nodeId as the \"at\" target). Then call action \"create\" with mode:\"fromParagraphs\", a preset (\"disc\" for bullet, \"decimal\" for numbered), and a range target: {from:{kind:\"block\", nodeType:\"paragraph\", nodeId:\"<first>\"}, to:{kind:\"block\", nodeType:\"paragraph\", nodeId:\"<last>\"}}. The range converts ALL paragraphs between from and to into list items. Make sure no other content exists between them. Action \"set_type\" converts between bullet and ordered (target any item in the list, kind:\"ordered\" or \"bullet\"). Action \"insert\" adds a new item before/after a target list item. Actions \"indent\" and \"outdent\" change nesting level; \"set_level\" jumps to a specific level (0-8). Action \"detach\" converts a list item back to a plain paragraph. Do NOT target paragraphs with indent/outdent/set_type; these actions require a listItem target.",
         "parameters": {
           "type": "object",
           "properties": {
@@ -1339,7 +1345,7 @@
       "type": "function",
       "function": {
         "name": "superdoc_comment",
-        "description": "Comment threads — create, edit, delete",
+        "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: {kind:\"text\", blockId:\"<blockId>\", range:{start:<N>, end:<N>}} using the blockId and highlightRange from the search result. 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 status to \"resolved\" or marks as internal. Action \"delete\" removes a comment or reply by ID. Do NOT pass \"ref\", \"id\", or \"parentId\" when creating a new top-level comment; only \"action\", \"text\", and \"target\" are needed.",
         "parameters": {
           "type": "object",
           "properties": {
@@ -1446,7 +1452,7 @@
       "type": "function",
       "function": {
         "name": "superdoc_track_changes",
-        "description": "Review and resolve tracked changes",
+        "description": "Review and resolve tracked changes (insertions, deletions, format changes) in the document. Action \"list\" returns all tracked changes with optional filtering by type (insert, delete, 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:\"<changeId>\"} or all changes at once with {scope:\"all\"}. Do NOT use this tool unless the document has tracked changes. Use superdoc_get_content info to check the tracked change count first.",
         "parameters": {
           "type": "object",
           "properties": {
@@ -1536,7 +1542,7 @@
       "type": "function",
       "function": {
         "name": "superdoc_search",
-        "description": "Find text or nodes in the document",
+        "description": "Refs expire after any mutation; always re-search before the next edit. Find text patterns or nodes in the document and get ref handles for targeting edits and formatting. Use this to locate content before calling superdoc_edit or superdoc_format. 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, \"all\" returns every match, \"exactlyOne\" fails if not exactly one match. Supports scoping via \"within\" to search inside a single block. Do NOT use regex or markdown formatting markers (#, **, etc.) in search patterns; patterns are plain text only. Do NOT use this tool when you already have a ref from superdoc_get_content blocks or superdoc_create; use that ref directly.",
         "parameters": {
           "type": "object",
           "properties": {
@@ -1694,7 +1700,7 @@
       "type": "function",
       "function": {
         "name": "superdoc_mutations",
-        "description": "Atomic multi-step batch edits (escape hatch)",
+        "description": "All steps succeed or all fail; no partial application. Execute multiple text edits atomically in a single batch. Use this INSTEAD OF multiple sequential superdoc_edit calls when you need 2+ text changes that should succeed or fail together. Each step has an id (e.g. \"s1\"), an op (text.rewrite, text.insert, text.delete, format.apply, assert), a \"where\" clause for targeting ({by:\"select\", select:{...}, require:\"first\"|\"exactlyOne\"|\"all\"} or {by:\"ref\", ref:\"...\"}), and \"args\" with operation-specific parameters. Action \"preview\" dry-runs the plan without modifying the document. Action \"apply\" executes it. CRITICAL: split mutations by phase. Text mutations (text.rewrite, text.insert, text.delete) go in one call. Formatting (format.apply) goes in a separate call with fresh refs from a new superdoc_search. Do NOT create two steps that target overlapping text in the same block; combine them into a single text.rewrite step. Overlapping steps fail with PLAN_CONFLICT_OVERLAP. Do NOT use this for single edits; use superdoc_edit instead. Do NOT mix text mutations and formatting in the same call.",
         "parameters": {
           "type": "object",
           "properties": {