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

[tupizz]

Summary

Optimizes SuperDoc MCP tool definitions, system prompts, and benchmark infrastructure for efficient agent workflows. Adds three new features to the format.apply mutation step and fixes markdown insert validation to support positioned inserts with BlockNodeAddress targets.

Results

NDA From-Scratch Creation (Claude Code + SuperDoc MCP)

Metric	Before	After	Improvement
Steps	58	13	-77%
Cost	$0.97	$0.24	-75%
Duration	217s	90s	-58%
MCP calls	56	9	-84%
Correctness	14/14	14/14	Same

Full Benchmark (96 runs, 8 providers x 12 tasks)

Condition	Pass Rate (before)	Pass Rate (after)
Codex-superdoc-mcp	67%	100%
CC-superdoc-mcp	42%	83%
Baseline/vendor	92%	92% (unchanged)

What changed

1. Tool definitions (operation-definitions.ts)

Updated tool descriptions in INTENT_GROUP_META to guide agents toward efficient patterns:

• superdoc_edit: Now described as "the primary tool for inserting content." Agents are told to ALWAYS use markdown insert for headings/paragraphs, with context-driven formatting guidance. Description explains target + placement for positioned inserts.

• superdoc_create: Redirects agents to markdown insert. Starts with "IMPORTANT: For headings and paragraphs, use superdoc_edit with type markdown instead."

• superdoc_mutations: Documented create.heading, create.paragraph, create.table as supported step types. Added format.apply batch guidance.

• superdoc_format: Directed agents to mutations format.apply for multi-item formatting.

• superdoc_search: Clarified ref lifecycle (expires between tool calls, resolves automatically within mutations batch).

2. New features: format.apply extensions

Three new optional fields added to the format.apply mutation step:

alignment — Set paragraph alignment in the same step as inline formatting:

{
  "op": "format.apply",
  "args": {
    "inline": {"fontFamily": "Times New Roman", "fontSize": 12, "underline": true},
    "alignment": "center"
  }
}

Values: left, center, right, justify. Maps to OOXML justification on the parent paragraph node(s). Previously, alignment required a separate superdoc_format call since paragraphs.setAlignment is not a valid mutations step op.

scope: "block" — Expand formatting to cover entire paragraph(s), not just matched text:

{
  "op": "format.apply",
  "where": {"by": "select", "select": {"type": "text", "pattern": "short prefix"}, "require": "first"},
  "args": {"inline": {"fontSize": 12}, "scope": "block"}
}

Solves the problem where text pattern selectors only match a substring, leaving the rest of the paragraph with default markdown formatting. With scope: "block", a short identifying prefix is enough to format the whole block.

minProperties: 1 on args schema — Prevents agents from sending empty args: {}.

Files changed:

• packages/document-api/src/types/mutation-plan.types.ts — StyleApplyStep.args type
• packages/document-api/src/contract/schemas.ts — JSON schema for format.apply step
• packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/executor.ts — applyAlignmentToRange() helper, expandToBlockBoundaries() helper, updated executeStyleApply and executeSpanStyleApply
• packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/register-executors.ts — Guard for optional inline
• packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/paragraphs-wrappers.ts — Exported ALIGNMENT_TO_JUSTIFICATION (shared constant)

3. Markdown insert: placement + BlockNodeAddress target

Fixed validation to allow markdown/html inserts with placement and BlockNodeAddress targets:

{
  "action": "insert",
  "type": "markdown",
  "target": {"kind": "block", "nodeType": "paragraph", "nodeId": "54A21B3C"},
  "placement": "before",
  "value": "# Executive Summary\n\nThis agreement..."
}

Previously, placement was rejected for any input with value, and BlockNodeAddress targets were only accepted for structural (content) inserts. Now markdown/html inserts route through the structural insert path which supports both.

Files changed:

• packages/document-api/src/insert/insert.ts — Validation accepts placement + BlockNodeAddress for markdown/html. Added RichContentInsertInput type export.
• packages/document-api/src/index.test.ts — Tests for new validation behavior
• packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/plan-wrappers.ts — insertStructuredInner handles BlockNodeAddress targets via resolveStructuralInsertTarget + resolvePlacement

4. System prompts

Updated all prompt surfaces with context-driven formatting guidance:

• system-prompt-mcp-header.md: Efficient patterns section with markdown insert, scope: "block", and alignment examples. "When to use which tool" guide.
• system-prompt-core.md: 3-step insert workflow (understand context → insert markdown → format in one batch). Context-driven reasoning: "What kind of document is this? How are titles styled?"
• claude-code-agent.mjs / codex-agent.mjs: Same patterns for benchmark providers.

5. Benchmark and eval infrastructure

• ENABLE_TOOL_SEARCH: 'auto:5' — Tool schemas loaded on-demand (saves ~57KB per turn)
• maxTurns: 35 for Claude Code (up from 20)
• New NDA fixture documents and interactive DOCX output reviewer script
• Removed debug console.log from claude-code-agent provider

6. Other changes

• examples/collaboration/ai-node-sdk/Makefile — Always rebuilds CLI binary on make dev-local (prevents stale binary)
• apps/docs/ai/ — Updated MCP how-to-use guide and agent best practices with efficient patterns

How the optimizations work

Before (old pattern: 45+ calls for NDA)

For each heading:
  1. superdoc_create(heading)           ← create one block
  2. superdoc_get_content(blocks)       ← re-fetch to get ref
  3. superdoc_search("heading text")    ← search to get text ref
  4. superdoc_format(inline, color)     ← format color
  5. superdoc_format(set_alignment)     ← format alignment
= 5 calls per heading × 8 headings = 40+ calls

After (new pattern: 3 calls)

1. superdoc_get_content(blocks)                      ← read + understand context
2. superdoc_edit(insert, type: "markdown", target, placement)  ← ALL structure in one call
3. superdoc_mutations(format.apply steps with alignment + scope: "block")  ← ALL formatting in one batch

Why it works

All claims verified against engine source:

• mdastToProseMirror.ts:170-184: Markdown # creates proper Heading1 styleId
• register-executors.ts:410-416: create.heading/paragraph wired in plan engine
• compiler.ts:505-595: Selectors resolve at compile time
• executor.ts:807-870: applyAlignmentToRange + expandToBlockBoundaries for alignment and scope
• plan-wrappers.ts:968-988: BlockNodeAddress targets resolved via resolveStructuralInsertTarget + resolvePlacement

Test plan

• 1354 document-api tests pass
• 11,123 super-editor tests pass
• super-editor builds clean
• generate:all completes
• SDK and MCP server rebuilt
• New tests for placement validation (markdown + BlockNodeAddress)
• NDA creation: 13 steps, $0.24, 14/14 checks (down from 58 steps, $0.97)
• Full benchmark: Codex-superdoc-mcp 100%, CC-superdoc-mcp 83%
• Executive summary insert verified with 3-call pattern (read + insert + format)

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c5a322fce2

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Use a valid placement literal in benchmark agent guidance

The prompt example hard-codes placement: "end", but insert validation only accepts before, after, insideStart, or insideEnd; "end" is rejected as INVALID_INPUT. When the benchmark agent follows this example (and the same one in evals/providers/codex-agent.mjs), its first markdown insert fails and burns turns/cost for recoverable errors.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Remove unsupported require:"last" from mutations tool description

This description advertises require:"last" as a valid where cardinality, but the actual mutation schema/types only allow first | exactlyOne | all. Agents relying on the tool description can emit plans that fail schema validation before execution, which is especially costly in MCP loops where retries consume extra calls.

Useful? React with 👍 / 👎.