verified-googledocs-mcp

replace_range_markdown

Replace a Google Docs range with markdown after validating the revision stamp and structural elements, preventing stale writes and accidental loss of tables, images, or footnotes.

Instructions

Replace a document range with compiled markdown.

Use this tool when you need to replace a section of a document with new markdown content. Obtain start_index, end_index, and computed_at_revision from find_sections. The range stamp is validated against the current document revision — a stale stamp raises STALE_RANGE ("re-run find_sections").

The structural guardrail inventories tables, images, chips, and footnotes inside the target range before writing. If the replacement markdown does not account for them the write is refused unless allow_structural_loss=true. A blast-radius check compares structural element counts outside the edited range pre/post; any change there is a hard failure.

Set dry_run=true to validate and preview without writing.

The returned payload (applied, revisions, structural_match, input_blocks/ post_blocks) is itself the confirmation the write landed — it already re-read the document and diffed it against the input. A follow-up read_document to double-check is a redundant round-trip; only re-read if you need the content for a subsequent step.

Errors: STALE_RANGE – range stamp is outdated; re-run find_sections UNSUPPORTED_MARKDOWN – markdown contains an unsupported construct INVALID_INPUT – structural guardrail refused or blast-radius violation INVALID_RANGE – start_index/end_index don't fit the tab's current extent, or the Docs API rejected the write as index-invalid TAB_NOT_FOUND – tab_id not in document REVISION_CONFLICT – document changed mid-call; re-read and retry SUGGESTIONS_PRESENT – tab has pending suggested edits; accept/reject them in the Docs UI first, then retry

Input Schema

TableJSON Schema

Name	Required	Description	Default
`doc_id`	Yes
`tab_id`	Yes
`dry_run`	No
`markdown`	Yes
`end_index`	Yes
`start_index`	Yes
`computed_at_revision`	Yes
`allow_structural_loss`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Sep 5, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations to lean on, the description carries full behavioral disclosure: revision-stamp validation, STALE_RANGE, structural guardrails, blast-radius checks, dry-run semantics, and confirmation via the returned payload. It also enumerates error conditions and how to recover from them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every block earns its place: purpose, when-to-use, validation flow, safety guardrails, dry-run, post-write confirmation, and a structured error list. Information is front-loaded and the error section is easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a stateful write operation with 8 parameters and complex guardrails, the description covers the critical behavioral context, all relevant failure modes, and the workflow relationship with find_sections. The output schema already exists, so not detailing return fields is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must explain parameter meaning, and it does for start_index, end_index, computed_at_revision, dry_run, allow_structural_loss, and markdown. doc_id and tab_id are left to inference from their names and sibling context, which is a minor gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: replacing a document range with compiled markdown. It clearly states the use case and implies the distinction from tab-level or text-level sibling tools by emphasizing range-based replacement keyed to find_sections.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says to use this tool when replacing a section of a document with new markdown content and instructs the agent to obtain indexes from find_sections. It gives clear context but does not explicitly name alternative siblings or state when not to use them, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.