Find and edit a passage in a large DOCX document

When an agent knows the text it needs to change, searching for that text can avoid loading the entire document into its context. Vespper's search_document searches the current DOCX session and returns complete HTML blocks that can be used as edit anchors. Use read_document when the agent needs surrounding structure or a range of pages.

This is a document-editing workflow. A semantic search result or a summary can help identify a topic, but an edit still needs to target the actual current passage unambiguously.

Start with a phrase or a regular expression

The search tool accepts a Python regular expression in pattern. For example, the following arguments search case-insensitively for a deadline label:

{
  "pattern": "(?i)delivery date",
  "start_at": 1
}

These are tool arguments; the integration also supplies the document session through MCP metadata. The search reference explains pattern syntax and the returned fields.

Search matches both the document's HTML and its visible text. That lets a plain phrase match text split across formatting spans. A returned match_text contains a complete block, while matched identifies the portion that matched the pattern. Preserve the complete block when building an edit anchor.

Check scope and ambiguity before editing

A result's page helps locate the passage. Its unique flag tells you whether the block's text also occurs elsewhere. Two identical placeholders can be separate results even when their HTML anchors look the same.

If unique is false, the page number helps you choose the intended occurrence, but simply copying that duplicate block into old does not make the edit unique. Read its surroundings and extend the anchor with an adjacent, distinguishing block. Do not combine non-adjacent passages into one anchor. The anchor rules describe this operation.

If the user asked for one deadline and search returns several plausible deadlines, use section context to resolve the target or ask the user which one they mean. Applying every match changes the scope of the request.

Follow the returned pagination

One response can contain only part of a large result set. When has_more is true, advance start_at by returned_matches to retrieve the next set. Do not treat the first response as evidence that no further matches exist.

For page reading, advance from the response's actual end_page, not the end page originally requested. The read reference explains that a token limit may shorten the returned range. Its has_more flag tells you whether pages remain.

Need	Operation
Locate a known date, name, or phrase	Search, then inspect candidate blocks.
Understand a section's structure	Read its page range.
Change every occurrence requested by the user	Follow search pagination and account for every intended result.
Insert content after a particular section	Read the section and identify its final block.

Treat page numbers as locations, not permanent anchors

DOCX content flows across pages according to fonts, margins, document settings, and the rendering environment. A page range helps locate a passage; the edit must still use its current structural block. Adding words can move that block to another page.

Break information	Meaning
Explicit page break	The document requests a new page.
Paragraph page-break setting	A paragraph should begin on a new page.
Last rendered page-break marker	A saved trace of earlier pagination, not a fresh layout calculation.

The python-docx question about inserting at a new page illustrates the danger of treating saved break markers as page containers. If a user asks to insert at the start of page 3, identify the paragraph currently there. If they instead need a section to always start on a new page, that is a structural formatting requirement for the chosen editing implementation. After a layout-changing edit, read again and verify the result in the target viewer.

Use current anchors and retain the new document

Read, search, and edit results include the session revision. If the target passage changes after it was read, obtain its current HTML before constructing another edit. Coordinate concurrent requests in your application so an agent does not unknowingly work from an older state.

After editing, inspect the applied count and any failures, save the latest returned DOCX, and verify the requested passage. A partial edit batch has already changed the document; recover only the failed edits instead of resending the whole request.