google-docs

• **Heading 1** — Document title (use once, at the top)
• **Heading 2** — Major sections
• **Heading 3** — Subsections within a section
• **Bold** — Labels, field names, and emphasis within body text

**Structure the content first, then apply formatting generously.** A

well-formatted document uses headings for every distinct section — not just the

title. Think of each logical group of content as deserving its own heading.

#### Example: PR Summary Document

**Step 1 — Content:**

PR Summary Report

PR #246: Add Gmail Skill

Author: Allen Hutchison
Status: Merged

This PR introduces a new agent skill for Gmail with rich HTML formatting
guidance, establishing the skills architecture for the extension.

Key Changes:
- Added skills/gmail/SKILL.md with email formatting instructions
- Updated WORKSPACE-Context.md to cross-reference the new skill
- Modified release script to bundle the skills directory

PR #245: Bump rollup from 4.57.1 to 4.59.0

Author: dependabot
Status: Merged

Routine dependency update for the build pipeline.

**Step 2 — Formatting:**

docs.formatText({
  documentId: "<id>",
  formats: [
    // Document title
    { startIndex: 1, endIndex: 18, style: "heading1" },
    // PR section headings
    { startIndex: 20, endIndex: 45, style: "heading2" },
    { startIndex: 287, endIndex: 325, style: "heading2" },
    // Field labels
    { startIndex: 47, endIndex: 54, style: "bold" },
    { startIndex: 73, endIndex: 80, style: "bold" },
    { startIndex: 89, endIndex: 101, style: "bold" },
    { startIndex: 327, endIndex: 334, style: "bold" },
    { startIndex: 347, endIndex: 354, style: "bold" },
  ]
})

### Formatting Best Practices

1. **Always insert text first**, then apply formatting — formatting operates on

existing text ranges

2. **Calculate indices carefully** — count characters including newlines (\n)

3. **Heading styles apply to the entire paragraph** — even if the range covers

only part of it

4. **Multiple styles can stack** — apply both heading2 and bold to the same

range for bold headings

5. **Use links for URLs** — apply link style with a url field instead of

pasting raw URLs

6. **Format generously** — use heading2 for every major section, bold for every

label or field name. A document with only a heading1 title and plain text

body looks unprofessional

Creating Documents

Use docs.create to create new documents:

• **Blank document**: Provide only a title
• **Document with content**: Provide title and content — the content is

inserted into the document after creation

• **In a specific folder**: Add folderName to organize the document

docs.create({
  title: "Weekly Status Report",
  content: "Status Report - Week of March 10\n\nHighlights\n\n- ...",
  folderName: "Team Reports"
})

Writing Text

Use docs.writeText to add text to an existing document:

• **Append to end** (default): position: "end" or omit position
• **Insert at beginning**: position: "beginning"
• **Insert at specific index**: position: "5" (numeric string)

docs.writeText({
  documentId: "doc-id",
  text: "New content\n",
  position: "end"
})

Find and Replace

Use docs.replaceText to find all occurrences of a string and replace them.

This works across all tabs by default, or in a specific tab with tabId.

Tab Management

Google Docs supports multiple tabs within a single document.

### Reading Tabs

• **Single tab**: docs.getText returns plain text directly
• **Multiple tabs**: Returns JSON array with tabId, title, content, and

index for each tab

• **Specific tab**: Pass tabId to read only that tab
• **Nested tabs**: Child tabs are flattened and included in results

### Writing to Tabs

All write tools (writeText, replaceText, formatText) accept an optional

tabId parameter:

• **Without tabId**: Operates on the first tab (default)
• **With tabId**: Operates on the specified tab, including nested child tabs

Document Organization

### Finding Documents

Use drive.search with a document MIME type filter to find Google Docs:

drive.search({
  query: "mimeType='application/vnd.google-apps.document' and name contains 'Weekly Report'"
})

For full-text search across document content, use fullText contains instead of

name contains.

### Moving Documents

Use drive.moveFile to move a document to a different folder. You can specify

the destination by folder ID or folder name.

Comments & Suggestions

### Reading Comments

Use drive.getComments to retrieve all comments on a document:

• Returns comment threads with author, content, timestamp, and resolution status
• Includes **threaded replies** with author, content, timestamp, and action

(e.g., resolve, reopen)

• Includes **quoted file content** showing what text the comment is anchored to

drive.getComments({ fileId: "doc-id" })

### Reading Suggestions

Use docs.getSuggestions to retrieve suggested edits from a document:

• **Insertions** — text proposed for addition (suggestedInsertionIds)
• **Deletions** — text proposed for removal (suggestedDeletionIds)
• **Style changes** — text formatting changes (bold, italic, etc.)
• **Paragraph style changes** — heading level changes (e.g., NORMAL_TEXT →

HEADING_2)

Each suggestion includes the affected text, suggestion IDs, and start/