mcp-word-bridge 3.4.2 → 3.5.0

package/README.md

@@ -58,7 +58,7 @@ That's it. The MCP server starts automatically when your MCP client loads the co
 mcp-word-bridge/
 ├── index.js              # Entry point: HTTPS server + MCP handlers + WebSocket relay
 ├── lib/
-│   ├── tools.js          # Tool definitions (87) and action mapping
+│   ├── tools.js          # Tool definitions and action mapping
 │   ├── equations.js      # LaTeX→OMML pipeline (fixDelimiters, fixNaryOperands, latexToOmml)
 │   └── usage-guide.js    # MCP resource content (usage patterns for LLMs)
 ├── taskpane-app.js       # Client-side Word JS API logic (runs in add-in)
@@ -80,7 +80,7 @@ mcp-word-bridge/
 └── README.md
 ```
 
-## Tools (87)
+## Tools (90)
 
 ### Document
 | Tool | Description |
@@ -95,14 +95,18 @@ mcp-word-bridge/
 | `word_get_styles` | List available styles |
 | `word_get_coauthors` | Get co-authoring status and active authors |
 | `word_set_change_tracking` | Enable/disable track changes |
+| `word_get_document_outline` | Get heading hierarchy as a structured outline tree |
 
 ### Paragraphs
 | Tool | Description |
 |------|-------------|
 | `word_get_paragraphs` | Get paragraphs with style, alignment, TOC flag (paginated) |
 | `word_get_paragraph_by_index` | Get full details of one paragraph (font, spacing, indent) |
-| `word_insert_paragraph` | Insert a styled paragraph at Start or End |
+| `word_insert_paragraph` | Append/prepend a styled paragraph at document Start or End |
+| `word_insert_paragraph_at_index` | Insert a paragraph before or after a specific paragraph index |
 | `word_delete_paragraph` | Delete a paragraph by index |
+| `word_replace_paragraph_text` | Replace paragraph text by index (preserves style) |
+| `word_move_paragraph` | Move one or more consecutive paragraphs to another position |
 | `word_set_paragraph_style` | Change style or alignment of a paragraph |
 | `word_set_paragraph_spacing` | Set line spacing, before/after, and indentation |
 
@@ -111,7 +115,7 @@ mcp-word-bridge/
 |------|-------------|
 | `word_search` | Find text matches (case-insensitive by default) |
 | `word_search_and_replace` | Find and replace all occurrences |
-| `word_insert_text` | Insert text before or after a search match |
+| `word_insert_text_at_match` | Insert text before or after a search match |
 | `word_get_selection_info` | Get current selection with font details |
 | `word_insert_text_at_selection` | Insert or replace text at cursor |
 | `word_insert_line_break` | Insert a soft line break (Shift+Enter) |
@@ -127,7 +131,7 @@ mcp-word-bridge/
 | Tool | Description |
 |------|-------------|
 | `word_insert_table` | Insert a table with data and optional style |
-| `word_get_tables` | Get all tables with values and styles |
+| `word_list_tables` | List table metadata (count, dimensions, style) — no cell values |
 | `word_get_table_data` | Get cell values from a specific table |
 | `word_set_table_cell` | Set text in a cell |
 | `word_add_table_row` | Add a row with optional values |
@@ -148,13 +152,11 @@ mcp-word-bridge/
 | Tool | Description |
 |------|-------------|
 | `word_add_comment` | Add a comment anchored to text |
-| `word_get_comments` | Get all comments with author, date, status |
+| `word_get_comments` | Get all comments with author, date, status, and anchor text |
 | `word_get_comment_replies` | Get replies for a comment |
 | `word_reply_to_comment` | Reply to a comment |
 | `word_resolve_comment` | Mark a comment as resolved |
 | `word_delete_comment` | Delete a comment and its replies |
-| `word_get_comment_anchor` | Get the document text a comment is anchored to |
-| `word_get_comments_with_anchor` | Get all comments with their anchor text included |
 
 ### Footnotes & Endnotes
 | Tool | Description |
@@ -239,7 +241,12 @@ mcp-word-bridge/
 ### Equations
 | Tool | Description |
 |------|-------------|
-| `word_insert_equation` | Insert a LaTeX equation as a native editable Word equation. Supports display (centered block) and inline modes. |
+| `word_insert_equation` | Insert a LaTeX equation as a native editable Word equation. Display (block) or inline mode with optional anchor text positioning. |
+
+### Batch
+| Tool | Description |
+|------|-------------|
+| `word_batch` | Execute up to 50 operations in a single call. Native ops are bundled into one message to Word for maximum speed. |
 
 ## How it works
 
@@ -264,6 +271,8 @@ LaTeX → temml → MathML → mathml2omml → OMML → OOXML → Word
 
 - **Display mode** (`displayMode: true`, default): centered block equation on its own line
 - **Inline mode** (`displayMode: false`): inserted at the current cursor position within a paragraph
+  - With `anchorText`: searches for the text and inserts the equation after the match (recommended — no manual cursor positioning needed)
+  - Without `anchorText`: inserts at wherever the cursor currently is
 - Supports: fractions, roots, integrals, sums, products, matrices, Greek letters, piecewise functions, aligned systems, and all standard LaTeX math
 - Equations are fully editable in Word's built-in equation editor
 - Invalid LaTeX returns a descriptive error message

package/index.js

@@ -119,7 +119,7 @@ function sendToTaskpane(action, params) {
       return;
     }
     const id = String(++mcpRequestId);
-    const heavyOps = ['insertHtml', 'insertOoxml', 'getStyles', 'insertTableOfContents'];
+    const heavyOps = ['insertHtml', 'insertOoxml', 'getStyles', 'insertTableOfContents', 'batchExecute'];
     const timeoutMs = heavyOps.includes(action) ? 60000 : 30000;
     const timeout = setTimeout(() => {
       bridgePending.delete(id);
@@ -134,47 +134,211 @@ function sendToTaskpane(action, params) {
 }
 
 const mcpServer = new Server(
-  { name: 'mcp-word-bridge', version: '3.4.2' },
+  { name: 'mcp-word-bridge', version: '3.5.0' },
   { capabilities: { tools: {}, resources: {} } }
 );
 
 mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
 
-mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args } = request.params;
-
-  // Special handling for word_insert_equation (server-side LaTeX→OMML conversion)
+// Helper: execute a single tool call (used by both direct calls and batch)
+async function executeTool(name, args) {
+  // word_insert_equation: server-side LaTeX→OMML conversion
   if (name === 'word_insert_equation') {
+    const latex = args.latex;
+    const displayMode = args.displayMode !== false;
+
+    let result;
     try {
-      const latex = args.latex;
-      const displayMode = args.displayMode !== false;
+      const { mml2omml } = require('mathml2omml');
+      result = latexToOmml(latex, displayMode, mml2omml);
+    } catch (e) {
+      const msg = e.message.startsWith('LaTeX parse error') || e.message.startsWith('"latex"') ? e.message : 'Error: ' + e.message;
+      return { content: [{ type: 'text', text: msg }], isError: true };
+    }
 
-      // Convert LaTeX → OMML via lib/equations.js
-      let result;
-      try {
-        const { mml2omml } = require('mathml2omml');
-        result = latexToOmml(latex, displayMode, mml2omml);
-      } catch (e) {
-        return { content: [{ type: 'text', text: e.message.startsWith('LaTeX parse error') || e.message.startsWith('"latex"') ? e.message : 'Error: ' + e.message }], isError: true };
+    const cleanOmml = result.omml;
+    const ooxml = buildEquationOoxml(cleanOmml, displayMode);
+
+    if (displayMode) {
+      await sendToTaskpane('insertOoxml', { ooxml, location: args.location || 'End' });
+    } else if (args.anchorText) {
+      // Inline mode with anchor: search for anchor text, insert space+marker after it, insert equation at cursor, clean up marker
+      const marker = '\u200B\uFEFF'; // unique two-char sequence unlikely to exist in normal text
+      const searchResult = await sendToTaskpane('search', { query: args.anchorText, matchCase: args.matchCase || false });
+      if (!searchResult || searchResult.count === 0) throw new Error('Anchor not found: ' + args.anchorText);
+      const occurrence = args.occurrence || 0;
+      if (occurrence >= searchResult.count) throw new Error('Occurrence ' + occurrence + ' not found (only ' + searchResult.count + ' match' + (searchResult.count === 1 ? '' : 'es') + ')');
+      // Insert space + marker to position cursor (space ensures equation doesn't glue to preceding text)
+      await sendToTaskpane('insertText', { text: ' ' + marker, after: args.anchorText, occurrence: occurrence, matchCase: args.matchCase || false });
+      await sendToTaskpane('insertOoxmlAtSelection', { ooxml });
+      // Clean up the marker (space remains, giving proper separation)
+      await sendToTaskpane('searchAndReplace', { find: marker, replace: '' });
+    } else {
+      await sendToTaskpane('insertOoxmlAtSelection', { ooxml });
+    }
+    return { content: [{ type: 'text', text: JSON.stringify({ success: true, displayMode, latex }) }] };
+  }
+
+  // word_get_document_outline: server-side filtering of paragraphs by heading style
+  if (name === 'word_get_document_outline') {
+    const maxLevel = args.maxLevel !== undefined ? args.maxLevel : 3;
+    const result = await sendToTaskpane('getParagraphs', {});
+    const headings = [];
+    for (const para of result.paragraphs) {
+      const match = para.style && para.style.match(/^Heading (\d)$/i);
+      if (match) {
+        const level = parseInt(match[1], 10);
+        if (level <= maxLevel) {
+          headings.push({ level, text: para.text, index: para.index });
+        }
+      }
+    }
+    return { content: [{ type: 'text', text: JSON.stringify({ count: headings.length, outline: headings }, null, 2) }] };
+  }
+
+  // word_move_paragraph: atomic move (read text+style, delete, insert at new position)
+  // Supports moving multiple consecutive paragraphs via optional 'count' parameter
+  if (name === 'word_move_paragraph') {
+    const fromIndex = args.fromIndex;
+    const toIndex = args.toIndex;
+    const count = args.count || 1;
+    const location = args.location || 'After';
+    if (fromIndex < 0) throw new Error('fromIndex must be non-negative');
+    if (toIndex < 0) throw new Error('toIndex must be non-negative');
+    if (count < 1) throw new Error('count must be at least 1');
+    if (fromIndex === toIndex && count === 1) throw new Error('fromIndex and toIndex must be different');
+    // Validate all indices are in bounds before mutating
+    const paraCount = await sendToTaskpane('getParagraphs', {});
+    const total = paraCount.count;
+    if (fromIndex >= total) throw new Error('fromIndex ' + fromIndex + ' out of range. Document has ' + total + ' paragraphs (0-indexed).');
+    if (fromIndex + count - 1 >= total) throw new Error('fromIndex + count (' + (fromIndex + count) + ') exceeds paragraph count (' + total + ').');
+    if (toIndex >= total) throw new Error('toIndex ' + toIndex + ' out of range. Document has ' + total + ' paragraphs (0-indexed).');
+    // Collect all paragraphs to move (text + style)
+    const collected = [];
+    for (let i = 0; i < count; i++) {
+      const details = await sendToTaskpane('getParagraphByIndex', { index: fromIndex + i });
+      collected.push({ text: details.text, style: details.style });
+    }
+    // Delete from last to first to preserve indices during deletion
+    for (let i = count - 1; i >= 0; i--) {
+      await sendToTaskpane('deleteParagraph', { index: fromIndex + i });
+    }
+    // Adjust destination index after deletions
+    let adjustedTo;
+    if (fromIndex < toIndex) {
+      adjustedTo = toIndex - count;
+    } else {
+      adjustedTo = toIndex;
+    }
+    // Insert in order at destination
+    for (let i = 0; i < collected.length; i++) {
+      if (i === 0) {
+        await sendToTaskpane('insertParagraphAtIndex', { index: adjustedTo, text: collected[i].text, style: collected[i].style, location: location });
+      } else {
+        // After the first insert, the paragraph we just inserted is at a known position.
+        // For 'Before': first para went to adjustedTo, so second goes After adjustedTo.
+        // For 'After': first para went to adjustedTo+1, so second goes After adjustedTo+1.
+        const prevInsertedAt = location === 'Before' ? adjustedTo + (i - 1) : adjustedTo + i;
+        await sendToTaskpane('insertParagraphAtIndex', { index: prevInsertedAt, text: collected[i].text, style: collected[i].style, location: 'After' });
       }
+    }
+    return { content: [{ type: 'text', text: JSON.stringify({ success: true, moved: { from: fromIndex, count, to: adjustedTo, location } }) }] };
+  }
 
-      const cleanOmml = result.omml;
-      const ooxml = buildEquationOoxml(cleanOmml, displayMode);
+  // word_batch: execute multiple operations in a single call
+  if (name === 'word_batch') {
+    const operations = args.operations;
+    if (!operations || !Array.isArray(operations) || operations.length === 0) {
+      return { content: [{ type: 'text', text: 'Error: operations must be a non-empty array' }], isError: true };
+    }
+    if (operations.length > 50) {
+      return { content: [{ type: 'text', text: 'Error: maximum 50 operations per batch' }], isError: true };
+    }
 
-      const action = displayMode ? 'insertOoxml' : 'insertOoxmlAtSelection';
-      const params = displayMode ? { ooxml, location: args.location || 'End' } : { ooxml };
-      await sendToTaskpane(action, params);
-      return { content: [{ type: 'text', text: JSON.stringify({ success: true, displayMode, latex }) }] };
-    } catch (e) {
-      return { content: [{ type: 'text', text: 'Error: ' + e.message }], isError: true };
+    // Partition into taskpane-native ops (have action mapping) vs server-composed ops
+    const SERVER_HANDLED = new Set(['word_insert_equation', 'word_batch', 'word_get_document_outline', 'word_move_paragraph']);
+    const results = [];
+
+    // Collect consecutive taskpane-native ops into batches, flush when hitting a server op
+    let nativeBuf = [];
+
+    const flushNative = async () => {
+      if (nativeBuf.length === 0) return;
+      const batchOps = nativeBuf.map(item => ({
+        action: toolActionMap[item.tool],
+        params: item.args || {}
+      }));
+      const batchResult = await sendToTaskpane('batchExecute', { operations: batchOps });
+      for (const r of batchResult.results) {
+        const item = nativeBuf[r.index];
+        if (r.success) {
+          results.push({ index: item.originalIndex, tool: item.tool, success: true, result: r.result });
+        } else {
+          results.push({ index: item.originalIndex, tool: item.tool, success: false, error: r.error });
+          // Mark that we should stop
+          nativeBuf = [];
+          return false;
+        }
+      }
+      nativeBuf = [];
+      return true;
+    };
+
+    let stopped = false;
+    for (let i = 0; i < operations.length && !stopped; i++) {
+      const op = operations[i];
+      if (!op.tool) {
+        results.push({ index: i, tool: op.tool, success: false, error: 'Missing tool name' });
+        stopped = true;
+        break;
+      }
+
+      if (SERVER_HANDLED.has(op.tool)) {
+        // Flush any pending native ops first
+        const ok = await flushNative();
+        if (ok === false) { stopped = true; break; }
+        // Execute server-side
+        try {
+          const opResult = await executeTool(op.tool, op.args || {});
+          if (opResult.isError) {
+            results.push({ index: i, tool: op.tool, success: false, result: opResult.content[0].text });
+            stopped = true;
+          } else {
+            results.push({ index: i, tool: op.tool, success: true, result: JSON.parse(opResult.content[0].text) });
+          }
+        } catch (e) {
+          results.push({ index: i, tool: op.tool, success: false, error: e.message });
+          stopped = true;
+        }
+      } else if (toolActionMap[op.tool]) {
+        // Buffer taskpane-native op
+        nativeBuf.push({ tool: op.tool, args: op.args || {}, originalIndex: i });
+      } else {
+        // Flush pending, then report unknown tool
+        const ok = await flushNative();
+        if (ok === false) { stopped = true; break; }
+        results.push({ index: i, tool: op.tool, success: false, error: 'Unknown tool: ' + op.tool });
+        stopped = true;
+      }
     }
+    // Flush any remaining native ops
+    if (!stopped) await flushNative();
+
+    const succeeded = results.filter(r => r.success).length;
+    return { content: [{ type: 'text', text: JSON.stringify({ completed: succeeded, failed: results.length - succeeded, total: operations.length, results }, null, 2) }] };
   }
 
+  // Default: forward to taskpane via action map
   const action = toolActionMap[name];
   if (!action) return { content: [{ type: 'text', text: 'Unknown tool: ' + name }], isError: true };
+  const result = await sendToTaskpane(action, args || {});
+  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+}
+
+mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
   try {
-    const result = await sendToTaskpane(action, args || {});
-    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    return await executeTool(name, args || {});
   } catch (e) {
     return { content: [{ type: 'text', text: 'Error: ' + e.message }], isError: true };
   }

package/lib/tools.js

@@ -5,137 +5,140 @@
 
 const tools = [
   // 1. DOCUMENT
-  { name: 'word_get_text', description: 'Get full plain text of the active document. Use for overview; for structured content use get_paragraphs.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_get_document_properties', description: 'Get all document metadata including title, author, path, changeTrackingMode, template, security, and timestamps.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_set_document_properties', description: 'Set document metadata (title, subject, author, keywords, comments, category, company, manager, format).', inputSchema: { type: 'object', properties: { title: { type: 'string' }, subject: { type: 'string' }, author: { type: 'string' }, keywords: { type: 'string' }, comments: { type: 'string' }, category: { type: 'string' }, company: { type: 'string' }, manager: { type: 'string' }, format: { type: 'string' } } } },
-  { name: 'word_save', description: 'Save the document to disk.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_clear', description: 'Clear all document content (body, headers, footers). Leaves one empty Normal paragraph. Fast reset for testing.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_create_document', description: 'Create and open a new blank document in a new Word window. Optionally provide base64-encoded .docx as template. NOTE: the add-in stays in the original window — use word_clear to reset the current document instead.', inputSchema: { type: 'object', properties: { base64: { type: 'string', description: 'Optional base64-encoded .docx file to use as template' } } } },
-  { name: 'word_get_word_count', description: 'Get word, character, and paragraph counts.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_get_styles', description: 'Get available document styles.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_get_coauthors', description: 'Get current co-authors and coauthoring status.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_set_change_tracking', description: 'Set change tracking mode. Use TrackAll to show edits as tracked changes.', inputSchema: { type: 'object', properties: { mode: { type: 'string', enum: ['TrackAll', 'TrackMineOnly', 'Off'] } }, required: ['mode'] } },
+  { name: 'word_get_text', description: '[Document] Get full plain text of the active document. Use for a quick overview; for structured content with styles use word_get_paragraphs instead.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'word_get_document_properties', description: '[Document] Get all document metadata including title, author, path, changeTrackingMode, template, security, and timestamps.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'word_set_document_properties', description: '[Document] Set document metadata (title, subject, author, keywords, comments, category, company, manager, format).', inputSchema: { type: 'object', properties: { title: { type: 'string' }, subject: { type: 'string' }, author: { type: 'string' }, keywords: { type: 'string' }, comments: { type: 'string' }, category: { type: 'string' }, company: { type: 'string' }, manager: { type: 'string' }, format: { type: 'string' } } } },
+  { name: 'word_save', description: '[Document] Save the document to disk.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'word_clear', description: '[Document] Clear all document body content. Leaves one empty Normal paragraph. Fast reset — does not clear headers/footers or custom properties.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'word_create_document', description: '[Document] Create and open a new blank document in a new Word window. Optionally provide base64-encoded .docx as template. NOTE: the add-in stays in the original window — use word_clear to reset the current document instead.', inputSchema: { type: 'object', properties: { base64: { type: 'string', description: 'Optional base64-encoded .docx file to use as template' } } } },
+  { name: 'word_get_word_count', description: '[Document] Get word, character, and paragraph counts.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'word_get_styles', description: '[Document] Get available document styles (returns up to 80 styles with name, type, and builtIn flag).', inputSchema: { type: 'object', properties: {} } },
+  { name: 'word_get_coauthors', description: '[Document] Get current co-authors and coauthoring status (Desktop only).', inputSchema: { type: 'object', properties: {} } },
+  { name: 'word_set_change_tracking', description: '[Document] Set change tracking mode. Call with "TrackAll" BEFORE making edits to show them as tracked changes.', inputSchema: { type: 'object', properties: { mode: { type: 'string', enum: ['TrackAll', 'TrackMineOnly', 'Off'] } }, required: ['mode'] } },
+  { name: 'word_get_document_outline', description: '[Document] Get the document heading hierarchy as a structured outline tree. Returns headings with their level, text, and paragraph index — useful for understanding document structure before editing.', inputSchema: { type: 'object', properties: { maxLevel: { type: 'number', description: 'Maximum heading level to include (1-9). Default: 3 (includes Heading 1, 2, 3)' } } } },
   // 2. PARAGRAPHS
-  { name: 'word_get_paragraphs', description: 'Get paragraphs with text, style, alignment, isTocEntry. Optional start/end index range for pagination.', inputSchema: { type: 'object', properties: { start: { type: 'number' }, end: { type: 'number' } } } },
-  { name: 'word_get_paragraph_by_index', description: 'Get full details of a single paragraph including font, spacing, indentation, and outline level.', inputSchema: { type: 'object', properties: { index: { type: 'number' } }, required: ['index'] } },
-  { name: 'word_insert_paragraph', description: 'Insert a styled paragraph at Start or End. Specify style (e.g. "Heading 1", "Heading 2", "Normal") and optional alignment (Left, Center, Right, Justified).', inputSchema: { type: 'object', properties: { text: { type: 'string' }, location: { type: 'string', enum: ['Start', 'End'] }, style: { type: 'string' }, alignment: { type: 'string', description: 'Paragraph alignment: Left, Center, Right, or Justified' } }, required: ['text'] } },
-  { name: 'word_delete_paragraph', description: 'Delete a paragraph by its index.', inputSchema: { type: 'object', properties: { index: { type: 'number' } }, required: ['index'] } },
-  { name: 'word_set_paragraph_style', description: 'Change the style or alignment of a paragraph by index. Alignment accepts: Left, Center, Right, Justified.', inputSchema: { type: 'object', properties: { index: { type: 'number' }, style: { type: 'string' }, alignment: { type: 'string', description: 'Paragraph alignment: Left, Center, Right, or Justified' } }, required: ['index'] } },
-  { name: 'word_set_paragraph_spacing', description: 'Set line spacing (in points, e.g. 12=single for 12pt font, 24=double), before/after spacing (points), and indentation (points) on a paragraph by index.', inputSchema: { type: 'object', properties: { index: { type: 'number' }, lineSpacing: { type: 'number', description: 'Line spacing in points (e.g. 12=single for 12pt, 18=1.5x, 24=double)' }, spaceBefore: { type: 'number', description: 'Space before paragraph in points' }, spaceAfter: { type: 'number', description: 'Space after paragraph in points' }, firstLineIndent: { type: 'number', description: 'First line indent in points' }, leftIndent: { type: 'number', description: 'Left indent in points' }, rightIndent: { type: 'number', description: 'Right indent in points' } }, required: ['index'] } },
+  { name: 'word_get_paragraphs', description: '[Paragraphs] Get paragraphs with text, style, alignment, and isTocEntry flag. Supports pagination via optional start/end index range (0-based). Returns total paragraph count.', inputSchema: { type: 'object', properties: { start: { type: 'number', description: 'First paragraph index to return (0-based, inclusive)' }, end: { type: 'number', description: 'Last paragraph index (exclusive). Omit to get all from start.' } } } },
+  { name: 'word_get_paragraph_by_index', description: '[Paragraphs] Get full details of a single paragraph including font, spacing, indentation, and outline level.', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Paragraph index (0-based)' } }, required: ['index'] } },
+  { name: 'word_insert_paragraph', description: '[Paragraphs] Append or prepend a styled paragraph to the document (Start or End only). For inserting at a specific position, use word_insert_paragraph_at_index instead.', inputSchema: { type: 'object', properties: { text: { type: 'string' }, location: { type: 'string', enum: ['Start', 'End'], description: 'Where in the document. Default: End' }, style: { type: 'string', description: 'Paragraph style (e.g. "Heading 1", "Normal"). Default: Normal' }, alignment: { type: 'string', description: 'Paragraph alignment: Left, Center, Right, or Justified' } }, required: ['text'] } },
+  { name: 'word_insert_paragraph_at_index', description: '[Paragraphs] Insert a new paragraph Before or After a specific paragraph index. Use this for precise positioning within the document (preferred over word_insert_paragraph for mid-document insertions).', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Reference paragraph index (0-based)' }, text: { type: 'string', description: 'Text content for the new paragraph' }, location: { type: 'string', enum: ['Before', 'After'], description: 'Insert before or after the reference paragraph. Default: After' }, style: { type: 'string', description: 'Paragraph style (e.g. "Heading 1", "Normal")' } }, required: ['index', 'text'] } },
+  { name: 'word_delete_paragraph', description: '[Paragraphs] Delete a paragraph by its 0-based index.', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Paragraph index (0-based)' } }, required: ['index'] } },
+  { name: 'word_replace_paragraph_text', description: '[Paragraphs] Replace the entire text of a paragraph by index. Preserves style/formatting. Preferred over word_search_and_replace in collaborative editing (targets by position, immune to text-drift).', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Paragraph index (0-based)' }, text: { type: 'string', description: 'New text content for the paragraph' } }, required: ['index', 'text'] } },
+  { name: 'word_move_paragraph', description: '[Paragraphs] Move a paragraph from one position to another. Handles the delete+insert atomically with correct index adjustment.', inputSchema: { type: 'object', properties: { fromIndex: { type: 'number', description: 'Source paragraph index (0-based)' }, toIndex: { type: 'number', description: 'Destination paragraph index (0-based, position after removal)' }, location: { type: 'string', enum: ['Before', 'After'], description: 'Insert before or after the destination index. Default: After' }, count: { type: 'number', description: 'Number of consecutive paragraphs to move (default: 1). Use to move a heading + its body together.' } }, required: ['fromIndex', 'toIndex'] } },
+  { name: 'word_set_paragraph_style', description: '[Paragraphs] Change the style or alignment of a paragraph by index. Alignment accepts: Left, Center, Right, Justified.', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Paragraph index (0-based)' }, style: { type: 'string' }, alignment: { type: 'string', description: 'Paragraph alignment: Left, Center, Right, or Justified' } }, required: ['index'] } },
+  { name: 'word_set_paragraph_spacing', description: '[Paragraphs] Set line spacing (in points: 12=single for 12pt font, 18=1.5x, 24=double), before/after spacing, and indentation on a paragraph by index.', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Paragraph index (0-based)' }, lineSpacing: { type: 'number', description: 'Line spacing in points (e.g. 12=single for 12pt, 18=1.5x, 24=double)' }, spaceBefore: { type: 'number', description: 'Space before paragraph in points' }, spaceAfter: { type: 'number', description: 'Space after paragraph in points' }, firstLineIndent: { type: 'number', description: 'First line indent in points' }, leftIndent: { type: 'number', description: 'Left indent in points' }, rightIndent: { type: 'number', description: 'Right indent in points' } }, required: ['index'] } },
   // 3. SEARCH & TEXT
-  { name: 'word_search', description: 'Search for text in the document (case-insensitive by default). Query must be non-empty and ≤255 chars. Returns match count and up to 30 matches with their text. Supports Word wildcards (e.g. ^p for paragraph mark).', inputSchema: { type: 'object', properties: { query: { type: 'string' }, matchCase: { type: 'boolean', description: 'Case-sensitive search. Default: false' }, matchWholeWord: { type: 'boolean' } }, required: ['query'] } },
-  { name: 'word_search_and_replace', description: 'Find and replace all occurrences of text (case-insensitive by default). Returns replacement count. Note: if find equals replace, Word still reports it as a replacement (the text is rewritten in-place). Supports Word wildcards (e.g. ^p for paragraph mark).', inputSchema: { type: 'object', properties: { find: { type: 'string' }, replace: { type: 'string' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' }, matchWholeWord: { type: 'boolean' } }, required: ['find', 'replace'] } },
-  { name: 'word_insert_text', description: 'Insert text before or after a search match. Provide "after" OR "before" (not both) as the anchor string to locate.', inputSchema: { type: 'object', properties: { text: { type: 'string' }, after: { type: 'string' }, before: { type: 'string' }, occurrence: { type: 'number', description: '0-indexed match to target (0=first, 1=second, etc)' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false (case-insensitive)' } }, required: ['text'] } },
-  { name: 'word_get_selection_info', description: 'Get the current selection text with full font and style details.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_insert_text_at_selection', description: 'Insert text at the current cursor position, or replace the current selection (set replace=true).', inputSchema: { type: 'object', properties: { text: { type: 'string' }, replace: { type: 'boolean', description: 'Replace current selection instead of appending. Default: false' } }, required: ['text'] } },
-  { name: 'word_insert_line_break', description: 'Insert a soft line break (Shift+Enter) before or after a text match.', inputSchema: { type: 'object', properties: { anchorText: { type: 'string' }, before: { type: 'boolean' }, occurrence: { type: 'number', description: '0-indexed match to target (0=first, 1=second, etc)' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false (case-insensitive)' } }, required: ['anchorText'] } },
+  { name: 'word_search', description: '[Search] Find text in the document (case-insensitive by default). Returns match count and up to 30 matches. Query must be ≤255 chars. Supports Word wildcards (^p for paragraph mark).', inputSchema: { type: 'object', properties: { query: { type: 'string' }, matchCase: { type: 'boolean', description: 'Case-sensitive search. Default: false' }, matchWholeWord: { type: 'boolean' } }, required: ['query'] } },
+  { name: 'word_search_and_replace', description: '[Search] Find and replace ALL occurrences (case-insensitive by default). Returns replacement count. For single-paragraph edits, prefer word_replace_paragraph_text (safer in collaborative docs).', inputSchema: { type: 'object', properties: { find: { type: 'string' }, replace: { type: 'string' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' }, matchWholeWord: { type: 'boolean' } }, required: ['find', 'replace'] } },
+  { name: 'word_insert_text_at_match', description: '[Search] Insert text before or after a SEARCH MATCH. First searches for the anchor string, then inserts adjacent to it. Provide "after" OR "before" (not both) as the anchor text to locate. Use occurrence (0-indexed) to target the Nth match.', inputSchema: { type: 'object', properties: { text: { type: 'string', description: 'Text to insert' }, after: { type: 'string', description: 'Search for this text and insert AFTER it' }, before: { type: 'string', description: 'Search for this text and insert BEFORE it' }, occurrence: { type: 'number', description: 'Which match to target: 0=first, 1=second, etc. Default: 0' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' } }, required: ['text'] } },
+  { name: 'word_get_selection_info', description: '[Search] Get the current cursor selection text with full font and style details.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'word_insert_text_at_selection', description: '[Search] Insert text at the current cursor position, or replace the current selection (set replace=true). Cursor moves to end of inserted text.', inputSchema: { type: 'object', properties: { text: { type: 'string' }, replace: { type: 'boolean', description: 'Replace current selection instead of appending. Default: false' } }, required: ['text'] } },
+  { name: 'word_insert_line_break', description: '[Search] Insert a soft line break (Shift+Enter) before or after a text match.', inputSchema: { type: 'object', properties: { anchorText: { type: 'string', description: 'Text to search for as anchor point' }, before: { type: 'boolean', description: 'Insert before the match (default: after)' }, occurrence: { type: 'number', description: 'Which match to target: 0=first, 1=second, etc. Default: 0' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' } }, required: ['anchorText'] } },
   // 4. FORMATTING
-  { name: 'word_format_text', description: 'Apply formatting (bold, italic, color, size, font) to a text match found by search. Color must be hex (e.g. #FF0000). Size range: 1-1638 points.', inputSchema: { type: 'object', properties: { text: { type: 'string' }, occurrence: { type: 'number', description: '0-indexed match to target (0=first, 1=second, etc)' }, bold: { type: 'boolean' }, italic: { type: 'boolean' }, underline: { type: 'boolean' }, strikeThrough: { type: 'boolean' }, color: { type: 'string', description: 'Hex color e.g. #FF0000' }, highlightColor: { type: 'string' }, size: { type: 'number', description: 'Font size in points (1-1638)' }, name: { type: 'string', description: 'Font name' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false (case-insensitive)' } }, required: ['text'] } },
-  { name: 'word_clear_formatting', description: 'Clear direct formatting from a text match, reverting it to the paragraph style defaults.', inputSchema: { type: 'object', properties: { text: { type: 'string' }, occurrence: { type: 'number', description: '0-indexed match to target (0=first, 1=second, etc)' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false (case-insensitive)' } }, required: ['text'] } },
-  { name: 'word_get_font_info', description: 'Inspect font properties (name, size, bold, italic, color) of a text match.', inputSchema: { type: 'object', properties: { text: { type: 'string' }, occurrence: { type: 'number', description: '0-indexed match to target (0=first, 1=second, etc)' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false (case-insensitive)' } }, required: ['text'] } },
+  { name: 'word_format_text', description: '[Formatting] Apply formatting (bold, italic, color, size, font) to a text match found by search. Color must be hex (#FF0000). Size: 1-1638pt.', inputSchema: { type: 'object', properties: { text: { type: 'string', description: 'Text to search for and format' }, occurrence: { type: 'number', description: 'Which match to target: 0=first, 1=second, etc. Default: 0' }, bold: { type: 'boolean' }, italic: { type: 'boolean' }, underline: { type: 'boolean' }, strikeThrough: { type: 'boolean' }, color: { type: 'string', description: 'Hex color e.g. #FF0000' }, highlightColor: { type: 'string' }, size: { type: 'number', description: 'Font size in points (1-1638)' }, name: { type: 'string', description: 'Font name' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' } }, required: ['text'] } },
+  { name: 'word_clear_formatting', description: '[Formatting] Clear direct formatting from a text match, reverting it to the paragraph style defaults.', inputSchema: { type: 'object', properties: { text: { type: 'string', description: 'Text to search for' }, occurrence: { type: 'number', description: 'Which match to target: 0=first, 1=second, etc. Default: 0' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' } }, required: ['text'] } },
+  { name: 'word_get_font_info', description: '[Formatting] Inspect font properties (name, size, bold, italic, color) of a text match.', inputSchema: { type: 'object', properties: { text: { type: 'string', description: 'Text to search for' }, occurrence: { type: 'number', description: 'Which match to target: 0=first, 1=second, etc. Default: 0' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' } }, required: ['text'] } },
   // 5. TABLES
-  { name: 'word_insert_table', description: 'Insert a table with data. Provide rows (1-500), cols (1-63), and data as array of arrays (e.g. [["A","B"],["C","D"]]).', inputSchema: { type: 'object', properties: { rows: { type: 'number' }, cols: { type: 'number' }, data: { type: 'array', items: { type: 'array', items: { type: 'string' } } }, location: { type: 'string', enum: ['Start', 'End'] }, style: { type: 'string' }, headerRowCount: { type: 'number' } }, required: ['rows', 'cols'] } },
-  { name: 'word_get_tables', description: 'Get all tables with row counts, styles, and cell values.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_get_table_data', description: 'Get all cell values from a specific table by index.', inputSchema: { type: 'object', properties: { index: { type: 'number' } }, required: ['index'] } },
-  { name: 'word_set_table_cell', description: 'Set text in a specific table cell by tableIndex, row, and col.', inputSchema: { type: 'object', properties: { tableIndex: { type: 'number' }, row: { type: 'number' }, col: { type: 'number' }, text: { type: 'string' } }, required: ['tableIndex', 'row', 'col', 'text'] } },
-  { name: 'word_add_table_row', description: 'Add a row to a table with optional cell values.', inputSchema: { type: 'object', properties: { tableIndex: { type: 'number' }, values: { type: 'array', items: { type: 'string' } }, location: { type: 'string', enum: ['Start', 'End'] } }, required: ['tableIndex'] } },
-  { name: 'word_delete_table_row', description: 'Delete a row from a table by tableIndex and rowIndex.', inputSchema: { type: 'object', properties: { tableIndex: { type: 'number' }, rowIndex: { type: 'number' } }, required: ['tableIndex', 'rowIndex'] } },
-  { name: 'word_merge_table_cells', description: 'Merge a rectangular range of cells (topRow/firstCell to bottomRow/lastCell).', inputSchema: { type: 'object', properties: { tableIndex: { type: 'number' }, topRow: { type: 'number' }, firstCell: { type: 'number' }, bottomRow: { type: 'number' }, lastCell: { type: 'number' } }, required: ['tableIndex', 'topRow', 'firstCell', 'bottomRow', 'lastCell'] } },
-  { name: 'word_split_table_cell', description: 'Split a table cell into multiple rows/columns.', inputSchema: { type: 'object', properties: { tableIndex: { type: 'number' }, row: { type: 'number' }, col: { type: 'number' }, rowCount: { type: 'number' }, colCount: { type: 'number' } }, required: ['tableIndex', 'row', 'col'] } },
-  { name: 'word_set_table_style', description: 'Apply a built-in table style (e.g. "Grid Table 4 - Accent 1").', inputSchema: { type: 'object', properties: { tableIndex: { type: 'number' }, style: { type: 'string' } }, required: ['tableIndex', 'style'] } },
-  { name: 'word_set_table_cell_shading', description: 'Set background color on a table cell.', inputSchema: { type: 'object', properties: { tableIndex: { type: 'number' }, row: { type: 'number' }, col: { type: 'number' }, color: { type: 'string', description: 'Hex color e.g. #FFD700' } }, required: ['tableIndex', 'row', 'col', 'color'] } },
+  { name: 'word_insert_table', description: '[Tables] Insert a table with data. Provide rows (1-500), cols (1-63), and data as array of arrays (e.g. [["A","B"],["C","D"]]). Data dimensions must match rows×cols.', inputSchema: { type: 'object', properties: { rows: { type: 'number' }, cols: { type: 'number' }, data: { type: 'array', items: { type: 'array', items: { type: 'string' } }, description: 'Cell values as array of row arrays. Must have exactly rows×cols dimensions.' }, location: { type: 'string', enum: ['Start', 'End'] }, style: { type: 'string', description: 'Table style name (e.g. "Grid Table 4 - Accent 1")' }, headerRowCount: { type: 'number' } }, required: ['rows', 'cols'] } },
+  { name: 'word_list_tables', description: '[Tables] List table metadata: count, rowCount, columnCount, style, headerRowCount for each table. Does NOT return cell values — use word_get_table_data for cell content.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'word_get_table_data', description: '[Tables] Get all cell values from a specific table as a 2D array. Use word_list_tables first to find the table index.', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Table index (0-based)' } }, required: ['index'] } },
+  { name: 'word_set_table_cell', description: '[Tables] Set text in a specific table cell.', inputSchema: { type: 'object', properties: { tableIndex: { type: 'number', description: 'Table index (0-based)' }, row: { type: 'number', description: 'Row index (0-based)' }, col: { type: 'number', description: 'Column index (0-based)' }, text: { type: 'string' } }, required: ['tableIndex', 'row', 'col', 'text'] } },
+  { name: 'word_add_table_row', description: '[Tables] Add a row to a table with optional cell values.', inputSchema: { type: 'object', properties: { tableIndex: { type: 'number', description: 'Table index (0-based)' }, values: { type: 'array', items: { type: 'string' }, description: 'Cell values for the new row' }, location: { type: 'string', enum: ['Start', 'End'], description: 'Add at start or end of table. Default: End' } }, required: ['tableIndex'] } },
+  { name: 'word_delete_table_row', description: '[Tables] Delete a row from a table.', inputSchema: { type: 'object', properties: { tableIndex: { type: 'number', description: 'Table index (0-based)' }, rowIndex: { type: 'number', description: 'Row index (0-based)' } }, required: ['tableIndex', 'rowIndex'] } },
+  { name: 'word_merge_table_cells', description: '[Tables] Merge a rectangular range of cells (topRow/firstCell to bottomRow/lastCell). All indices 0-based.', inputSchema: { type: 'object', properties: { tableIndex: { type: 'number' }, topRow: { type: 'number' }, firstCell: { type: 'number' }, bottomRow: { type: 'number' }, lastCell: { type: 'number' } }, required: ['tableIndex', 'topRow', 'firstCell', 'bottomRow', 'lastCell'] } },
+  { name: 'word_split_table_cell', description: '[Tables] Split a table cell into multiple rows/columns.', inputSchema: { type: 'object', properties: { tableIndex: { type: 'number' }, row: { type: 'number' }, col: { type: 'number' }, rowCount: { type: 'number', description: 'Split into this many rows. Default: 1' }, colCount: { type: 'number', description: 'Split into this many columns. Default: 2' } }, required: ['tableIndex', 'row', 'col'] } },
+  { name: 'word_set_table_style', description: '[Tables] Apply a built-in table style (e.g. "Grid Table 4 - Accent 1").', inputSchema: { type: 'object', properties: { tableIndex: { type: 'number' }, style: { type: 'string' } }, required: ['tableIndex', 'style'] } },
+  { name: 'word_set_table_cell_shading', description: '[Tables] Set background color on a table cell. Color must be hex (e.g. #FFD700).', inputSchema: { type: 'object', properties: { tableIndex: { type: 'number' }, row: { type: 'number' }, col: { type: 'number' }, color: { type: 'string', description: 'Hex color e.g. #FFD700' } }, required: ['tableIndex', 'row', 'col', 'color'] } },
   // 6. LISTS
-  { name: 'word_insert_list', description: 'Insert a bulleted or numbered list from an array of item strings.', inputSchema: { type: 'object', properties: { items: { type: 'array', items: { type: 'string' } }, numbered: { type: 'boolean' }, location: { type: 'string', enum: ['Start', 'End'] } }, required: ['items'] } },
-  { name: 'word_get_list_info', description: 'Get list formatting details (level, numbering) for a paragraph by index.', inputSchema: { type: 'object', properties: { index: { type: 'number' } }, required: ['index'] } },
-  { name: 'word_set_list_level', description: 'Set indent level of a list item (0=top, 1=sub-item, etc).', inputSchema: { type: 'object', properties: { index: { type: 'number' }, level: { type: 'number' } }, required: ['index', 'level'] } },
+  { name: 'word_insert_list', description: '[Lists] Insert a bulleted or numbered list from an array of item strings.', inputSchema: { type: 'object', properties: { items: { type: 'array', items: { type: 'string' }, description: 'List item strings' }, numbered: { type: 'boolean', description: 'true = numbered list, false/omit = bulleted' }, location: { type: 'string', enum: ['Start', 'End'] } }, required: ['items'] } },
+  { name: 'word_get_list_info', description: '[Lists] Get list formatting details (level, numbering) for a paragraph by index. Returns isListItem:false if not in a list.', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Paragraph index (0-based)' } }, required: ['index'] } },
+  { name: 'word_set_list_level', description: '[Lists] Set indent level of a list item (0=top level, 1=sub-item, up to 8).', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Paragraph index (0-based)' }, level: { type: 'number', description: 'Indent level: 0-8' } }, required: ['index', 'level'] } },
   // 7. COMMENTS
-  { name: 'word_add_comment', description: 'Add a review comment anchored to a text match in the document.', inputSchema: { type: 'object', properties: { anchorText: { type: 'string' }, comment: { type: 'string' }, occurrence: { type: 'number', description: '0-indexed match to target (0=first, 1=second, etc)' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false (case-insensitive)' } }, required: ['anchorText', 'comment'] } },
-  { name: 'word_get_comments', description: 'Get all comments with ID, author, content, date, and resolved status.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_get_comment_replies', description: 'Get all replies for a specific comment by ID.', inputSchema: { type: 'object', properties: { commentId: { type: 'string' } }, required: ['commentId'] } },
-  { name: 'word_reply_to_comment', description: 'Reply to a comment by its ID (from get_comments).', inputSchema: { type: 'object', properties: { commentId: { type: 'string' }, text: { type: 'string' } }, required: ['commentId', 'text'] } },
-  { name: 'word_resolve_comment', description: 'Mark a comment as resolved by its ID.', inputSchema: { type: 'object', properties: { commentId: { type: 'string' } }, required: ['commentId'] } },
-  { name: 'word_delete_comment', description: 'Delete a comment and its replies by ID.', inputSchema: { type: 'object', properties: { commentId: { type: 'string' } }, required: ['commentId'] } },
-  { name: 'word_get_comment_anchor', description: 'Get the document text that a comment is anchored to (the highlighted/marked text the comment refers to).', inputSchema: { type: 'object', properties: { commentId: { type: 'string' } }, required: ['commentId'] } },
-  { name: 'word_get_comments_with_anchor', description: 'Get all comments with ID, author, content, date, resolved status, AND the anchor text each comment is attached to.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'word_add_comment', description: '[Comments] Add a review comment anchored to a text match. IMPORTANT: Read word_get_comments before bulk text replacements to avoid damaging comment anchors.', inputSchema: { type: 'object', properties: { anchorText: { type: 'string', description: 'Text to search for as comment anchor' }, comment: { type: 'string', description: 'Comment text' }, occurrence: { type: 'number', description: 'Which match to target: 0=first, 1=second, etc. Default: 0' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' } }, required: ['anchorText', 'comment'] } },
+  { name: 'word_get_comments', description: '[Comments] Get all comments with ID, author, content, date, resolved status, and the anchor text each comment is attached to. Call this BEFORE any bulk text replacements.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'word_get_comment_replies', description: '[Comments] Get all replies for a specific comment by its ID (from word_get_comments).', inputSchema: { type: 'object', properties: { commentId: { type: 'string' } }, required: ['commentId'] } },
+  { name: 'word_reply_to_comment', description: '[Comments] Reply to a comment thread by its ID.', inputSchema: { type: 'object', properties: { commentId: { type: 'string' }, text: { type: 'string' } }, required: ['commentId', 'text'] } },
+  { name: 'word_resolve_comment', description: '[Comments] Mark a comment as resolved (hides in Word UI, preserves audit trail). Preferred over delete.', inputSchema: { type: 'object', properties: { commentId: { type: 'string' } }, required: ['commentId'] } },
+  { name: 'word_delete_comment', description: '[Comments] Permanently delete a comment and all its replies. Prefer word_resolve_comment to preserve history.', inputSchema: { type: 'object', properties: { commentId: { type: 'string' } }, required: ['commentId'] } },
   // 8. FOOTNOTES & ENDNOTES
-  { name: 'word_insert_footnote', description: 'Insert a footnote anchored to a text match.', inputSchema: { type: 'object', properties: { anchorText: { type: 'string' }, text: { type: 'string' }, occurrence: { type: 'number', description: '0-indexed match to target (0=first, 1=second, etc)' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false (case-insensitive)' } }, required: ['anchorText', 'text'] } },
-  { name: 'word_insert_footnote_at_index', description: 'Insert a footnote at the end of a paragraph by index (no search needed).', inputSchema: { type: 'object', properties: { paragraphIndex: { type: 'number' }, text: { type: 'string' } }, required: ['paragraphIndex', 'text'] } },
-  { name: 'word_insert_endnote', description: 'Insert an endnote anchored to a text match.', inputSchema: { type: 'object', properties: { anchorText: { type: 'string' }, text: { type: 'string' }, occurrence: { type: 'number', description: '0-indexed match to target (0=first, 1=second, etc)' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false (case-insensitive)' } }, required: ['anchorText', 'text'] } },
-  { name: 'word_get_footnotes', description: 'Get all footnotes with index and text content.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_get_endnotes', description: 'Get all endnotes with index and text content.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_delete_footnote', description: 'Delete a footnote by its index (0-based).', inputSchema: { type: 'object', properties: { index: { type: 'number' } }, required: ['index'] } },
-  { name: 'word_delete_endnote', description: 'Delete an endnote by its index (0-based).', inputSchema: { type: 'object', properties: { index: { type: 'number' } }, required: ['index'] } },
+  { name: 'word_insert_footnote', description: '[Footnotes] Insert a footnote anchored to a text match (searches for anchorText, attaches footnote there).', inputSchema: { type: 'object', properties: { anchorText: { type: 'string', description: 'Text to search for as anchor point' }, text: { type: 'string', description: 'Footnote content' }, occurrence: { type: 'number', description: 'Which match to target: 0=first, 1=second, etc. Default: 0' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' } }, required: ['anchorText', 'text'] } },
+  { name: 'word_insert_footnote_at_index', description: '[Footnotes] Insert a footnote at the end of a paragraph by index (no search needed — use when you know the paragraph position).', inputSchema: { type: 'object', properties: { paragraphIndex: { type: 'number', description: 'Paragraph index (0-based)' }, text: { type: 'string', description: 'Footnote content' } }, required: ['paragraphIndex', 'text'] } },
+  { name: 'word_insert_endnote', description: '[Footnotes] Insert an endnote anchored to a text match.', inputSchema: { type: 'object', properties: { anchorText: { type: 'string', description: 'Text to search for as anchor point' }, text: { type: 'string', description: 'Endnote content' }, occurrence: { type: 'number', description: 'Which match to target: 0=first, 1=second, etc. Default: 0' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' } }, required: ['anchorText', 'text'] } },
+  { name: 'word_get_footnotes', description: '[Footnotes] Get all footnotes with index and text content.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'word_get_endnotes', description: '[Footnotes] Get all endnotes with index and text content.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'word_delete_footnote', description: '[Footnotes] Delete a footnote by its 0-based index.', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Footnote index (0-based)' } }, required: ['index'] } },
+  { name: 'word_delete_endnote', description: '[Footnotes] Delete an endnote by its 0-based index.', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Endnote index (0-based)' } }, required: ['index'] } },
   // 9. TRACK CHANGES
-  { name: 'word_get_tracked_changes', description: 'Get all tracked changes with index, type, author, date, and text.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_accept_tracked_change', description: 'Accept a tracked change by index.', inputSchema: { type: 'object', properties: { index: { type: 'number' } }, required: ['index'] } },
-  { name: 'word_reject_tracked_change', description: 'Reject a tracked change by index.', inputSchema: { type: 'object', properties: { index: { type: 'number' } }, required: ['index'] } },
-  { name: 'word_accept_all_tracked_changes', description: 'Accept all tracked changes.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_reject_all_tracked_changes', description: 'Reject all tracked changes.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'word_get_tracked_changes', description: '[Track Changes] Get all tracked changes with index, type (Added/Deleted), author, date, and text.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'word_accept_tracked_change', description: '[Track Changes] Accept a single tracked change by its index.', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Change index (0-based, from word_get_tracked_changes)' } }, required: ['index'] } },
+  { name: 'word_reject_tracked_change', description: '[Track Changes] Reject a single tracked change by its index.', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Change index (0-based, from word_get_tracked_changes)' } }, required: ['index'] } },
+  { name: 'word_accept_all_tracked_changes', description: '[Track Changes] Accept all tracked changes at once.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'word_reject_all_tracked_changes', description: '[Track Changes] Reject all tracked changes at once.', inputSchema: { type: 'object', properties: {} } },
   // 10. CONTENT CONTROLS
-  { name: 'word_get_content_controls', description: 'Get all content controls with id, tag, title, type, and text.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_insert_content_control', description: 'Wrap a text match in a content control (RichText or PlainText preserve the anchor text; CheckBox REPLACES the anchor text with a checkbox widget).', inputSchema: { type: 'object', properties: { anchorText: { type: 'string' }, type: { type: 'string', enum: ['RichText', 'PlainText', 'CheckBox'] }, title: { type: 'string' }, tag: { type: 'string' }, color: { type: 'string' }, occurrence: { type: 'number', description: '0-indexed match to target (0=first, 1=second, etc)' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false (case-insensitive)' } } } },
-  { name: 'word_set_content_control_text', description: 'Set text in a content control by ID or tag.', inputSchema: { type: 'object', properties: { id: { type: 'number' }, tag: { type: 'string' }, text: { type: 'string' } }, required: ['text'] } },
+  { name: 'word_get_content_controls', description: '[Content Controls] Get all content controls with id, tag, title, type (RichText/PlainText/CheckBox), and text.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'word_insert_content_control', description: '[Content Controls] Wrap a text match in a content control. RichText/PlainText preserve anchor text; CheckBox REPLACES it with a checkbox widget.', inputSchema: { type: 'object', properties: { anchorText: { type: 'string', description: 'Text to search for and wrap' }, type: { type: 'string', enum: ['RichText', 'PlainText', 'CheckBox'], description: 'Control type. Default: RichText' }, title: { type: 'string' }, tag: { type: 'string', description: 'Tag for programmatic identification' }, color: { type: 'string', description: 'Border color' }, occurrence: { type: 'number', description: 'Which match to target: 0=first, 1=second, etc. Default: 0' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' } } } },
+  { name: 'word_set_content_control_text', description: '[Content Controls] Set text in a content control identified by ID or tag. Does NOT work on CheckBox controls.', inputSchema: { type: 'object', properties: { id: { type: 'number', description: 'Content control ID (from word_get_content_controls)' }, tag: { type: 'string', description: 'Content control tag (alternative to ID)' }, text: { type: 'string' } }, required: ['text'] } },
   // 11. BOOKMARKS
-  { name: 'word_get_bookmarks', description: 'Get all bookmark names.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_insert_bookmark', description: 'Insert a bookmark at anchor text. If a bookmark with the same name already exists, it is moved to the new location (returns warning).', inputSchema: { type: 'object', properties: { name: { type: 'string' }, anchorText: { type: 'string' }, occurrence: { type: 'number', description: '0-indexed match to target (0=first, 1=second, etc)' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false (case-insensitive)' } }, required: ['name', 'anchorText'] } },
-  { name: 'word_delete_bookmark', description: 'Delete a bookmark by name.', inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] } },
-  { name: 'word_go_to_bookmark', description: 'Navigate to a bookmark and select its text range.', inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] } },
-  { name: 'word_get_bookmark_text', description: 'Get the text content within a named bookmark.', inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] } },
+  { name: 'word_get_bookmarks', description: '[Bookmarks] Get all bookmark names in the document.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'word_insert_bookmark', description: '[Bookmarks] Create a named bookmark at a text match. If name already exists, the bookmark is moved (returns warning).', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Bookmark name (must be unique)' }, anchorText: { type: 'string', description: 'Text to search for as bookmark location' }, occurrence: { type: 'number', description: 'Which match to target: 0=first, 1=second, etc. Default: 0' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' } }, required: ['name', 'anchorText'] } },
+  { name: 'word_delete_bookmark', description: '[Bookmarks] Delete a bookmark by name (text remains, only the bookmark reference is removed).', inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] } },
+  { name: 'word_go_to_bookmark', description: '[Bookmarks] Navigate to a bookmark and select its text range. Returns the bookmark text.', inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] } },
+  { name: 'word_get_bookmark_text', description: '[Bookmarks] Get the text content within a named bookmark.', inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] } },
   // 12. HYPERLINKS
-  { name: 'word_insert_hyperlink', description: 'Insert a hyperlink on existing text.', inputSchema: { type: 'object', properties: { anchorText: { type: 'string' }, url: { type: 'string' }, occurrence: { type: 'number', description: '0-indexed match to target (0=first, 1=second, etc)' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false (case-insensitive)' } }, required: ['anchorText', 'url'] } },
-  { name: 'word_get_hyperlinks', description: 'List all hyperlinks with URL, display text, and whether they are internal (TOC) links.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_remove_hyperlink', description: 'Remove a hyperlink from text (keeps the text, removes the link).', inputSchema: { type: 'object', properties: { anchorText: { type: 'string' }, occurrence: { type: 'number', description: '0-indexed match to target (0=first, 1=second, etc)' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false (case-insensitive)' } }, required: ['anchorText'] } },
+  { name: 'word_insert_hyperlink', description: '[Hyperlinks] Add a hyperlink URL to existing text (searches for anchorText, applies the link).', inputSchema: { type: 'object', properties: { anchorText: { type: 'string', description: 'Text to search for and link' }, url: { type: 'string', description: 'URL (must start with http:// or https://)' }, occurrence: { type: 'number', description: 'Which match to target: 0=first, 1=second, etc. Default: 0' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' } }, required: ['anchorText', 'url'] } },
+  { name: 'word_get_hyperlinks', description: '[Hyperlinks] List all hyperlinks with URL, display text, and internal flag (TOC links).', inputSchema: { type: 'object', properties: {} } },
+  { name: 'word_remove_hyperlink', description: '[Hyperlinks] Remove a hyperlink from text (keeps the text, removes only the link).', inputSchema: { type: 'object', properties: { anchorText: { type: 'string', description: 'Text of the hyperlink to remove' }, occurrence: { type: 'number', description: 'Which match to target: 0=first, 1=second, etc. Default: 0' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' } }, required: ['anchorText'] } },
   // 13. HEADERS & FOOTERS
-  { name: 'word_get_header_footer', description: 'Get header or footer text.', inputSchema: { type: 'object', properties: { type: { type: 'string', enum: ['header', 'footer'] }, sectionIndex: { type: 'number' }, headerType: { type: 'string', enum: ['Primary', 'FirstPage', 'EvenPages'] } }, required: ['type'] } },
-  { name: 'word_set_header_footer', description: 'Set header or footer text.', inputSchema: { type: 'object', properties: { type: { type: 'string', enum: ['header', 'footer'] }, text: { type: 'string' }, sectionIndex: { type: 'number' }, headerType: { type: 'string', enum: ['Primary', 'FirstPage', 'EvenPages'] } }, required: ['type', 'text'] } },
+  { name: 'word_get_header_footer', description: '[Headers/Footers] Get header or footer text content.', inputSchema: { type: 'object', properties: { type: { type: 'string', enum: ['header', 'footer'] }, sectionIndex: { type: 'number', description: 'Section index (0-based). Default: 0' }, headerType: { type: 'string', enum: ['Primary', 'FirstPage', 'EvenPages'], description: 'Default: Primary' } }, required: ['type'] } },
+  { name: 'word_set_header_footer', description: '[Headers/Footers] Set header or footer text (replaces existing content).', inputSchema: { type: 'object', properties: { type: { type: 'string', enum: ['header', 'footer'] }, text: { type: 'string' }, sectionIndex: { type: 'number', description: 'Section index (0-based). Default: 0' }, headerType: { type: 'string', enum: ['Primary', 'FirstPage', 'EvenPages'], description: 'Default: Primary' } }, required: ['type', 'text'] } },
   // 14. IMAGES
-  { name: 'word_insert_image', description: 'Insert an image from base64 data.', inputSchema: { type: 'object', properties: { base64: { type: 'string', description: 'Base64-encoded image data' }, location: { type: 'string', enum: ['Start', 'End'] }, width: { type: 'number' }, height: { type: 'number' }, altText: { type: 'string' } }, required: ['base64'] } },
-  { name: 'word_get_images', description: 'List all inline images with dimensions, alt text, and hyperlinks.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_delete_image', description: 'Delete an inline image by its index (0-based).', inputSchema: { type: 'object', properties: { index: { type: 'number' } }, required: ['index'] } },
+  { name: 'word_insert_image', description: '[Images] Insert an inline image from base64-encoded data (PNG, JPEG, or GIF).', inputSchema: { type: 'object', properties: { base64: { type: 'string', description: 'Base64-encoded image data' }, location: { type: 'string', enum: ['Start', 'End'] }, width: { type: 'number', description: 'Width in points' }, height: { type: 'number', description: 'Height in points' }, altText: { type: 'string', description: 'Alt text for accessibility' } }, required: ['base64'] } },
+  { name: 'word_get_images', description: '[Images] List all inline images with index, dimensions, alt text, and hyperlinks.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'word_delete_image', description: '[Images] Delete an inline image by its 0-based index.', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Image index (0-based)' } }, required: ['index'] } },
   // 15. PAGE LAYOUT & SECTIONS
-  { name: 'word_get_page_layout', description: 'Get page layout (margins, orientation, paper size) for a section.', inputSchema: { type: 'object', properties: { sectionIndex: { type: 'number' } } } },
-  { name: 'word_set_page_layout', description: 'Set page margins (in points), orientation, or paper size for a section.', inputSchema: { type: 'object', properties: { orientation: { type: 'string', enum: ['Portrait', 'Landscape'] }, topMargin: { type: 'number' }, bottomMargin: { type: 'number' }, leftMargin: { type: 'number' }, rightMargin: { type: 'number' }, paperSize: { type: 'string', enum: ['Letter', 'A4', 'A3', 'Legal', 'Custom'] }, sectionIndex: { type: 'number' } } } },
-  { name: 'word_get_sections', description: 'List all sections with their page setup (margins, orientation, paper size).', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_insert_page_break', description: 'Insert a page break after a paragraph. Omit paragraphIndex for end of document.', inputSchema: { type: 'object', properties: { paragraphIndex: { type: 'number', description: 'Paragraph index to insert break after. Omit for end of document.' } } } },
-  { name: 'word_insert_section_break', description: 'Insert a section break after a paragraph.', inputSchema: { type: 'object', properties: { paragraphIndex: { type: 'number' }, breakType: { type: 'string', enum: ['SectionNext', 'SectionContinuous', 'SectionEven', 'SectionOdd'], description: 'Default: SectionNext' } } } },
+  { name: 'word_get_page_layout', description: '[Layout] Get page layout (margins, orientation, paper size) for a section.', inputSchema: { type: 'object', properties: { sectionIndex: { type: 'number', description: 'Section index (0-based). Default: 0' } } } },
+  { name: 'word_set_page_layout', description: '[Layout] Set page margins (in points, 72pt = 1 inch), orientation, or paper size for a section.', inputSchema: { type: 'object', properties: { orientation: { type: 'string', enum: ['Portrait', 'Landscape'] }, topMargin: { type: 'number', description: 'Points (72 = 1 inch)' }, bottomMargin: { type: 'number', description: 'Points (72 = 1 inch)' }, leftMargin: { type: 'number', description: 'Points (72 = 1 inch)' }, rightMargin: { type: 'number', description: 'Points (72 = 1 inch)' }, paperSize: { type: 'string', enum: ['Letter', 'A4', 'A3', 'Legal', 'Custom'] }, sectionIndex: { type: 'number', description: 'Section index (0-based). Default: 0' } } } },
+  { name: 'word_get_sections', description: '[Layout] List all sections with their page setup (margins, orientation, paper size).', inputSchema: { type: 'object', properties: {} } },
+  { name: 'word_insert_page_break', description: '[Layout] Insert a page break after a paragraph. Omit paragraphIndex to insert at end of document.', inputSchema: { type: 'object', properties: { paragraphIndex: { type: 'number', description: 'Paragraph index (0-based). Omit for end of document.' } } } },
+  { name: 'word_insert_section_break', description: '[Layout] Insert a section break after a paragraph. Cannot be used inside table cells.', inputSchema: { type: 'object', properties: { paragraphIndex: { type: 'number', description: 'Paragraph index (0-based). Omit for end of document.' }, breakType: { type: 'string', enum: ['SectionNext', 'SectionContinuous', 'SectionEven', 'SectionOdd'], description: 'Default: SectionNext' } } } },
   // 16. CUSTOM PROPERTIES
-  { name: 'word_get_custom_properties', description: 'Get all custom document properties (key-value pairs with types).', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_set_custom_property', description: 'Set a custom document property. Creates or updates the key-value pair.', inputSchema: { type: 'object', properties: { key: { type: 'string' }, value: { type: 'string' } }, required: ['key', 'value'] } },
-  { name: 'word_delete_custom_property', description: 'Delete a custom document property by key.', inputSchema: { type: 'object', properties: { key: { type: 'string' } }, required: ['key'] } },
+  { name: 'word_get_custom_properties', description: '[Properties] Get all custom document properties (key-value pairs with types).', inputSchema: { type: 'object', properties: {} } },
+  { name: 'word_set_custom_property', description: '[Properties] Set a custom document property. Creates or updates the key-value pair.', inputSchema: { type: 'object', properties: { key: { type: 'string' }, value: { type: 'string' } }, required: ['key', 'value'] } },
+  { name: 'word_delete_custom_property', description: '[Properties] Delete a custom document property by key.', inputSchema: { type: 'object', properties: { key: { type: 'string' } }, required: ['key'] } },
   // 17. ADVANCED INSERTION & FIELDS
-  { name: 'word_insert_html', description: 'Insert HTML content that Word converts to native formatting. Supports headings, bold, italic, links, tables.', inputSchema: { type: 'object', properties: { html: { type: 'string' }, location: { type: 'string', enum: ['Start', 'End'] } }, required: ['html'] } },
-  { name: 'word_insert_ooxml', description: 'Insert raw Office Open XML for precise formatting control when HTML is insufficient.', inputSchema: { type: 'object', properties: { ooxml: { type: 'string' }, location: { type: 'string', enum: ['Start', 'End'] } }, required: ['ooxml'] } },
-  { name: 'word_insert_table_of_contents', description: 'Insert a table of contents based on heading styles.', inputSchema: { type: 'object', properties: { location: { type: 'string', enum: ['Start', 'End'] }, switches: { type: 'string' } } } },
-  { name: 'word_get_fields', description: 'Get all fields in the document (hyperlinks, TOC entries, page numbers, etc).', inputSchema: { type: 'object', properties: {} } },
+  { name: 'word_insert_html', description: '[Advanced] Insert HTML content that Word converts to native formatting. Supports headings, bold, italic, links, tables, and lists.', inputSchema: { type: 'object', properties: { html: { type: 'string' }, location: { type: 'string', enum: ['Start', 'End'], description: 'Default: End' } }, required: ['html'] } },
+  { name: 'word_insert_ooxml', description: '[Advanced] Insert raw Office Open XML for precise formatting control when HTML is insufficient. Must follow pkg:package structure.', inputSchema: { type: 'object', properties: { ooxml: { type: 'string' }, location: { type: 'string', enum: ['Start', 'End'], description: 'Default: End' } }, required: ['ooxml'] } },
+  { name: 'word_insert_table_of_contents', description: '[Advanced] Insert a table of contents based on heading styles. Note: after insertion, heading text appears twice (in TOC and body) — search matches TOC entries first.', inputSchema: { type: 'object', properties: { location: { type: 'string', enum: ['Start', 'End'], description: 'Default: Start' }, switches: { type: 'string', description: 'TOC field switches. Default: \\o "1-3" \\h \\z \\u' } } } },
+  { name: 'word_get_fields', description: '[Advanced] Get all fields in the document (hyperlinks, TOC entries, page numbers, etc).', inputSchema: { type: 'object', properties: {} } },
   // 18. EQUATIONS
-  { name: 'word_insert_equation', description: 'Insert a LaTeX math equation as a native Word equation (editable in Word equation editor). Supports fractions, roots, integrals, matrices, Greek letters, and all standard LaTeX math. Use displayMode:true for centered block equations, false for inline.', inputSchema: { type: 'object', properties: { latex: { type: 'string', description: 'LaTeX math expression (e.g. "\\\\frac{a}{b}", "\\\\int_0^\\\\infty e^{-x} dx")' }, displayMode: { type: 'boolean', description: 'true = block/centered equation (default), false = inline equation' }, location: { type: 'string', enum: ['Start', 'End'], description: 'Where to insert. Default: End' } }, required: ['latex'] } },
+  { name: 'word_insert_equation', description: '[Equations] Insert a LaTeX math equation as a native editable Word equation. Supports fractions, roots, integrals, matrices, Greek letters, and all standard LaTeX math. Display mode (default) inserts a centered block equation. Inline mode inserts after a search match (provide anchorText) or at cursor position.', inputSchema: { type: 'object', properties: { latex: { type: 'string', description: 'LaTeX math expression (e.g. "\\\\frac{a}{b}", "\\\\int_0^\\\\infty e^{-x} dx")' }, displayMode: { type: 'boolean', description: 'true (default) = centered block equation, false = inline equation' }, location: { type: 'string', enum: ['Start', 'End'], description: 'Where to insert display-mode equations. Default: End' }, anchorText: { type: 'string', description: 'For inline mode: search for this text and insert equation after it (avoids manual cursor positioning)' }, occurrence: { type: 'number', description: 'Which anchorText match to target: 0=first, 1=second, etc. Default: 0' }, matchCase: { type: 'boolean', description: 'Case-sensitive anchor matching. Default: false' } }, required: ['latex'] } },
+  // 19. BATCH OPERATIONS
+  { name: 'word_batch', description: '[Batch] Execute multiple operations in a single call to reduce round-trips. Each operation is a tool call object with "tool" and "args" fields. Operations execute sequentially — if one fails, subsequent operations are skipped. Returns results array with success/error for each operation. Consecutive native operations are sent to Word in one message for maximum speed.', inputSchema: { type: 'object', properties: { operations: { type: 'array', items: { type: 'object', properties: { tool: { type: 'string', description: 'Tool name (e.g. "word_insert_paragraph")' }, args: { type: 'object', description: 'Arguments for the tool' } }, required: ['tool'] }, description: 'Array of {tool, args} objects to execute sequentially' } }, required: ['operations'] } },
 ];
 
 const toolActionMap = {
   word_get_text: 'getDocumentText', word_get_document_properties: 'getDocumentProperties',
   word_set_document_properties: 'setDocumentProperties', word_save: 'saveDocument',
-  word_clear: 'clearDocument',
-  word_create_document: 'createNewDocument',
+  word_clear: 'clearDocument', word_create_document: 'createNewDocument',
   word_get_word_count: 'getWordCount', word_get_styles: 'getStyles',
   word_get_coauthors: 'getCoauthors', word_set_change_tracking: 'setChangeTracking',
   word_get_paragraphs: 'getParagraphs', word_get_paragraph_by_index: 'getParagraphByIndex',
-  word_insert_paragraph: 'insertParagraph', word_delete_paragraph: 'deleteParagraph',
+  word_insert_paragraph: 'insertParagraph', word_insert_paragraph_at_index: 'insertParagraphAtIndex',
+  word_delete_paragraph: 'deleteParagraph', word_replace_paragraph_text: 'replaceParagraphText',
   word_set_paragraph_style: 'setParagraphStyle', word_set_paragraph_spacing: 'setParagraphSpacing',
   word_search: 'search', word_search_and_replace: 'searchAndReplace',
-  word_insert_text: 'insertText', word_get_selection_info: 'getSelectionInfo',
+  word_insert_text_at_match: 'insertText', word_get_selection_info: 'getSelectionInfo',
   word_insert_text_at_selection: 'insertTextAtSelection', word_insert_line_break: 'insertLineBreak',
   word_format_text: 'formatRange', word_clear_formatting: 'clearFormatting',
   word_get_font_info: 'getFontInfo',
-  word_insert_table: 'insertTable', word_get_tables: 'getTables',
+  word_insert_table: 'insertTable', word_list_tables: 'getTables',
   word_get_table_data: 'getTableData', word_set_table_cell: 'setTableCell',
   word_add_table_row: 'addTableRow', word_delete_table_row: 'deleteTableRow',
   word_merge_table_cells: 'mergeTableCells', word_split_table_cell: 'splitTableCell',
   word_set_table_style: 'setTableStyle', word_set_table_cell_shading: 'setTableCellShading',
   word_insert_list: 'insertList', word_get_list_info: 'getListInfo', word_set_list_level: 'setListLevel',
-  word_add_comment: 'addComment', word_get_comments: 'getComments',
+  word_add_comment: 'addComment', word_get_comments: 'getCommentsWithAnchor',
   word_get_comment_replies: 'getCommentReplies', word_reply_to_comment: 'replyToComment',
   word_resolve_comment: 'resolveComment', word_delete_comment: 'deleteComment',
-  word_get_comment_anchor: 'getCommentAnchor', word_get_comments_with_anchor: 'getCommentsWithAnchor',
   word_insert_footnote: 'insertFootnote', word_insert_footnote_at_index: 'insertFootnoteAtIndex',
   word_insert_endnote: 'insertEndnote', word_get_footnotes: 'getFootnotes',
   word_get_endnotes: 'getEndnotes', word_delete_footnote: 'deleteFootnote', word_delete_endnote: 'deleteEndnote',
@@ -158,6 +161,8 @@ const toolActionMap = {
   word_delete_custom_property: 'deleteCustomProperty',
   word_insert_html: 'insertHtml', word_insert_ooxml: 'insertOoxml',
   word_insert_table_of_contents: 'insertTableOfContents', word_get_fields: 'getFields',
+  // word_insert_equation, word_batch, word_get_document_outline, word_move_paragraph
+  // are handled directly in index.js (not via taskpane action map)
 };
 
 module.exports = { tools, toolActionMap };

package/lib/usage-guide.js

@@ -6,25 +6,52 @@ const USAGE_GUIDE = `# MCP Word Bridge — Usage Guide
 
 Controls a live Word document through an Office Add-in. All operations execute immediately in Word.
 
