feat(sdk): optimize tool definitions and prompts for efficient MCP workflows

apps/docs/ai/agents/best-practices.mdx

@@ -67,6 +67,24 @@ Instruct the LLM to plan all edits before calling tools. A well-structured promp
 
 Batch multiple changes only when atomic execution is genuinely helpful — use `superdoc_mutations` for that.
 
+## Prefer markdown insert for multi-block creation
+
+When you need to create multiple headings and paragraphs in one operation, use `superdoc_edit` with `type: "markdown"` instead of calling `superdoc_create` once per block. A single markdown insert produces the entire structure in one call.
+
+```json
+{
+  "tool": "superdoc_edit",
+  "intent": "insert",
+  "target": { "type": "end" },
+  "content": {
+    "type": "markdown",
+    "value": "## Executive Summary\n\nThis agreement governs the terms of service.\n\n## Key Provisions\n\nThe following provisions apply to all parties."
+  }
+}
+```
+
+After inserting, apply formatting in a single `superdoc_mutations` batch using `format.apply` steps — one step per block or range. This reduces a workflow that might otherwise take 40+ calls down to 4: read, search, insert, format.
+
 ## Use focused tools; `superdoc_mutations` is an escape hatch
 
 For straightforward edits, use the focused intent tools (`superdoc_edit`, `superdoc_format`, `superdoc_create`, `superdoc_list`, `superdoc_comment`). They validate arguments, give clear errors, and are easier for models to call correctly.
@@ -90,6 +108,27 @@ try {
 }
 ```
 
+## Choose formatting values from the document
+
+Don't hardcode formatting values. Read them from the document's existing content and match what's already there.
+
+**Body text:** Read `fontFamily`, `fontSize`, and `color` from non-empty paragraphs with `alignment: "justify"` or `alignment: "left"`. Set `bold: false` for body paragraphs.
+
+Many DOCX documents report `underline: true` on all blocks due to style inheritance. This is a DOCX artifact — not intentional formatting. Do not carry it forward when inserting new paragraphs.
+
+**Headings:** Read from existing heading blocks in the document. Scale `fontSize` up relative to body text. Headings are typically bold and sometimes centered — confirm against what's already in the document rather than assuming.
+
+```typescript
+// Get content first, find a representative body paragraph
+const content = await superdoc.getContent();
+const bodyParagraph = content.blocks.find(
+  (b) => b.type === 'paragraph' && b.text?.trim().length > 0
+);
+const { fontFamily, fontSize, color } = bodyParagraph?.formatting ?? {};
+
+// Use those values when formatting inserted content
+```
+
 ## Add examples for repeatable workflows
 
 If the same kind of edit runs across many documents (e.g., always rewriting a specific clause, always adding a comment to a section), include a concrete tool call example in your system prompt. Models that see a working example of the exact tool invocation produce correct calls more reliably than models that only see the schema.

apps/docs/ai/mcp/how-to-use.mdx

@@ -19,16 +19,71 @@ superdoc_open → superdoc_get_content / superdoc_search → intent tools → su
 4. `superdoc_save` writes changes to disk
 5. `superdoc_close` releases the session
 
+## Efficient patterns
+
+### Create multiple sections at once
+
+Use `superdoc_edit` with `type: "markdown"` to insert structured content in a single call. It parses markdown into proper document nodes — headings, paragraphs, bold, italic, and lists.
+
+```
+superdoc_edit({
+  session_id,
+  action: "insert",
+  type: "markdown",
+  placement: "end",
+  content: "# Background\n\nThis section covers the project history.\n\n# Next steps\n\n1. Review the proposal\n2. Assign owners\n3. Set a deadline"
+})
+```
+
+Markdown syntax maps to document styles:
+
+| Markdown | Document node |
+|----------|--------------|
+| `# Heading` | Heading 1 |
+| `## Heading` | Heading 2 |
+| `**text**` | Bold |
+| `*text*` | Italic |
+| `- item` | Bullet list |
+| `1. item` | Numbered list |
+
+### Format multiple items at once
+
+Use `superdoc_mutations` with `format.apply` steps to apply formatting across the document in one atomic call.
+
+```
+superdoc_mutations({session_id, action: "apply", atomic: true, changeMode: "direct", steps: [
+  {id: "f1", op: "format.apply", where: {by: "node", select: {type: "node", nodeType: "heading", level: 1}}, args: {inline: {bold: true}}, require: "all"},
+  {id: "f2", op: "format.apply", where: {by: "node", select: {type: "node", nodeType: "heading", level: 2}}, args: {inline: {italic: true}}, require: "all"}
+]})
+```
+
+<Warning>
+Format targets must exist before the batch runs. Node selectors resolve at step execution time using the current document state. If a required target is missing, the step fails and — with `atomic: true` — the entire batch rolls back.
+</Warning>
+
+### When to use which tool
+
+| Task | Best tool |
+|------|-----------|
+| Insert one paragraph or heading | `superdoc_create` |
+| Insert multiple sections with structure | `superdoc_edit` with `type: "markdown"` |
+| Replace text across the whole document | `superdoc_search` + `superdoc_edit` |
+| Rewrite a whole paragraph | `superdoc_get_content` + `superdoc_edit` with block ref |
+| Apply formatting to known text | `superdoc_search` + `superdoc_format` |
+| Apply formatting to all nodes of a type | `superdoc_mutations` with `format.apply` |
+| Multiple text changes that must succeed together | `superdoc_mutations` with `atomic: true` |
+| Review or resolve tracked changes | `superdoc_track_changes` |
+
 ## Targeting
 
 Every editing tool needs a **target** telling the API *where* to apply the change. There are three ways to get one:
 
 - **From blocks data**: Each block has a `ref` (pass to `superdoc_edit` or `superdoc_format`) and a `nodeId` (for building `at` positions with `superdoc_create`).
 - **From `superdoc_search`**: Returns `handle.ref` covering the matched text. Use search when you need to find text patterns, not when you already know which block to target.
