feat(sdk): optimize tool definitions and prompts for efficient MCP workflows#2722
Conversation
- superdoc_edit: emphasize markdown insert for multi-section creation - superdoc_create: direct to markdown/mutations for multiple items - superdoc_mutations: document create steps and batch format pattern - superdoc_format: direct to mutations for multi-item formatting - superdoc_search: clarify ref lifecycle within vs across batches - system-prompt: add efficient document creation workflow
…ints - Update provider SUPERDOC_SYSTEM_PROMPT with markdown insert and mutations batch examples (what CC actually reads as system prompt) - Update Codex AGENTS.md with same efficient patterns - Update MCP header prompt with "when to use which tool" guide - Increase CC maxTurns from 20 to 35 (both CC failures were at 21) - Regenerate SDK artifacts and rebuild MCP server
tupizz
changed the title
…ional inline in step executors
…deduplicate alignment constant
…t type, deduplicate alignment constant" This reverts commit 4c04ebd.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 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".
|
|
||
| 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..."}) |
There was a problem hiding this comment.
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 👍 / 👎.
| 'Do NOT mix text mutations and formatting in the same call.', | ||
| 'Execute multiple operations atomically in one batch. Use this for any workflow needing 2+ changes. ' + | ||
| 'Supported step types: text (text.rewrite, text.insert, text.delete), format (format.apply), create (create.heading, create.paragraph, create.table), assert. ' + | ||
| 'Each step has an id, an op, a "where" clause for targeting ({by:"select", select:{...}, require:"first"|"exactlyOne"|"all"|"last"} or {by:"ref", ref:"..."}), and "args" with operation-specific parameters. ' + |
There was a problem hiding this comment.
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 👍 / 👎.
1 participant
Summary
Optimizes SuperDoc MCP tool definitions, system prompts, and benchmark infrastructure for efficient agent workflows. Adds three new features to the
format.applymutation step and fixes markdown insert validation to support positioned inserts withBlockNodeAddresstargets.Results
NDA From-Scratch Creation (Claude Code + SuperDoc MCP)
Full Benchmark (96 runs, 8 providers x 12 tasks)
What changed
1. Tool definitions (
operation-definitions.ts)Updated tool descriptions in
INTENT_GROUP_METAto 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+placementfor 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.tableas supported step types. Addedformat.applybatch guidance.superdoc_format: Directed agents to mutations
format.applyfor multi-item formatting.superdoc_search: Clarified ref lifecycle (expires between tool calls, resolves automatically within mutations batch).
2. New features:
format.applyextensionsThree new optional fields added to the
format.applymutation 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 OOXMLjustificationon the parent paragraph node(s). Previously, alignment required a separatesuperdoc_formatcall sinceparagraphs.setAlignmentis 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: 1on args schema — Prevents agents from sending emptyargs: {}.Files changed:
packages/document-api/src/types/mutation-plan.types.ts—StyleApplyStep.argstypepackages/document-api/src/contract/schemas.ts— JSON schema for format.apply steppackages/super-editor/src/editors/v1/document-api-adapters/plan-engine/executor.ts—applyAlignmentToRange()helper,expandToBlockBoundaries()helper, updatedexecuteStyleApplyandexecuteSpanStyleApplypackages/super-editor/src/editors/v1/document-api-adapters/plan-engine/register-executors.ts— Guard for optionalinlinepackages/super-editor/src/editors/v1/document-api-adapters/plan-engine/paragraphs-wrappers.ts— ExportedALIGNMENT_TO_JUSTIFICATION(shared constant)3. Markdown insert:
placement+BlockNodeAddresstargetFixed validation to allow markdown/html inserts with
placementandBlockNodeAddresstargets:{ "action": "insert", "type": "markdown", "target": {"kind": "block", "nodeType": "paragraph", "nodeId": "54A21B3C"}, "placement": "before", "value": "# Executive Summary\n\nThis agreement..." }Previously,
placementwas rejected for any input withvalue, andBlockNodeAddresstargets 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 acceptsplacement+BlockNodeAddressfor markdown/html. AddedRichContentInsertInputtype export.packages/document-api/src/index.test.ts— Tests for new validation behaviorpackages/super-editor/src/editors/v1/document-api-adapters/plan-engine/plan-wrappers.ts—insertStructuredInnerhandlesBlockNodeAddresstargets viaresolveStructuralInsertTarget+resolvePlacement4. System prompts
Updated all prompt surfaces with context-driven formatting guidance:
system-prompt-mcp-header.md: Efficient patterns section with markdown insert,scope: "block", andalignmentexamples. "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: 35for Claude Code (up from 20)console.logfrom claude-code-agent provider6. Other changes
examples/collaboration/ai-node-sdk/Makefile— Always rebuilds CLI binary onmake dev-local(prevents stale binary)apps/docs/ai/— Updated MCP how-to-use guide and agent best practices with efficient patternsHow the optimizations work
Before (old pattern: 45+ calls for NDA)
After (new pattern: 3 calls)
Why it works
All claims verified against engine source:
mdastToProseMirror.ts:170-184: Markdown#creates properHeading1styleIdregister-executors.ts:410-416:create.heading/paragraphwired in plan enginecompiler.ts:505-595: Selectors resolve at compile timeexecutor.ts:807-870:applyAlignmentToRange+expandToBlockBoundariesfor alignment and scopeplan-wrappers.ts:968-988:BlockNodeAddresstargets resolved viaresolveStructuralInsertTarget+resolvePlacementTest plan
generate:allcompletes