superdoc_edit

The primary tool for inserting content into documents. ALWAYS use action "insert" with type "markdown" to create headings, paragraphs, or any block content: this is faster and creates proper document structure in one call. Do NOT use superdoc_create for headings or paragraphs. The markdown parser creates headings from # markers (# = Heading1, ## = Heading2), bold from text, italic from *text*, and numbered/bullet lists. Position markdown inserts with "target" (a BlockNodeAddress like {kind:"block", nodeType, nodeId}) and "placement" (before, after, insideStart, insideEnd). Without a target, content appends at the end of the document. IMPORTANT: After a markdown insert, analyze the document context (what kind of document, how titles and body text are styled) and follow up with ONE superdoc_mutations call to format inserted blocks so they look like they belong. Each format.apply step accepts "inline" (fontFamily, fontSize, bold, underline, color), "alignment", and "scope" in the same step. Use scope: "block" so formatting covers the entire paragraph. Copy the exact property values from the existing get_content blocks (fontFamily, fontSize, color, alignment, bold, underline). Do NOT invent values: use what the blocks show. Also supports replace, delete, and undo/redo. For ordinary replace and delete, pass a "ref" from superdoc_search or superdoc_get_content blocks. Action "delete" removes a text range and leaves the block container in place. To remove a whole paragraph, heading, list item, or table, use action "delete_block" with target:{kind:"block", nodeType, nodeId} from superdoc_get_content action "blocks", or action "delete_block_range" with "start" and "end" block addresses to remove a contiguous span of top-level blocks (inclusive). A search ref covers only the matched substring; a block ref covers the entire block text, so use block refs when rewriting or shortening whole paragraphs. To replace every block in the main body, use action "replace" with target:{kind:"story",storyType:"body"}, one text/value/content payload, and changeMode:"direct". This replaces body content, not the DOCX package, and does not require a search first. Tracked whole-body replacement is unsupported. For multi-step redlines or whole-clause rewrites, prefer superdoc_mutations with where:{by:"block", nodeType, nodeId} from superdoc_get_content action "blocks" includeText:true rather than relying on text selectors. Refs expire after any mutation; always re-search before the next edit. For 2+ edits that must succeed or fail atomically, use superdoc_mutations instead. Before an exact HTML or Markdown insert/replace that must be fidelity-checked, use action "check_support", review its outcome and diagnostics, then pass its guard back as "supportCheck" on the unchanged write. Supports "dryRun" to preview changes and "changeMode: tracked" to record edits as tracked changes. Do NOT build "target" objects manually when a ref is available; prefer "ref" for simpler, more reliable targeting. EXAMPLES: 1. {"action":"insert","type":"markdown","target":{"kind":"block","nodeType":"paragraph","nodeId":"<nodeId>"},"placement":"before","value":"# Executive Summary\n\nThis agreement sets forth the principal terms...","changeMode":"direct"} 2. {"action":"insert","type":"html","value":"<h2>Review heading</h2><p>Tracked rich content.</p>","changeMode":"tracked"} 3. {"action":"insert","type":"markdown","value":"# Section Title\n\nParagraph content here.\n\n# Another Section\n\nMore content with bold and *italic*."} 4. {"action":"replace","ref":"<handle.ref>","text":"new text here"} 5. {"action":"replace","ref":"<handle.ref>","value":"Direct rich replacement","type":"markdown","changeMode":"direct"} 6. {"action":"replace","ref":"<handle.ref>","value":"<strong>Tracked rich replacement</strong>","type":"html","changeMode":"tracked"} 7. {"action":"check_support","operation":"insert","input":{"type":"markdown","value":"# Checked section"},"options":{"changeMode":"direct"}} 8. {"action":"replace","target":{"kind":"story","storyType":"body"},"value":"# Replacement\n\nComplete new body.","type":"markdown","changeMode":"direct"} 9. {"action":"delete","ref":"<handle.ref>"} 10. {"action":"delete_block","target":{"kind":"block","nodeType":"heading","nodeId":"<nodeId>"}} 11. {"action":"undo"}. It is categorised as a Write tool in the Superdoc MCP Server, which means it can create or modify data. Consider rate limits to prevent runaway writes.

superdoc_edit accepts 12 parameters: in, end, ref, text, type, force, input, start, value, action, dryRun, target. Required: action. The full parameter table on this page comes from the server's own tool schema.

Register the Superdoc MCP server in PolicyLayer and add a rule for superdoc_edit: allow, deny, rate-limit, or require approval. Point your MCP client at the PolicyLayer proxy URL and the rule is enforced on every call, before it reaches Superdoc. Nothing to install.

superdoc_edit is a Write tool with medium risk. Write tools should be rate-limited to prevent accidental bulk modifications.

Yes. Add a rate_limit block to the superdoc_edit rule in your PolicyLayer policy. For example, setting max: 10 and window: 60 limits the tool to 10 calls per minute. Rate limits are tracked per agent session and reset automatically.

Set action: deny in the PolicyLayer policy for superdoc_edit. The AI agent will receive a policy violation error and cannot call the tool. You can also include a reason field to explain why the tool is blocked.

superdoc_edit is provided by the Superdoc MCP server (@superdoc/mcp). PolicyLayer sits as a proxy in front of this server to enforce policies before tool calls reach the server.