verified-googledocs-mcp

add_anchored_comment

Add a comment to a specific quoted passage in a Google Docs tab. Validates the quote exists, returns comment-state evidence, and lists nearest matches if not found.

Instructions

Add a comment to a document, validated against a quoted passage.

Use this tool when you need to create a comment on specific text in a document tab. The quote must exist in the tab — the tool locates it via the same normalization ladder as replace_text and returns QUOTE_NOT_FOUND with nearest candidate anchors if the quote is absent.

NOTE: The Drive API may render the created comment as document-level even when quotedFileContent is supplied. This behaviour is pending confirmation from a live anchoring spike; for now the comment is created with the quote embedded in its content and the tool returns comment-state evidence.

Returns comment-state evidence: applied, comment_id, resolved, reply_count, content, quoted_text, audit_logged.

Errors: QUOTE_NOT_FOUND – quote not found in the tab; nearest candidates listed INVALID_INPUT – empty body or quote TAB_NOT_FOUND – tab_id not in document

Input Schema

TableJSON Schema

Name	Required	Description	Default
`body`	Yes
`quote`	Yes
`doc_id`	Yes
`tab_id`	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.7/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 excellently. It discloses non-obvious behavior: the normalization ladder, QUOTE_NOT_FOUND with nearest candidate anchors, the Drive API caveat about document-level rendering, the quote being embedded in content, and the returned comment-state evidence.

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 well-structured and front-loaded: a one-sentence purpose, a clear usage paragraph, a caveat, a return summary, and a compact error list. Every sentence contributes useful information, and the formatting makes the error cases 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?

The description is complete for a 4-parameter tool with no annotations and zero schema coverage. It explains the core behavior, important edge cases, return evidence, and error conditions. The presence of an output schema means the return-value list is sufficient without needing a full schema explanation.

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 description coverage is 0%, so the description must compensate. It adds meaningful semantics for quote and body via the validation rule and INVALID_INPUT error, and clarifies tab_id through TAB_NOT_FOUND. doc_id is implied by the document context. The description does not fully enumerate each parameter, but it covers the non-obvious ones well.

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: 'Add a comment to a document, validated against a quoted passage.' It clearly distinguishes this tool from comment-management siblings like reply_to_comment, resolve_comment, and get_comment_thread by focusing on creating a comment anchored to specific text.

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 states when to use the tool: 'Use this tool when you need to create a comment on specific text in a document tab.' It also clarifies the quote must exist in the tab, which is a key precondition. It does not explicitly name alternatives or exclusions, but the sibling set makes the intended use clear.

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