-- **From `superdoc_create`**: Returns `nodeId` for chaining creates and building block targets. Re-fetch blocks after create to get a fresh ref before formatting.
+- **From `superdoc_create`**: Returns `nodeId` and `ref` for the new node. For creating multiple sections or blocks at once, prefer `superdoc_edit` with `type: "markdown"` instead of multiple `superdoc_create` calls. Re-fetch blocks after create to get a fresh ref before formatting.
 
 <Warning>
-**Refs expire after any mutation.** Always re-search or re-read blocks before the next operation.
+**Refs expire after any mutation.** Always re-search or re-read blocks before the next operation. Within a `superdoc_mutations` batch, node selectors resolve automatically at step execution time, so re-fetching between steps is not required.
 </Warning>
 
 ## Common operations
@@ -75,7 +130,7 @@ superdoc_list({session_id, action: "create", mode: "fromParagraphs", preset: "di
 
 ### Batch edits atomically
 
-Use `superdoc_mutations` when you need multiple text changes that must succeed or fail together:
+Use `superdoc_mutations` when you need multiple changes that must succeed or fail together. Supported step types include `text.rewrite`, `text.delete`, `format.apply`, `create.heading`, `create.paragraph`, and `create.table`.
 
 ```
 superdoc_mutations({session_id, action: "apply", atomic: true, changeMode: "direct", steps: [

apps/docs/document-api/reference/_generated-manifest.json

@@ -1016,5 +1016,5 @@
     }
   ],
   "marker": "{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}",
-  "sourceHash": "4a3601ee0f28a73c712fbe06e8b4913a9ae882a71152f9f6e892ea51137fc5e8"
+  "sourceHash": "a77f6a56704f39dcdc2d65ef8192ea4fffc0c8fb797bf13f516a949557d6e0ec"
 }

apps/docs/document-api/reference/mutations/apply.mdx

@@ -946,6 +946,16 @@ The runtime capability snapshot also exposes this allowlist at `planEngine.suppo
               "args": {
                 "additionalProperties": false,
                 "properties": {
+                  "alignment": {
+                    "description": "Set paragraph alignment on the target block(s). Can be combined with inline formatting in the same step.",
+                    "enum": [
+                      "left",
+                      "center",
+                      "right",
+                      "justify"
+                    ],
+                    "type": "string"
+                  },
                   "inline": {
                     "additionalProperties": false,
                     "minProperties": 1,
@@ -1754,11 +1764,16 @@ The runtime capability snapshot also exposes this allowlist at `planEngine.suppo
                       }
                     },
                     "type": "object"
+                  },
+                  "scope": {
+                    "description": "When \"block\", inline formatting expands to cover the entire parent paragraph(s), not just the matched text. Use \"block\" after markdown inserts to format whole paragraphs with a short identifying pattern. Default: \"match\".",
+                    "enum": [
+                      "match",
+                      "block"
+                    ],
+                    "type": "string"
                   }
                 },
-                "required": [
-                  "inline"
-                ],
                 "type": "object"
               },
               "id": {

apps/docs/document-api/reference/mutations/preview.mdx

@@ -932,6 +932,16 @@ The runtime capability snapshot also exposes this allowlist at `planEngine.suppo
               "args": {
                 "additionalProperties": false,
                 "properties": {
+                  "alignment": {
+                    "description": "Set paragraph alignment on the target block(s). Can be combined with inline formatting in the same step.",
+                    "enum": [
+                      "left",
+                      "center",
+                      "right",
+                      "justify"
+                    ],
+                    "type": "string"
+                  },
                   "inline": {
                     "additionalProperties": false,
                     "minProperties": 1,
@@ -1740,11 +1750,16 @@ The runtime capability snapshot also exposes this allowlist at `planEngine.suppo
                       }
                     },
                     "type": "object"
+                  },
+                  "scope": {
+                    "description": "When \"block\", inline formatting expands to cover the entire parent paragraph(s), not just the matched text. Use \"block\" after markdown inserts to format whole paragraphs with a short identifying pattern. Default: \"match\".",
+                    "enum": [
+                      "match",
+                      "block"
+                    ],
+                    "type": "string"
                   }
                 },
-                "required": [
-                  "inline"
-                ],
                 "type": "object"
               },
               "id": {

evals/providers/claude-code-agent.mjs

@@ -50,13 +50,32 @@ const SUPERDOC_SYSTEM_PROMPT = `You have a SuperDoc MCP server connected with to
 
 IMPORTANT: You MUST use the SuperDoc MCP tools for ALL .docx operations. Do NOT use Bash with unzip, python-docx, mammoth, or manual XML parsing.
 
-Workflow:
-1. superdoc_open(path) → returns session_id
-2. Use superdoc_get_content, superdoc_search, superdoc_edit, superdoc_format, superdoc_create, superdoc_comment, superdoc_track_changes, superdoc_mutations with the session_id
-3. superdoc_save(session_id) to persist changes
-4. superdoc_close(session_id) when done
+## Efficient workflows
 
-These tools handle OOXML format correctly and preserve document structure. Raw XML manipulation will corrupt the document.`;
+### Creating multiple headings and paragraphs
+
+Use superdoc_edit with type "markdown" to create ALL structure in one call:
+
+superdoc_edit({action: "insert", type: "markdown", placement: "end", value: "# Heading 1\\n\\nParagraph text...\\n\\n# Heading 2\\n\\nMore text..."})
+
+This creates proper Heading styles from # markers, bold from **text**, italic from *text*, and lists. One call replaces many superdoc_create calls.
+
+### Applying formatting to multiple items at once
+
+Use superdoc_mutations with format.apply and require "all" to batch formatting:
+
+superdoc_mutations({action: "apply", steps: [{id: "f1", op: "format.apply", where: {by: "select", select: {type: "node", nodeType: "heading"}, require: "all"}, args: {inline: {color: "#FF0000"}}}]})
+
+This formats every heading at once instead of formatting one at a time.
+
+### Standard workflow
+
+1. superdoc_open(path) → session_id
+2. For reading: superdoc_get_content
+3. For creating structure: superdoc_edit with type "markdown" (preferred for multiple blocks) or superdoc_create (for a single block at a specific position)
+4. For formatting: superdoc_mutations with format.apply steps (preferred for multiple items) or superdoc_format (for a single item)
+5. For text edits: superdoc_edit (single) or superdoc_mutations (batch)
+6. superdoc_save then superdoc_close`;
 
 const SUPERDOC_CLI_AGENTS_MD = `# AGENTS.md
 
@@ -150,6 +169,7 @@ export default class ClaudeCodeBenchmarkProvider {
 
     try {
       const env = { ...process.env };
+      env.ENABLE_TOOL_SEARCH = 'auto:5';
       if (!this.config.superdocOnPath) {
         env.PATH = env.PATH.split(':')
           .filter(p => !p.includes('superdoc'))
@@ -188,7 +208,7 @@ export default class ClaudeCodeBenchmarkProvider {
         model,
         allowedTools: this.config.allowedTools || ['Bash', 'Read', 'Write', 'Edit', 'Glob', 'Grep'],
         disallowedTools: this.config.disallowedTools,
-        maxTurns: this.config.maxTurns || 20,
+        maxTurns: this.config.maxTurns || 35,
         permissionMode: 'bypassPermissions',
         allowDangerouslySkipPermissions: true,
         settingSources: [], // SDK isolation mode: don't load user MCP servers (Linear, Excalidraw, etc.)
@@ -229,7 +249,7 @@ export default class ClaudeCodeBenchmarkProvider {
         prompt: fullPrompt,
         options: queryOptions,
       })) {
-        console.log('message', message);
+        console.log(message);
 
         if (message.type === 'assistant' && message.message?.content) {
           for (const block of message.message.content) {

evals/providers/codex-agent.mjs

@@ -43,9 +43,34 @@ const SUPERDOC_MCP_AGENTS_MD = `# AGENTS.md
 You have a SuperDoc MCP server available. Use it for ALL .docx file operations.
 
 **Do NOT** use unzip, python-docx, mammoth, sed, or manual XML editing on .docx files.
-**Do** use the superdoc_* MCP tools: superdoc_open → superdoc_get_content/search/edit → superdoc_save → superdoc_close.
 
-The SuperDoc tools handle OOXML format correctly and preserve document structure.
+## Efficient workflows
+
+### Creating multiple headings and paragraphs
+
+Use superdoc_edit with type "markdown" to create ALL structure in one call:
+
+\`\`\`
+superdoc_edit({action: "insert", type: "markdown", placement: "end", value: "# Heading\\n\\nParagraph...\\n\\n# Heading 2\\n\\nMore text..."})
+\`\`\`
+
+This creates proper Heading styles from # markers, bold from **text**, italic from *text*. One call replaces many superdoc_create calls.
+
+### Applying formatting to multiple items at once
+
+Use superdoc_mutations with format.apply and require "all":
+
+\`\`\`
+superdoc_mutations({action: "apply", steps: [{id: "f1", op: "format.apply", where: {by: "select", select: {type: "node", nodeType: "heading"}, require: "all"}, args: {inline: {color: "#FF0000"}}}]})
+\`\`\`
+
+### Standard workflow
+
+1. superdoc_open → session_id
+2. Create structure: superdoc_edit with type "markdown" (multiple blocks) or superdoc_create (single block)
+3. Format: superdoc_mutations format.apply (batch) or superdoc_format (single item)
+4. Text edits: superdoc_edit or superdoc_mutations
+5. superdoc_save → superdoc_close
 `;
 
 const SUPERDOC_CLI_AGENTS_MD = `# AGENTS.md
@@ -146,6 +171,7 @@ export default class CodexBenchmarkProvider {
         NODE_ENV: 'production',
         FORCE_COLOR: '0',
         NO_COLOR: '1',
+        ENABLE_TOOL_SEARCH: 'auto:5',
       };
 
       // Install vendor DOCX skill (Anthropic's docx skill) as AGENTS.md