docx_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 docx_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 docx_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 replace and delete, pass a “ref” from docx_search or docx_get_content blocks. 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. For multi-step redlines or whole-clause rewrites, prefer docx_mutations with where:{by:“block”, nodeType, nodeId} from docx_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 docx_mutations instead. Supports “dryRun” to preview changes and “changeMode: tracked” to record edits as tracked changes (not supported for markdown/html inserts). Do NOT build “target” objects manually when a ref is available; prefer “ref” for simpler, more reliable targeting.
Parameters
string, enum: 'delete' | 'insert' | 'redo' | 'replace' | 'undo'
required
The action to perform. One of: delete, insert, redo, replace, undo.
boolean
Bypass confirmation checks.
string, enum: 'direct' | 'tracked'
Edit mode: “direct” applies changes immediately, “tracked” records as suggestions.
boolean
Preview the result without applying changes.
Target address. For inline/set_style: prefer ‘ref’ from docx_search, or use {kind:‘selection’, start:{kind:‘text’, blockId, offset}, end:{kind:‘text’, blockId, offset}}. For paragraph actions (set_alignment, set_indentation, set_spacing, set_direction, set_flow_options): use {kind:‘block’, nodeType:‘paragraph’|‘heading’|‘listItem’, nodeId:‘<nodeId from blocks list>’}.
string
Text content to insert. Only for action ‘insert’. Omit for other actions.
string, enum: 'text' | 'markdown' | 'html'
Content format: ‘text’ (default), ‘markdown’, or ‘html’. Only for action ‘insert’. Omit for other actions.
string
Handle ref from docx_search result (pass handle.ref value directly). Preferred over building a target object.
Document fragment to insert (structured content). Only for actions ‘insert’, ‘replace’. Omit for other actions.
string, enum: 'before' | 'after' | 'insideStart' | 'insideEnd'
Where to place content relative to target: ‘before’, ‘after’, ‘insideStart’, or ‘insideEnd’. Only for action ‘insert’. Omit for other actions.
object
Controls nesting behavior. tables: ‘allow’ permits inserting tables inside other tables. Only for actions ‘insert’, ‘replace’. Omit for other actions.
string
Replacement text content. Only for action ‘replace’. Omit for other actions.
string, enum: 'selection' | 'exact'
Delete behavior: ‘selection’ (default) or ‘exact’. Only for action ‘delete’. Omit for other actions.
string
required
The HERO documentId of the docx to target.