--- title: "Using the New Google Docs API Suggestions and Comments to Build a Gemini Writing Coach in Apps Script" author: "Martin Hawksey" date: 2026-11-03T21:08:16+00:00 modified: 2026-11-03T21:08:19+00:00 canonical_url: https://pulse.appsscript.info/p/2026/11/using-the-new-google-docs-api-suggestions-and-comments-to-build-a-gemini-writing-coach-in-apps-script/ markdown_url: https://pulse.appsscript.info/p/2026/11/using-the-new-google-docs-api-suggestions-and-comments-to-build-a-gemini-writing-coach-in-apps-script.md categories: - "Docs" - "Solutions" tags: - "tanaikech.github.io" featured_image: https://pulse.appsscript.info/files/2026/11/documentor_ai_overview_infographic.jpg description: "Learn how to use the new Google Docs API suggestions and comments in Apps Script with Gemini, including index management and DocumentApp selection mapping." --- # Using the New Google Docs API Suggestions and Comments to Build a Gemini Writing Coach in Apps Script ![Using the New Google Docs API Suggestions and Comments to Build a Gemini Writing Coach in Apps Script](https://pulse.appsscript.info/files/2026/11/documentor_ai_overview_infographic.jpg) > When we use generative AI to proofread our daily writing, whether technical reports, business proposals, or blog posts, it is easy to fall into the habit of simply copying and pasting AI-rewritten text without reflecting on *what* was changed or *why*. While that fixes the immediate draft, it rarely helps us grow as writers. In our [Q3 2026 Google Workspace Developer Release Notes](https://pulse.appsscript.info/p/2026/09/google-workspace-developer-release-notes-q3-2026-the-shift-toward-agentic-collaboration/), we highlighted the arrival of native [comment and suggestion management in the Google Docs API (`v1`)**](https://developers.google.com/workspace/docs/api/how-tos/suggestions). Inspired by Romin Irani’s recent Google Cloud series on building [ADK document reviewers**](https://medium.com/google-cloud/building-an-ai-document-reviewer-with-google-adk-gemini-and-the-new-google-docs-comments-1f79fb6cb86f) and [comment assistants**](https://medium.com/google-cloud/building-an-ai-comment-assistant-in-google-docs-with-adk-and-the-new-docs-api-v1-comment-b293aecaa92c), Kanshi Tanaike has released **DocuMentor AI**, an open-source Google Docs add-on built in Google Apps Script that turns those new endpoints into an interactive writing coach. Developers who have worked with the Google Docs API will know the challenge of managing shifting `startIndex` and `endIndex` character offsets when inserting and removing content (and since `DocumentApp` doesn’t support Suggesting mode or comments, there is no avoiding the REST API here). If you’ve already explored the official [`WriteControl` and suggestions guide**](https://developers.google.com/workspace/docs/api/how-tos/suggestions), the guide simplifies this by only showing single-request examples, such as inserting a string at `index: 1` with `writeMode: "SUGGEST"`. Digging into Kanshi’s implementation reveals several practical patterns that aren’t covered in the official docs: - **Applying Suggestions**: You cannot propose a suggested edit and reply to it in the same `batchUpdate` call because the suggestion ID doesn’t exist until the edit is created. Kanshi solves this in two steps: first applying all suggested edits in reverse order (from the bottom of the document to the top) so character positions don’t shift, and then using the suggestion IDs returned in the response to attach the coaching notes (`addCommentReply`) in a second `batchUpdate` call. - **Commenting on Tables & Images**: Adding text suggestions immediately changes the character positions of everything further down the page. Before attaching review comments to charts or tables, the script fetches the document a second time to get their updated positions, and falls back to the surrounding paragraph if the API rejects anchoring a comment directly to an image. - **Mapping Selections**: The Docs REST API has no way to know what a user has highlighted on screen, while `DocumentApp.getSelection()` doesn’t return the `startIndex` and `endIndex` offsets the REST API requires. To let users review just a highlighted section, the script matches the selected `DocumentApp` elements (and any comments anchored to them) to their corresponding positions in the Docs API response. - **Tracking Accepted or Edited**: Because `WriteMode.SUGGEST` runs under the user’s own account and resolved suggestions disappear from the document body, the API doesn’t distinguish AI edits from human ones or track what the writer did with them. To work around this, the script saves each AI suggestion ID and its surrounding text in `DocumentProperties`, comparing them on later runs to see whether the suggestion was accepted as-is, edited further, or rejected. Since publishing his original walkthrough, Kanshi has continued to iterate on the project, sharing a follow-up post, [Beyond Passive AI Rewrites and Vibe Coding in Google Docs**](https://tanaikech.github.io/2026/10/27/beyond-passive-ai-rewrites-and-vibe-coding-in-google-docs/), along with several updates to the repository adding embedded code-block review, Google Drive rulebook grounding, and admin-friendly API key management. To explore the full walkthrough and the latest version of the code, check out the source post below and the [tanaikech/DocuMentorAI**](https://github.com/tanaikech/DocuMentorAI) repository on GitHub. Source: [Building a Multimodal, Suggestion-Based AI Writing Coach with Gemini and Google Docs – Kanshi Tanaike**](https://tanaikech.github.io/2026/10/23/building-a-multimodal-suggestion-based-ai-writing-coach-with-gemini-and-google-docs/) --- *Published by [Martin Hawksey](https://pulse.appsscript.info/p/author/admin/) on [Pulse](https://pulse.appsscript.info/). Original article: [https://pulse.appsscript.info/p/2026/11/using-the-new-google-docs-api-suggestions-and-comments-to-build-a-gemini-writing-coach-in-apps-script/](https://pulse.appsscript.info/p/2026/11/using-the-new-google-docs-api-suggestions-and-comments-to-build-a-gemini-writing-coach-in-apps-script/)*