Google Docs: Replace a text range — MCP tool
Google Docs MCP tool: Replaces one exact index range with new text in a single atomic batchUpdate.
Technical name: replace_range
What task it solves
I want to rewrite a specific passage of a document.
Replaces one exact index range with new text in a single atomic batchUpdate.
When to use it
Use it when position matters — rewriting one sentence, one heading or one occurrence among many. For textual find-and-replace across the document use replace_all_text; for a full rewrite use import_markdown.
What to provide
document_id— required.start_index/end_index— required. The range [start, end) fromread_document_text, fetched AFTER the latest edit.text— required. The replacement; empty string just deletes the range.tab_id,segment_id— optional addressing.
What it returns
The batchUpdate reply with the new revisionId.
What changes in Google Docs
The old range content is deleted and the new text inserted at its start in one atomic call. The new text takes the style at start_index. All later indexes shift.
Example request
Replace the second paragraph of the summary with this shorter version.
Errors and limitations
The range must not cut across a table cell boundary. Stale indexes hit the wrong text — always re-read first. The deleted content is unrecoverable; the call is never retried automatically after an ambiguous failure.
Access also depends on token permissions, quotas, and upstream API limits.
Related MCP tools
- Find and replace text —
replace_all_text - Delete a text range —
delete_range - Read document as text —
read_document_text
Technical details
- Impact: destructive operation
- Group: Text editing
- Description source:
replace_rangeregistration insrc/tools/text.ts - Full technical reference
- All MCP capabilities