gdocs-mcp

Read a Google Doc

read_doc

Read a Google Doc as markdown with inline HTML, preserving styles, tracked suggestions, tabs, headers, and footers so agents can edit safely.

Instructions

Read a Google Doc as markdown + inline HTML. The read opens with a block — one CSS rule per named style (p = Normal text, h1–h6, .title, .subtitle), in pt — and a paragraph or run shows style="…" only where it differs from its rule (text-align, line-height, margin-top/bottom/left/right, text-indent; a hanging indent is margin-left:36pt with a negative text-indent). Title and Subtitle paragraphs read as . A page break reads as on its own line, where the break is. Every element in a paragraph reads, so an edit that quotes one can give it back: a footnote is [^1] with its note as a [^1]: line at the end; a date is Nov 15, 2026; a person or a link chip is Jane Doe (the text is Google’s); a dropdown is with its list as a Draft line after the block; a horizontal rule is --- on a line of its own; a column break is ; an equation and a page-number field are empty and whose title says to edit them in Google Docs. A table of contents is not read. List items show no indent: their nesting owns it. mode: clean (committed text, default) · tracked (suggestions shown as /) · accepted · rejected. segment picks the content tree: body (default), header, footer, or all (body plus every header/footer, each labelled). Text that would otherwise read as markup is marked as literal: a paragraph wrapped in … ("4. Term" is a paragraph, not a list) or a backslash before a character (5 * 3), and \ is a real backslash — write them back as read, and the document keeps only the words. A body read always reports which headers/footers exist and what they hold, since their content — a letterhead logo, a page number — is NOT part of the body and would otherwise be invisible.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "path": "<path>"
    },
    "name": "read_doc"
  }
}

Input Schema

Name	Required	Description
`mode`	No	read mode (default clean)
`page`	No	which header/footer, when a doc defines more than one (default-page, first-page, even-page). Omit to use whichever exists.
`path`	Yes	The doc or tab: a Drive id or URL, /folder/doc, or /folder/doc/tab (nested: /folder/doc/tab/child). A doc with one tab needs no tab step; a doc with several is refused until one is named, and the refusal lists every tab path.
`account`	No	Google account email to use. Defaults to GDOCS_DEFAULT_ACCOUNT, or the sole account.
`segment`	No	content tree to read (default body)

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv1.0.0Oct 31, 2026

removedInput schema / properties / documentId

Removed value: -{
-  "description": "Google Doc id",
-  "type": "string"
-}

addedInput schema / properties / path

Added value: +{
+  "description": "The doc or tab: a Drive id or URL, /folder/doc, or /folder/doc/tab (nested: /folder/doc/tab/child). A doc with one tab needs no tab step; a doc with several is refused until one is named, and the refusal lists every tab path.",
+  "type": "string"
+}

removedInput schema / properties / tab

Removed value: -{
-  "description": "Target a specific tab by tabId or title (from list_tabs). Defaults to the first tab.",
-  "type": "string"
-}

changedInput schema / required

Previous value: -[
-  "documentId"
-]New value: +[
+  "path"
+]

Changed2 schema fields changedv0.5.0Aug 17, 2026

addedInput schema / properties / page

Added value: +{
+  "description": "which header/footer, when a doc defines more than one (default-page, first-page, even-page). Omit to use whichever exists.",
+  "enum": [
+    "default",
+    "first",
+    "even"
+  ],
+  "type": "string"
+}

addedInput schema / properties / segment

Added value: +{
+  "description": "content tree to read (default body)",
+  "enum": [
+    "body",
+    "header",
+    "footer",
+    "all"
+  ],
+  "type": "string"
+}

First observedv0.1.1Aug 1, 2026

TDQS

A4.3/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 the full burden and does so unusually well: it discloses output structure (style block, class-based paragraphs), how every inline element serializes (footnotes, time, chips, dropdowns, rules, column breaks, equations), and explicit limitations ('A table of contents is not read', 'List items show no indent'). It also warns that a body read reports headers/footers because their content is 'NOT part of the body and would otherwise be invisible', which is exactly the non-obvious behavior an agent needs.

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

Conciseness3/5

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

It is front-loaded and purposeful, and given there is no output schema most of the format detail earns its place. However it is delivered as one very long run-on paragraph of semicolon-chained clauses with no breaks or structure, making it hard to scan for the parts an agent needs at call time.

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?

No output schema exists, so the description must define the return format, and it does so exhaustively — styling rules, literal-escaping semantics, every inline element type, and what is deliberately omitted. For a 5-parameter read tool at this complexity, an agent has everything needed to call it and interpret the result correctly.

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 100%, so the baseline is 3, but the description adds real meaning to the enums that the schema only labels: mode is explained as clean (committed text, default) vs tracked (suggestions as <ins>/<del>) vs accepted/rejected, and segment as body/header/footer/all with 'all' defined as body plus every labelled header/footer. page and account are left entirely to the schema, so it stops short of a 5.

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?

Opens with a specific verb and resource plus the output contract: 'Read a Google Doc as markdown + inline HTML.' An agent can immediately distinguish this from write_doc, edit_doc, or export_doc without inspecting the schema.

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

Usage Guidelines3/5

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

Usage is only implied: the note that 'an edit that quotes one can give it back' hints at round-tripping with edit_doc, and mode/segment values imply selection contexts, but there is no explicit when-to-use / when-not-to-use guidance or named alternative (e.g., export_doc, get_page_setup). The agent must infer routing from sibling names alone.

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