+## Quick Start — Read This First
+
+1. **Read before writing** — call \`word_get_document_outline\` or \`word_get_paragraphs\` to understand the document structure
+2. **Use the right tool for the job:**
+   - Appending content → \`word_insert_paragraph\` (Start/End)
+   - Inserting at a position → \`word_insert_paragraph_at_index\` (Before/After by index)
+   - Editing existing text → \`word_replace_paragraph_text\` (by index, safe for collaboration)
+   - Bulk find/replace → \`word_search_and_replace\` (all occurrences)
+   - Inserting adjacent to text → \`word_insert_text_at_match\` (searches then inserts)
+3. **Batch multiple operations** — use \`word_batch\` to send up to 50 operations in one call
+4. **Save explicitly** — call \`word_save\` after significant changes
+
 ## Reading Content
-- \`word_get_paragraphs\` — structured content (text, style, alignment, isTocEntry). Paginate with start/end.
+- \`word_get_document_outline\` — heading hierarchy tree (fast structural overview)
+- \`word_get_paragraphs\` — all paragraphs with text, style, alignment. Paginate with start/end.
 - \`word_get_text\` — quick plain-text dump (no structure)
 - \`word_search\` — locate text before operating on it
 
 ## Document Lifecycle
-- \`word_clear\` — clear all body content in one call (fast reset). Leaves one empty Normal paragraph. Does not clear headers/footers or custom properties.
-- \`word_create_document\` — create and open a new blank document in a separate Word window. The add-in stays connected to the original document. Optionally pass base64-encoded .docx as template.
+- \`word_clear\` — clear all body content (fast reset). Does not clear headers/footers.
+- \`word_create_document\` — create a new document in a separate Word window
 - \`word_save\` — persist changes to disk
 
 ## Editing Text
-- \`word_search_and_replace\` — bulk find/replace
-- \`word_insert_text\` — insert before/after a search match (use \`occurrence\` for Nth match)
+- \`word_replace_paragraph_text\` — replace text by paragraph index (PREFERRED for collaborative docs)
+- \`word_search_and_replace\` — bulk find/replace across document
+- \`word_insert_text_at_match\` — insert before/after a search match (use \`occurrence\` for Nth match)
 - \`word_insert_text_at_selection\` — insert at cursor or replace selection
 - Verify edits with \`word_search\` or \`word_get_paragraphs\`
 
+## Batch Operations
+\`word_batch\` executes multiple operations in a single MCP call:
+\`\`\`json
+{"operations": [
+  {"tool": "word_insert_paragraph", "args": {"text": "Hello", "style": "Heading 1"}},
+  {"tool": "word_insert_paragraph", "args": {"text": "World", "style": "Normal"}},
+  {"tool": "word_save", "args": {}}
+]}
+\`\`\`
+Operations run sequentially. If one fails, the rest are skipped. Maximum 50 per batch.
+
+**Performance:** Consecutive standard operations (paragraphs, search, formatting, tables, etc.) are bundled into a single WebSocket message to Word — executing in one round-trip instead of one per operation. Only server-composed tools (equations, outline, move_paragraph) break the batch into segments.
+
 ## Search Behavior (applies to ALL search-based tools)
-- Case-insensitive by default. Pass \`matchCase: true\` for exact match.
-- Affected tools: search, search_and_replace, format_text, insert_text, insert_footnote, add_comment, insert_hyperlink, insert_bookmark, insert_content_control, clear_formatting, get_font_info, insert_line_break, remove_hyperlink, insert_endnote.
+- Case-insensitive by default. Pass \`matchCase: true\` for exact case match.
+- Affected tools: search, search_and_replace, insert_text_at_match, format_text, insert_footnote, add_comment, insert_hyperlink, insert_bookmark, insert_content_control, clear_formatting, get_font_info, insert_line_break, remove_hyperlink, insert_endnote, insert_equation (inline with anchor).
 
 ## Alignment Values
 The bridge normalizes aliases: Left, Center/Centered, Right, Justify/Justified.
@@ -32,19 +59,18 @@ The bridge normalizes aliases: Left, Center/Centered, Right, Justify/Justified.
 ## Change Tracking
 - Call \`word_set_change_tracking({mode:"TrackAll"})\` BEFORE edits for tracked changes
 - Adjacent insertions by the same author may coalesce into a single tracked change
-- \`search_and_replace\` with tracking may only expose the "Added" half; use \`accept_all_tracked_changes\` if granular control isn't needed
+- \`search_and_replace\` with tracking may only expose the "Added" half
 
 ## Comments — CRITICAL PATTERNS
 
 ### Reading
-- \`word_get_comments_with_anchor\` — preferred: returns comments + their anchored document text
-- \`word_get_comment_replies\` — reply thread for a specific comment
+- \`word_get_comments\` — returns all comments with their anchored document text, author, dates, resolved status
 
 ### Comment + text editing interaction
 **Problem:** \`word_search_and_replace\` on text anchoring a comment collapses the anchor (shrinks to empty). The comment survives but loses its positional context.
 
 **Safe pattern:**
-1. \`word_get_comments_with_anchor\` — identify commented text
+1. \`word_get_comments\` — identify commented text via anchorText field
 2. If replacement overlaps a comment anchor:
    a. \`word_reply_to_comment\` explaining resolution (if appropriate)
    b. \`word_resolve_comment\`
@@ -53,19 +79,15 @@ The bridge normalizes aliases: Left, Center/Centered, Right, Justify/Justified.
 
 **Avoid:** replacing text first (anchor collapses), or deleting+recreating comments (loses author/date/thread).
 
-### Adding
-- \`word_add_comment\` — anchor to a text match
-- \`word_reply_to_comment\` — reply to existing thread
-- \`word_resolve_comment\` — hides in Word UI, preserves history
-
 ## Tables
-- 0-based indexing: tableIndex, row, col
-- \`word_get_tables\` for overview, \`word_get_table_data\` for a specific table's cells
+- All indices 0-based: tableIndex, row, col
+- \`word_list_tables\` for metadata overview (count, dimensions, style — no cell values)
+- \`word_get_table_data\` for a specific table's cell values
 - Table cell paragraphs can't be structurally deleted (only cleared)
 - Can't insert page/section breaks inside table cells
 
 ## Footnotes & Endnotes
-- \`word_insert_footnote\` — anchor to text match
+- \`word_insert_footnote\` — anchor to text match (searches for anchorText)
 - \`word_insert_footnote_at_index\` — anchor to paragraph by index (no search needed)
 
 ## Page Layout
@@ -79,28 +101,34 @@ The bridge normalizes aliases: Left, Center/Centered, Right, Justify/Justified.
 ## TOC Behavior
 After inserting a Table of Contents, heading text appears twice in the document (once in TOC, once in body). Search matches TOC entries first — use \`occurrence\` parameter to target the body instance.
 
-## Error Messages
-- "Word taskpane not connected" — user must open the MCP Word Bridge add-in in Word
-- "Anchor not found" — search text not found in document
-- "Occurrence N not found" — match index out of range
-- Timeout: 30s default, 60s for HTML/OOXML/styles/TOC insertion
-
 ## Equations
 - \`word_insert_equation\` takes a LaTeX string and inserts a native Word equation
-- \`displayMode: true\` (default) = centered block equation; \`false\` = inline
-- Inline mode inserts at the current cursor position. Use \`word_insert_paragraph\` or \`word_insert_text_at_selection\` first to position the cursor, then call \`word_insert_equation\` with \`displayMode: false\`.
-- After an inline equation, use \`word_insert_text_at_selection\` (not \`word_insert_paragraph\`) to continue text in the same paragraph.
+- \`displayMode: true\` (default) = centered block equation
+- \`displayMode: false\` = inline equation
+- For inline equations, provide \`anchorText\` to position the equation after a search match (avoids manual cursor management)
+- Without \`anchorText\`, inline equations insert at the current cursor position
 - Supports: fractions, roots, integrals, sums, matrices, Greek letters, AMS math
-- Invalid LaTeX returns a descriptive parse error (not a crash)
+- Invalid LaTeX returns a descriptive parse error
 - The equation is fully editable in Word's built-in equation editor
 - Examples: \`\\\\frac{a}{b}\`, \`\\\\int_0^\\\\infty e^{-x} dx\`, \`\\\\sum_{i=1}^n x_i\`
 
+## Error Messages
+- "Word taskpane not connected" — user must open the MCP Word Bridge add-in in Word
+- "Anchor not found" — search text not found in document
+- "Occurrence N not found" — match index out of range
+- Timeout: 30s default, 60s for HTML/OOXML/styles/TOC insertion
+
 ## Best Practices
-1. Read before writing — understand document structure first
-2. \`word_get_comments_with_anchor\` before bulk replacements to avoid anchor damage
-3. Enable change tracking for collaborative documents
-4. \`word_save\` explicitly after significant changes
-5. Resolve comments rather than deleting them (preserves audit trail)
+1. Start with \`word_get_document_outline\` to understand structure
+2. \`word_get_comments\` before bulk replacements to avoid anchor damage
+3. Use \`word_batch\` for multiple sequential operations (reduces latency)
+4. In collaborative editing, prefer index-based tools over search-based:
+   - \`word_replace_paragraph_text\` over \`word_search_and_replace\`
+   - \`word_insert_paragraph_at_index\` over \`word_insert_paragraph\`
+5. Enable change tracking for collaborative documents
+6. \`word_save\` explicitly after significant changes
+7. Resolve comments rather than deleting them (preserves audit trail)
+8. Use \`word_move_paragraph\` to reorder content (avoids index-shifting bugs with manual delete+insert)
 `;
 
 module.exports = USAGE_GUIDE;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-word-bridge",
