verified-googledocs-mcp

replace_table_row

Replace one row in an existing Google Docs table with plain text, preserving existing cell formatting. Use for in-place row updates after locating the table and row.

Instructions

Replace every cell in one row of an existing table with plain text.

Use this tool — the workhorse for updating existing tables in place — to overwrite one row's cells after locating the table and row with list_tables and get_table. cells are PLAIN STRINGS, not markdown, and the list length must equal the row's column count. Each cell's pre-existing bold/italic/underline style is preserved on the replacement text. The tool refuses tables that contain merged cells and rows where a cell contains a nested table.

Set dry_run=true to preview without writing. dry_run is authoritative for index validity: the same assembled request list is index-simulated whether dry_run is true or false, and the suggestion guard below runs identically on both paths, so a passing dry_run means the real write will pass too — provided nothing about the document changes in between (a new suggestion, a concurrent edit) before the real write is issued.

Returns evidence: applied, table_index, row_index, row_before, row_after, cells_match, revision_before, revision_after, audit_logged. In dry-run mode row_after_preview and planned_requests replace row_after and cells_match.

Errors: TAB_NOT_FOUND – tab_id not in document TABLE_NOT_FOUND – table_index does not exist in the tab INVALID_INPUT – merged cells, a nested table in a target cell, a wrong cell count, or a bad row_index 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 VERIFICATION_FAILED – post-write re-read does not match the requested cells INDEX_SIMULATION_FAILED – compiled requests would land at an invalid index; caught before the API call AUTH_EXPIRED – no valid token

Input Schema

TableJSON Schema

Name	Required	Description	Default
`cells`	Yes
`doc_id`	Yes
`tab_id`	Yes
`dry_run`	No
`row_index`	Yes
`table_index`	Yes

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.8/5.0

Behavior5/5

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

No annotations are provided, so the description carries the full behavioral disclosure burden. It states that cells are plain strings not markdown, that style is preserved, that merged cells and nested tables cause refusal, that dry_run is authoritative for index validity, and that a passing dry_run predicts a real write only if nothing changes in between. The detailed error list further exposes mutation, verification, and authentication behavior.

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 structured and front-loaded: the core purpose comes first, followed by prerequisites, dry-run behavior, return evidence, and errors. Every section earns its place, and the use of clear headings and an error list makes the detail scannable rather than bloated.

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 zero annotations, zero schema descriptions, and a complex table-mutation operation, the description is essentially complete. It covers prerequisite discovery, input constraints, dry-run guarantees, return fields, and eight error scenarios, leaving no critical gap for an agent to invoke the tool correctly.

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

Parameters5/5

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

The input schema has zero property descriptions, but the description compensates thoroughly. It explains cells must be plain strings and their list length must match the column count, describes dry_run semantics, and clarifies row_index and table_index meaning through the locating instructions and error messages. This gives the agent enough meaning to construct a correct call despite the empty schema.

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 action and target: 'Replace every cell in one row of an existing table with plain text.' This clearly distinguishes it from siblings like insert_table, which creates a new table, and replace_text, which generally replaces text. The resource (existing table row), the operation (replace every cell), and the value format (plain text) are all explicit.

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?

The description gives strong usage context: it tells the agent to first locate the table and row using list_tables and get_table, and explains the dry_run preview workflow. It does not explicitly contrast the tool with alternative table-editing or markdown-replacement tools, so it falls short of a full when-to-use versus when-not-to-use guide.

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