docx_search
Find text patterns or nodes in the document and get ref handles for targeting edits and formatting. Refs expire after any mutation that changes the document. Re-search before the next edit when using individual tools (docx_edit, docx_format). Within a docx_mutations batch, selectors in “where” clauses resolve automatically at compile time; no manual re-searching needed between steps. Text search returns handle.ref covering only the matched substring. Node search finds blocks by type (paragraph, heading, table, listItem, etc.). The “require” parameter controls match cardinality: “first” returns one match, “all” returns every match, “exactlyOne” fails if not exactly one match. Supports scoping via “within” to search inside a single block. Do NOT use regex or markdown formatting markers (#, **, etc.) in search patterns; patterns are plain text only. Do NOT use this tool when you already have a ref from docx_get_content blocks or docx_create; use that ref directly.
Parameters
required
Search selector. Use {type:‘text’, pattern:’…’} for text search or {type:‘node’, nodeType:‘paragraph’|‘heading’|…} for node search.
object
Limit search scope to within a specific block: {kind:‘block’, nodeType:’…’, nodeId:’…’}.
string, enum: 'any' | 'first' | 'exactlyOne' | 'all'
Match cardinality: ‘any’ (all matches), ‘first’ (only first), ‘exactlyOne’ (fail if != 1), ‘all’ (fail if 0).
string, enum: 'strict' | 'candidates'
Search mode: ‘strict’ (default, exact matching) or ‘candidates’ (returns scored potential matches).
boolean
When true, includes full node data in results. Default: false.
number
Maximum number of matches to return.
number
Number of matches to skip for pagination.
string
required
The HERO documentId of the docx to target.