verified-googledocs-mcp

replace_tab_markdown

Replace a specific tab's entire content with compiled markdown while protecting existing tables, images, chips, and footnotes; use dry-run to validate before writing.

Instructions

Replace the entire content of a document tab with compiled markdown.

Use this tool when you need to completely replace a tab's content with new markdown. tab_id is required and must identify an existing tab.

The structural guardrail refuses writes that would silently lose tables, images, chips, or footnotes unless allow_structural_loss=true.

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: UNSUPPORTED_MARKDOWN – markdown contains an unsupported construct INVALID_INPUT – structural guardrail refused TAB_NOT_FOUND – tab_id missing or 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
`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.9/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses the structural guardrail behavior, the dry-run mode, that the returned payload already confirms the write by re-reading and diffing, and detailed error conditions including REVISION_CONFLICT and SUGGESTIONS_PRESENT.

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 longer than average but every sentence adds practical value: scope, guardrail, dry-run, confirmation semantics, and error conditions. It is front-loaded with the main purpose and then structured into clear, scannable sections for return behavior and errors.

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?

Given the tool's complexity — structural loss guardrail, dry-run flow, conflict handling, and detailed error taxonomy — the description covers everything an agent needs to call it correctly. It also references the output payload, making the post-call behavior clear even though an output schema exists.

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?

The schema has 0% description coverage, so the description must compensate. It explains tab_id as required and identifying an existing tab, dry_run as validate-and-preview without writing, and allow_structural_loss as the way to bypass the structural guardrail. doc_id and markdown format are not deeply elaborated, but doc_id is contextually obvious and the markdown parameter is defined by the tool's core purpose.

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 immediately states the action and scope: "Replace the entire content of a document tab with compiled markdown." This clearly distinguishes it from partial-edit siblings like replace_text, replace_range_markdown, and append_markdown because it emphasizes replacing the entire content.

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

Usage Guidelines5/5

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

It gives an explicit use condition: "Use this tool when you need to completely replace a tab's content with new markdown." It also directs the agent when NOT to follow up with read_document, saying a re-read is redundant unless the content is needed for a subsequent step, and lists an error case where the user must intervene in the Docs UI first.

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