gdocs-mcp

Add a comment or reply

add_comment

Add a comment to quoted text in a Google Doc or reply to an existing comment so feedback stays attached as the text moves.

Instructions

Comment on text in a Google Doc: quotedText is the text the comment sits on, found the way edit_doc finds old_string (markup-tolerant; text that matches more than once is refused with the context of each match, so quote more of it). The comment stays on that text as it moves. Docs has no comment on the whole doc, so quotedText is required; put overall feedback on the title, or on its first words. The tab comes from path, and segment: "header" or "footer" comments in the page header or footer. To reply to an existing comment instead, pass replyTo (a comment id from list_comments) and no quotedText; the reply goes to the doc named by path, whatever its tab.

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>",
      "content": "<content>"
    },
    "name": "add_comment"
  }
}

Input Schema

Name	Required	Description
`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.
`content`	Yes	the comment, or the reply
`replyTo`	No	a comment id (from list_comments) to reply to; omit to start a new comment
`segment`	No	which content tree to target: body (default), or the page header/footer. Header/footer content is invisible to a body read — a letterhead logo lives there.
`quotedText`	No	the text to comment on; required unless replyTo is given

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedv1.0.0Oct 31, 2026

addedInput schema / properties / content / description
```
Added value: +"the comment, or the reply"
```
removedInput schema / properties / documentId
```
Removed value: -{
-  "type": "string"
-}
```

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 / 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"
+}

addedInput schema / properties / quotedText

Added value: +{
+  "description": "the text to comment on; required unless replyTo is given",
+  "type": "string"
+}

changedInput schema / properties / replyTo / description

Previous value: -"a comment id (from list_comments) to reply to; omit to start a new top-level comment"New value: +"a comment id (from list_comments) to reply to; omit to start a new comment"

addedInput schema / properties / segment

Added value: +{
+  "description": "which content tree to target: body (default), or the page header/footer. Header/footer content is invisible to a body read — a letterhead logo lives there.",
+  "enum": [
+    "body",
+    "header",
+    "footer"
+  ],
+  "type": "string"
+}

changedInput schema / required

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

First observedv0.1.1Aug 1, 2026

TDQS

A4.5/5.0

Behavior4/5

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

With no annotations, the description carries the behavioral burden well: it explains that comments stay attached as text moves, ambiguous quotedText matches are refused with match context, and tab/header/footer behavior comes from path and segment. It does not cover permission requirements, notification behavior, or rate limits, so it is strong but not fully exhaustive.

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

Conciseness4/5

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

The description is dense and front-loads the core behavior, but some sentences are long and pack multiple constraints together. It is appropriately sized for a 7-parameter commenting tool with no annotations, and no sentence is clearly wasted.

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

Completeness4/5

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

Given 7 parameters, no annotations, and no output schema, the description is largely complete: it covers the main comment action, reply mode, quoting semantics, tab resolution, and header/footer targeting. It could be slightly more complete by mentioning auth/account expectations or any side effects around comment creation.

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 schema already documents each parameter. The description adds meaningful cross-parameter semantics: quotedText is required unless replyTo is given, replyTo takes a comment id from list_comments, path determines the tab, and segment controls body versus header/footer targeting.

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 states a specific verb and resource: commenting on text in a Google Doc, with a distinct reply mode. It also distinguishes the tool from edit_doc and list_comments, so an agent can identify its role without opening sibling schemas.

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 explicitly explains when to use quotedText versus replyTo, and gives the workaround for overall document feedback because Google Docs lacks whole-doc comments. It also routes agents to list_comments for reply IDs and edit_doc for understanding quotedText matching.

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