-  "version": "3.4.2",
+  "version": "3.5.0",
   "description": "MCP server for live Word document editing via Office Add-in",
   "main": "index.js",
   "bin": {

package/taskpane-app.js

@@ -70,6 +70,30 @@ async function handleCommand(cmd) {
 // --- Command registry ---
 const commands = {};
 
+// == BATCH EXECUTION (runs multiple actions in one WebSocket message) ==
+commands.batchExecute = async (p) => {
+  if (!p.operations || !Array.isArray(p.operations) || p.operations.length === 0) {
+    throw new Error('operations must be a non-empty array');
+  }
+  log('  batch: ' + p.operations.length + ' ops', 'log-batch');
+  const results = [];
+  for (let i = 0; i < p.operations.length; i++) {
+    const op = p.operations[i];
+    try {
+      const handler = commands[op.action];
+      if (!handler) throw new Error('Unknown action: ' + op.action);
+      log('  [' + (i + 1) + '/' + p.operations.length + '] ' + op.action, 'log-batch');
+      const result = await handler(op.params || {});
+      results.push({ index: i, success: true, result: result });
+    } catch (e) {
+      log('  [' + (i + 1) + '/' + p.operations.length + '] ' + (op.action || '?') + ' ✗ ' + e.message, 'log-err');
+      results.push({ index: i, success: false, error: e.message });
+      break; // stop on first error
+    }
+  }
+  return { results: results };
+};
+
 // == BASIC ==
 commands.ping = async () => ({ status: 'ok', wordReady });
 
@@ -231,6 +255,15 @@ commands.deleteParagraph = (p) => Word.run(async (ctx) => {
   if (p.index >= paragraphs.items.length) throw new Error('Paragraph index out of range. Valid indices: 0-' + (paragraphs.items.length - 1) + ' (document has ' + paragraphs.items.length + ' paragraphs).');
   paragraphs.items[p.index].delete();
   await ctx.sync();
+  // Move cursor to the paragraph that now occupies this position (or previous if at end)
+  const parasAfter = ctx.document.body.paragraphs;
+  parasAfter.load('text');
+  await ctx.sync();
+  if (parasAfter.items.length > 0) {
+    const cursorIdx = Math.min(p.index, parasAfter.items.length - 1);
+    parasAfter.items[cursorIdx].getRange('Start').select();
+    await ctx.sync();
+  }
   return { success: true };
 });
 
@@ -270,6 +303,9 @@ commands.setParagraphStyle = (p) => Word.run(async (ctx) => {
     para.alignment = alignment;
     await ctx.sync();
   }
+  // Move cursor to the styled paragraph
+  para.getRange('End').select();
+  await ctx.sync();
   return { success: true };
 });
 
@@ -400,8 +436,7 @@ commands.getTables = () => Word.run(async (ctx) => {
   tables.load('rowCount,values,style,headerRowCount');
   await ctx.sync();
   const items = tables.items.map((t, i) => ({
-    index: i, rowCount: t.rowCount, style: t.style, headerRowCount: t.headerRowCount,
-    values: t.values
+    index: i, rowCount: t.rowCount, columnCount: (t.values && t.values[0]) ? t.values[0].length : 0, style: t.style, headerRowCount: t.headerRowCount
   }));
   return { count: items.length, tables: items };
 });
@@ -1180,6 +1215,35 @@ commands.setParagraphSpacing = (p) => Word.run(async (ctx) => {
   return { success: true };
 });
 
+// == SURGICAL PARAGRAPH EDITING ==
+commands.replaceParagraphText = (p) => Word.run(async (ctx) => {
+  if (p.index < 0) throw new Error('Index must be non-negative');
+  const paragraphs = ctx.document.body.paragraphs;
+  paragraphs.load('text');
+  await ctx.sync();
+  if (p.index >= paragraphs.items.length) throw new Error('Paragraph index out of range. Valid indices: 0-' + (paragraphs.items.length - 1) + ' (document has ' + paragraphs.items.length + ' paragraphs).');
+  const para = paragraphs.items[p.index];
+  const inserted = para.insertText(p.text, Word.InsertLocation.replace);
+  inserted.getRange('End').select();
+  await ctx.sync();
+  return { success: true };
+});
+
+commands.insertParagraphAtIndex = (p) => Word.run(async (ctx) => {
+  if (p.index < 0) throw new Error('Index must be non-negative');
+  const paragraphs = ctx.document.body.paragraphs;
+  paragraphs.load('text');
+  await ctx.sync();
+  if (p.index >= paragraphs.items.length) throw new Error('Paragraph index out of range. Valid indices: 0-' + (paragraphs.items.length - 1) + ' (document has ' + paragraphs.items.length + ' paragraphs).');
+  const ref = paragraphs.items[p.index];
+  const location = p.location === 'Before' ? Word.InsertLocation.before : Word.InsertLocation.after;
+  const newPara = ref.insertParagraph(p.text, location);
+  newPara.style = p.style || 'Normal';
+  newPara.getRange('End').select();
+  await ctx.sync();
+  return { success: true };
+});
+
 // == BOOKMARK NAVIGATION ==
 commands.goToBookmark = (p) => Word.run(async (ctx) => {
   let range;

package/taskpane.html

@@ -38,6 +38,7 @@
     .log-cmd { color: #6cb6ff; }
     .log-ok { color: #4ec94e; }
     .log-err { color: #f87171; }
+    .log-batch { color: #f0a050; }
   </style>
 </head>
 <body>