@aaronsb/google-workspace-mcp 4.0.1 → 4.2.1

package/README.md

@@ -5,170 +5,198 @@
 [![Node](https://img.shields.io/node/v/@aaronsb/google-workspace-mcp?logo=node.js&label=node)](https://nodejs.org)
 [![License](https://img.shields.io/github/license/aaronsb/google-workspace-mcp)](LICENSE)
 
-Give AI agents real access to Google Workspace — Gmail, Calendar, Drive, Docs, Sheets, Tasks, and Meet — through a single MCP server that handles multi-account credential routing, response shaping for AI consumption, and contextual next-step guidance.
+**Give your AI agent real access to Google Workspace** — Gmail, Calendar, Drive, Docs, Sheets, Tasks and Meet — from one MCP server, across as many accounts as you have.
 
-The server talks to Google's REST APIs directly, through a client it builds **from Google's own machine-readable API specifications**. Google publishes a [Discovery document](https://developers.google.com/discovery) for every API; a build step reads them and generates the descriptor this server dispatches against. Google's API surface *is* the source of truth — not a hand-maintained wrapper, and not a third-party CLI.
+Search your mail, check your calendar, write a doc, file a task — in conversation, as yourself.
 
-## Why This MCP Server
+## Install
 
-**For users:** One install gives your agent authenticated access to your Google accounts. Search email, check your calendar, manage Drive files, chain multi-step workflows — through natural conversation.
+First, you need **Google OAuth credentials** — the one prerequisite common to every path:
 
-**For teams:** Multi-account support lets one agent work across personal and work accounts at once, with per-account credential isolation and XDG-compliant storage.
+1. Go to [console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)
+2. Create an **OAuth 2.0 Client ID**, application type **Desktop app**
+3. Enable the APIs you want (Gmail, Calendar, Drive, Sheets, Docs, Tasks, Meet)
+4. Keep the **Client ID** and **Client Secret** handy — you'll paste them in below
 
-**For developers:** Adding an operation is a YAML edit, not a code change. The manifest curates which of Google's methods to expose; the generated descriptor already knows every method's path, HTTP verb, parameters, and scopes. Nothing is transcribed by hand, so nothing drifts from Google.
+Then pick the path that matches how you work. All three run the same server.
 
-## What's Available
+Node 22.12 or newer. (Node 18 and 20 are both end-of-life.)
 
-**11 tools — 7 Google services (80 operations), plus accounts, batching, content authoring, and a file sandbox.**
+---
 
-| Tool | What It Does |
-|------|--------------|
-| `manage_email` | Gmail — search, read (plain or sanitized HTML), send, reply / reply-all, forward, triage, trash, labels, threads, attachments |
-| `manage_calendar` | Calendar — list, agenda, get, create, quickAdd (natural language), update, delete, calendars, freebusy |
-| `manage_drive` | Drive — search, get, upload, download, copy, rename / move, delete, export, permissions, comments, view images |
-| `manage_sheets` | Sheets — read / write ranges (row-numbered output), append, clear, manage tabs, copy / duplicate / rename |
-| `manage_docs` | Docs — get, create, append, insert text, find-and-replace |
-| `manage_tasks` | Tasks — list / create / update / complete tasks and task lists |
-| `manage_meet` | Meet — browse past conferences, participants, transcripts, recordings, smart notes |
-| `manage_accounts` | Multi-account lifecycle — add accounts, manage credentials and scopes |
-| `manage_scratchpad` | Compose / edit multi-line content (line- or JSON-path-addressed), attach files, send to any target; JSON mode live-syncs to Docs / Sheets |
-| `manage_workspace` | File operations in the workspace sandbox (exchange point for attachments, downloads, exports) |
-| `queue_operations` | Chain operations sequentially with `$N.field` result references |
+### 📦 → 🤖 Claude Desktop — one-click `.mcpb` install (recommended)
 
-Every response carries **next-steps** guidance, so the agent always knows what it can do next.
+Download **`google-workspace-mcp.mcpb`** from the [latest release](https://github.com/aaronsb/google-workspace-mcp/releases/latest), then **drag it onto the Claude Desktop window**, or double-click it.
 
-Those 80 operations reach 60 of the 233 methods Google publishes across these seven APIs.
+Claude Desktop opens an install dialog with three fields:
 
-**Missing something you need?** The rest of the surface is mapped, not guessed. **[Browse every method Google publishes](docs/api-surface.md)** — what it does, whether we expose it, and a one-click link to request it. The descriptions are Google's own, and the page is generated from the same specification the client is built from, so it can't drift.
+| Field | |
+|---|---|
+| **Google OAuth Client ID** | required — from the step above |
+| **Google OAuth Client Secret** | required — from the step above |
+| **Workspace Directory** | optional — where attachments, downloads and exports land. Defaults to `~/.local/share/google-workspace-mcp/workspace/`. Give it a dedicated folder — not your home, Documents, Desktop, or a Google Drive folder. |
 
-The subset is curated on purpose: an agent has to *choose* among these, and every method it must weigh is one it can pick wrongly. But that judgement was made without you — if it's wrong for your case, **[say so](docs/coverage.md)**. A good request names the task, not the method.
+Paste, hit Save, done. No JSON to edit, no Node to install, no paths to get right — the bundle carries the server and every dependency.
 
-## How It Works
+**One bundle covers every platform** — macOS (Intel and Apple Silicon), Linux (x64 and ARM64), and Windows. There is nothing to choose: the server is pure JavaScript, so there is no platform-specific payload to pick between.
 
-Two phases. Google's API specification is acquired at **build time** and frozen into a committed artifact; at **runtime** the server only reads it.
+> *Cross-platform note:* `.mcpb` files install via Claude Desktop's bundled handler. If double-clicking doesn't trigger Claude on your system, drag the file onto the Claude Desktop window instead, or right-click → "Open with…" and pick Claude Desktop (then "always open with" if your OS offers). Behavior varies: macOS usually auto-associates, Windows may need a one-time association, Linux varies by desktop environment.
 
-### Build time — acquire the specification
+---
 
-```mermaid
-flowchart LR
-    disco["Google Discovery<br>documents"] --> gen["descriptor generator<br>generate-descriptor.mjs"]
-    gen --> desc[("src/google/descriptor.json<br>233 methods · committed<br>paths · verbs · params · scopes")]
-    desc --> gate{{"CI drift gate<br>regenerate and compare"}}
+### Claude Code — one command
 
-    classDef external fill:#f6821f,color:#1a1a1a,stroke:#d97706
-    classDef process  fill:#2d7d9a,color:#ffffff,stroke:#4a5568
-    classDef artifact fill:#2d8e5e,color:#ffffff,stroke:#4a5568
-    classDef guard    fill:#fbbf24,color:#1a1a1a,stroke:#d97706
-    class disco external
-    class gen process
-    class desc artifact
-    class gate guard
+```bash
+claude mcp add google-workspace \
+  -e GOOGLE_CLIENT_ID=your-client-id \
+  -e GOOGLE_CLIENT_SECRET=your-client-secret \
+  -- npx -y @aaronsb/google-workspace-mcp
 ```
 
-### Runtime — dispatch against it
+That's it — no file to edit. Verify with `/mcp`.
+
+---
+
+### Other MCP clients
+
+Add an entry to the client's MCP config file (for Claude Desktop by hand, that's `claude_desktop_config.json`; for Claude Code, `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "google-workspace": {
+      "command": "npx",
+      "args": ["-y", "@aaronsb/google-workspace-mcp"],
+      "env": {
+        "GOOGLE_CLIENT_ID": "your-client-id",
+        "GOOGLE_CLIENT_SECRET": "your-client-secret"
+      }
+    }
+  }
+}
+```
+
+Or install it globally and point at the binary directly:
+
+```bash
+npm install -g @aaronsb/google-workspace-mcp
+```
+
+## How it fits together
 
 ```mermaid
 flowchart LR
-    mcp["MCP client"] -->|stdio| factory["factory generator<br>schemas + handlers"]
-    manifest["manifest/*.yaml<br>which ops to expose"] --> factory
-    factory --> patches["patches<br>Gmail hydration · agenda merge · MIME"]
-    patches --> client["Google API client<br>+ account router"]
-    desc[("descriptor.json")] -. read at startup .-> client
-    client --> google["Google REST APIs"]
-
+    human["🧑 You<br>ask in plain language"]
+    agent["🤖 Your AI agent<br>Claude Desktop, Claude Code…"]
+    server["⚙️ This MCP server<br>picks the right account,<br>builds the real request"]
+    keys[("🔑 Your accounts<br>OAuth tokens, kept<br>on your own machine")]
+    google["☁️ Google<br>Gmail · Calendar · Drive<br>Docs · Sheets · Tasks · Meet"]
+
+    human -->|"“what's on my calendar?”"| agent
+    agent -->|"tool call"| server
+    server <-->|"which account?"| keys
+    server -->|"real API call, as you"| google
+    google -->|"your data"| server
+    server -->|"shaped for an agent<br>+ what to do next"| agent
+    agent -->|"an answer"| human
+
+    classDef person   fill:#475569,color:#ffffff,stroke:#94a3b8
+    classDef robot    fill:#2d7d9a,color:#ffffff,stroke:#4a5568
+    classDef ours     fill:#7c3aed,color:#ffffff,stroke:#8b5cf6
+    classDef secrets  fill:#2d8e5e,color:#ffffff,stroke:#4a5568
     classDef external fill:#f6821f,color:#1a1a1a,stroke:#d97706
-    classDef artifact fill:#2d8e5e,color:#ffffff,stroke:#4a5568
-    classDef config   fill:#fbbf24,color:#1a1a1a,stroke:#d97706
-    classDef core     fill:#7c3aed,color:#ffffff,stroke:#8b5cf6
-    classDef inert    fill:#475569,color:#ffffff,stroke:#94a3b8
+
+    class human person
+    class agent robot
+    class server ours
+    class keys secrets
     class google external
-    class desc artifact
-    class manifest config
-    class factory,patches,client core
-    class mcp inert
 ```
 
-**The descriptor** is generated from Google's Discovery documents and committed. A CI drift gate re-generates it and fails if the result differs, so the spec we dispatch against cannot silently fall behind Google.
+**Your credentials never leave your machine.** The server holds an OAuth token per account, on your own disk, and calls Google *as you* — there is no middleman service, no account of ours, nothing to sign up for. Add as many accounts as you like (personal and work, side by side); the server routes each request to the right one.
 
-**The client** (`src/google/client.ts`) is deliberately opinion-free: it builds the request Google's spec describes and returns exactly what Google returned. It does not reshape responses. All interpretation lives in patches and formatters, aimed at the MCP contract — which is what keeps "what Google said" and "what we chose to show" separable.
+## What it can do
 
-**The factory** reads the YAML manifest and generates MCP tool schemas and handlers at startup. **Patches** add behavior where an agent needs more than a raw API response — hydrating Gmail search results with senders and subjects, merging an agenda across calendars, building MIME for outbound mail. Operations without a patch get sensible defaults.
+**11 tools across 7 Google services**, plus multi-account handling, batching, content authoring, and a file sandbox.
 
-Because method names are generated into a TypeScript union, calling a method Google doesn't publish is a **compile error**, not a 404 at runtime.
+| Tool | What It Does |
+|------|--------------|
+| `manage_email` | Gmail — search, read (plain or sanitized HTML), send, reply / reply-all, forward, triage, trash, labels, threads, attachments |
+| `manage_calendar` | Calendar — list, agenda, get, create, quickAdd (natural language), update, delete, calendars, freebusy |
+| `manage_drive` | Drive — search, get, upload, download, copy, rename / move, delete, export, permissions, comments, view images |
+| `manage_sheets` | Sheets — read / write ranges (row-numbered output), append, clear, manage tabs, copy / duplicate / rename |
+| `manage_docs` | Docs — get, create, append, insert text, find-and-replace |
+| `manage_tasks` | Tasks — list / create / update / complete tasks and task lists |
+| `manage_meet` | Meet — browse past conferences, participants, transcripts, recordings, smart notes |
+| `manage_accounts` | Multi-account lifecycle — add accounts, manage credentials and scopes |
+| `manage_scratchpad` | Compose / edit multi-line content (line- or JSON-path-addressed), attach files, send to any target; JSON mode live-syncs to Docs / Sheets |
+| `manage_workspace` | File operations in the workspace sandbox (exchange point for attachments, downloads, exports) |
+| `queue_operations` | Chain operations sequentially with `$N.field` result references |
 
-## Install
+Every response carries **next-steps** guidance, so the agent always knows what it can do next.
 
-### MCPB Bundle (Claude Desktop and other MCP clients)
+## One ask, many steps
 
-Download `google-workspace-mcp.mcpb` from the [latest release](https://github.com/aaronsb/google-workspace-mcp/releases).
+The useful part isn't any single operation — it's that your agent can **string them together**.
 
-One bundle covers every platform — macOS (Intel and Apple Silicon), Linux (x64 and ARM64), and Windows. There is nothing to choose: the server is pure JavaScript on Node, so there is no platform-specific payload to pick between. It needs Node 22.12 or newer.
+You ask for one thing. The agent works out that it needs four API calls, in order, each one feeding the next:
 
-In Claude Desktop, drag the `.mcpb` file into the app — it will prompt for your Google OAuth credentials. Other MCP clients that support `.mcpb` extensions install it the same way. The bundle includes the server and all of its dependencies.
+```mermaid
+sequenceDiagram
+    autonumber
+    participant H as 🧑 You
+    participant A as 🤖 Your agent
+    participant S as ⚙️ MCP server
+    participant G as ☁️ Google
+
+    H->>A: "file the invoice from Acme<br>and remind me to pay it Friday"
+    A->>S: find the email
+    S->>G: search Gmail
+    G-->>S: the message
+    S-->>A: found it — and here's what you can do next
+    A->>S: save the attachment
+    S->>G: download it
+    A->>S: put it in Drive
+    S->>G: upload
+    A->>S: create a task, due Friday
+    S->>G: Google Tasks
+    A-->>H: Done. Invoice filed, task set for Friday.
+```
 
-### Claude Code / npm
+Two things make this work. Every response tells the agent **what it can do next**, so it isn't guessing at the next step. And `queue_operations` lets it run a whole chain in **one call**, feeding each result into the next — so "find the invoice, file it, remind me" is a single round trip rather than four.
 
-```bash
-npm install @aaronsb/google-workspace-mcp
-```
+## Ask for what's missing
 
-Or run directly:
+This server exposes **80 operations**, reaching 60 of the **233 methods** Google publishes across those seven APIs. It is a curated subset on purpose: an agent has to *choose* among these, and every method it must weigh is one it can pick wrongly. A tool with 233 operations isn't more capable than one with 80 — it's harder to use correctly.
 
-```bash
-npx @aaronsb/google-workspace-mcp
-```
+But that judgement was made without you.
 
-### Prerequisites
+**→ [Browse every method Google publishes](docs/api-surface.md)**
 
-1. **Node.js** 22.12 or newer — Node 18 and 20 are both end-of-life.
-2. **Google Cloud OAuth credentials** — create at [console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials):
-   - Create an OAuth 2.0 Client ID (Desktop application)
-   - Enable the APIs you want (Gmail, Calendar, Drive, Sheets, …)
-3. Set environment variables:
-   ```bash
-   export GOOGLE_CLIENT_ID="your-client-id"
-   export GOOGLE_CLIENT_SECRET="your-client-secret"
-   ```
+Every method is listed — what it does, whether we expose it, and a **Request** link that opens a pre-filled issue. The descriptions are Google's own, quoted verbatim, and the page is generated from the same specification the client is built from, so it can't drift from reality.
 
-## MCP Client Configuration
+That page also lists **four whole APIs this server doesn't touch yet** — Chat, Contacts, Slides and Forms — for the same reason: *not targeted* is a decision, not a fact of nature.
 
-### Claude Desktop
+A good request **names the task, not the method**:
 
-Add to `claude_desktop_config.json`:
+> *"I want the agent to file incoming invoices into a folder automatically."*
 
-```json
-{
-  "mcpServers": {
-    "google-workspace": {
-      "command": "npx",
-      "args": ["@aaronsb/google-workspace-mcp"],
-      "env": {
-        "GOOGLE_CLIENT_ID": "your-client-id",
-        "GOOGLE_CLIENT_SECRET": "your-client-secret"
-      }
-    }
-  }
-}
-```
+That can be evaluated. It might turn out an existing operation already does it, or that the right answer is a different method than the one you found. *"Expose `users.settings.filters.create`"* is a conclusion, not a case — lead with the problem and let the method follow.
 
-### Claude Code
+## Why Apache 2.0, and not open core
 
-Add to `.mcp.json`:
+**Everything is here.** There is no paid tier, no "enterprise" build, no feature held back to sell you later. What you install is what exists.
 
-```json
-{
-  "mcpServers": {
-    "google-workspace": {
-      "command": "npx",
-      "args": ["@aaronsb/google-workspace-mcp"],
-      "env": {
-        "GOOGLE_CLIENT_ID": "your-client-id",
-        "GOOGLE_CLIENT_SECRET": "your-client-secret"
-      }
-    }
-  }
-}
-```
+Open core works by keeping the good part back. The free thing is a lead magnet, and the moment your use gets serious you discover the operation you need lives behind a licence. That model would be especially rotten *here*: this is a piece of plumbing between you and **your own data**, using **your own Google credentials**, running on **your own machine**. Nothing about that arrangement should have a paywall in the middle of it, and nothing about it needs a vendor.
+
+[Apache 2.0](LICENSE) rather than MIT for two concrete reasons:
+
+- **An explicit patent grant.** Contributors licence their patent claims along with their code, so using this can't become a patent problem later. MIT is silent on patents, which means the question is merely unanswered rather than settled.
+- **It's safe to adopt at work.** Apache 2.0 is on essentially every corporate allow-list. Fork it, vendor it, ship it inside a commercial product — you don't owe anyone anything, and you don't need to ask.
+
+The one obligation is attribution: keep the notices ([`NOTICE`](NOTICE), [`LICENSE`](LICENSE)) with the code. That's it.
+
+Through v3.0.0 this project was MIT-licensed, and that history is preserved rather than erased — MIT-era contributions keep their original notice in [`LICENSE-MIT`](LICENSE-MIT), and their authors are credited in [`NOTICE`](NOTICE). Apache 2.0 takes back nothing MIT permitted.
 
 ## Usage
 
@@ -199,20 +227,7 @@ Chain operations with result references — the output of one step feeds the nex
 }
 ```
 
-## Expanding Coverage
-
-The coverage mapper diffs what the manifest exposes against what Google actually publishes, so the frontier is always measured rather than estimated:
-
-```bash
-npm run generate-descriptor   # re-read Google's Discovery documents
-make coverage                 # what we expose vs. what Google offers
-make manifest-lint            # validate the curated manifest
-make check                    # type-check, lint, test, build, smoke
-```
-
-To expose a new operation, add it to the relevant `src/factory/manifest/*.yaml`. The descriptor already knows its path, verb, parameters, and scopes, and the factory generates the tool schema and handler. New operations get default formatting automatically — add a patch only when an agent needs a shaped response rather than a raw one.
-
-## Data Storage
+## Where your data lives
 
 Follows the XDG Base Directory Specification:
 
@@ -224,19 +239,17 @@ Follows the XDG Base Directory Specification:
 
 Credentials are per-account files holding standard OAuth tokens. No secrets are stored in the project directory.
 
-## Design
+## Under the hood
 
-The server generates its API client from Google's own Discovery documents and calls Google directly. Nothing sits between the server and the API it targets: there is no subprocess, no second response shape, and no unversioned wrapper to keep in step. The descriptor is regenerated and diffed against Google on every build, so a method that does not exist is a compile error rather than a runtime surprise.
+You don't need any of this to use the server. But if you're curious, or you want to add an operation:
 
-On top of that sits the manifest-driven tool factory: adding an operation is a YAML edit, not a code change. The coverage mapper reads Google's real published surface, so "what we expose vs what exists" is a measured number.
+The server builds its Google API client **from Google's own machine-readable API specifications**. Nothing is transcribed by hand, so the surface can't drift from reality, and adding an operation is a YAML edit rather than a code change.
 
-The reasoning behind this design, including what was verified and what it cost, is in **[ADR-103](docs/architecture/core/ADR-103-generate-a-google-api-descriptor-retire-the-gws-facade.md)**.
+- **[How it works](docs/how-it-works.md)** — the build-time / runtime split, the descriptor, the factory
+- **[API coverage](docs/coverage.md)** — what's exposed, what isn't, and how to ask for more
+- **[The full API surface](docs/api-surface.md)** — every method Google publishes, plus the four APIs we don't target yet
+- **[Architecture decisions](docs/architecture/)** — the ADRs, including why this server owns its Google client outright
 
 ## License
 
-[Apache License 2.0](LICENSE).
-
-Through v3.0.0 this project was MIT-licensed. Those contributions keep their original
-notice (`LICENSE-MIT`), and the contributors are credited in [`NOTICE`](NOTICE). Apache 2.0
-adds an explicit patent grant and a state-your-changes requirement; it does not take back
-anything MIT permitted.
+[Apache License 2.0](LICENSE) — see [Why Apache 2.0](#why-apache-20-and-not-open-core) above.

package/build/factory/manifest/calendar.yaml

@@ -13,10 +13,10 @@ operations:
     params:
       calendarId:
         type: string
-        description: "Calendar ID to query (default: 'primary'). Use 'calendars' operation to list available IDs."
+        description: "Calendar ID. Use the `calendars` operation to list available IDs; required for events on shared calendars. Defaults to 'primary' on the event operations (`list`, `get`, `create`, `quickAdd`, `update`, `delete`). On `agenda`, a calendar name or ID to filter to — OMIT it to span all calendars, and do not pass 'primary', which is an API alias rather than an id agenda matches on. On `freebusy`, a comma-separated list of calendar IDs to check IN ADDITION to your own."
       timeMin:
         type: string
-        description: "Start of range (ISO 8601) — defaults to today"
+        description: "Start of range (ISO 8601). On `list`, defaults to today."
       timeMax:
         type: string
         description: "End of range (ISO 8601)"
@@ -40,7 +40,7 @@ operations:
     params:
       calendarId:
         type: string
-        description: "Filter to a specific calendar name or ID"
+        description: "Calendar ID. Use the `calendars` operation to list available IDs; required for events on shared calendars. Defaults to 'primary' on the event operations (`list`, `get`, `create`, `quickAdd`, `update`, `delete`). On `agenda`, a calendar name or ID to filter to — OMIT it to span all calendars, and do not pass 'primary', which is an API alias rather than an id agenda matches on. On `freebusy`, a comma-separated list of calendar IDs to check IN ADDITION to your own."
       days:
         type: number
         description: "Number of days ahead to show (default: today only)"
@@ -58,7 +58,7 @@ operations:
     params:
       calendarId:
         type: string
-        description: "Calendar ID (default: 'primary'). Required for events on shared calendars."
+        description: "Calendar ID. Use the `calendars` operation to list available IDs; required for events on shared calendars. Defaults to 'primary' on the event operations (`list`, `get`, `create`, `quickAdd`, `update`, `delete`). On `agenda`, a calendar name or ID to filter to — OMIT it to span all calendars, and do not pass 'primary', which is an API alias rather than an id agenda matches on. On `freebusy`, a comma-separated list of calendar IDs to check IN ADDITION to your own."
       eventId:
         type: string
         description: "Event ID"
@@ -74,7 +74,7 @@ operations:
     params:
       calendarId:
         type: string
-        description: "Calendar ID (default: 'primary')"
+        description: "Calendar ID. Use the `calendars` operation to list available IDs; required for events on shared calendars. Defaults to 'primary' on the event operations (`list`, `get`, `create`, `quickAdd`, `update`, `delete`). On `agenda`, a calendar name or ID to filter to — OMIT it to span all calendars, and do not pass 'primary', which is an API alias rather than an id agenda matches on. On `freebusy`, a comma-separated list of calendar IDs to check IN ADDITION to your own."
       summary:
         type: string
         description: "Event title"
@@ -95,10 +95,10 @@ operations:
         description: "Event location"
       attendees:
         type: string
-        description: "Comma-separated attendee emails"
+        description: "Comma-separated email addresses. On `update`, whatever you pass REPLACES the existing list — addresses you leave out are removed, and an empty string clears everyone. OMIT the parameter to leave the attendee list untouched while changing other fields. On `freebusy`, the addresses whose availability to check."
       meet:
         type: boolean
-        description: "Add a Google Meet video conference link to the event"
+        description: "Add a Google Meet video conference link. On `update`, true adds a link and false REMOVES an existing one; omit it to leave the link as it is."
 
   quickAdd:
     type: action
@@ -107,7 +107,7 @@ operations:
     params:
       calendarId:
         type: string
-        description: "Calendar ID (default: 'primary')"
+        description: "Calendar ID. Use the `calendars` operation to list available IDs; required for events on shared calendars. Defaults to 'primary' on the event operations (`list`, `get`, `create`, `quickAdd`, `update`, `delete`). On `agenda`, a calendar name or ID to filter to — OMIT it to span all calendars, and do not pass 'primary', which is an API alias rather than an id agenda matches on. On `freebusy`, a comma-separated list of calendar IDs to check IN ADDITION to your own."
       text:
         type: string
         description: "Natural language event description"
@@ -122,32 +122,32 @@ operations:
     params:
       calendarId:
         type: string
-        description: "Calendar ID (default: 'primary')"
+        description: "Calendar ID. Use the `calendars` operation to list available IDs; required for events on shared calendars. Defaults to 'primary' on the event operations (`list`, `get`, `create`, `quickAdd`, `update`, `delete`). On `agenda`, a calendar name or ID to filter to — OMIT it to span all calendars, and do not pass 'primary', which is an API alias rather than an id agenda matches on. On `freebusy`, a comma-separated list of calendar IDs to check IN ADDITION to your own."
       eventId:
         type: string
-        description: "Event ID to update"
+        description: "Event ID"
         required: true
       summary:
         type: string
-        description: "Updated event title"
+        description: "Event title"
       start:
         type: string
-        description: "Updated start time (ISO 8601)"
+        description: "Start time (ISO 8601)"
       end:
         type: string
-        description: "Updated end time (ISO 8601)"
+        description: "End time (ISO 8601)"
       description:
         type: string
-        description: "Updated description"
+        description: "Event description or notes"
       location:
         type: string
-        description: "Updated location"
+        description: "Event location"
       attendees:
         type: string
-        description: "Comma-separated attendee emails. REPLACES the existing attendee list entirely (Google events.patch overwrites arrays). Pass an empty string to clear all attendees."
+        description: "Comma-separated email addresses. On `update`, whatever you pass REPLACES the existing list — addresses you leave out are removed, and an empty string clears everyone. OMIT the parameter to leave the attendee list untouched while changing other fields. On `freebusy`, the addresses whose availability to check."
       meet:
         type: boolean
-        description: "Add a Google Meet video conference link. Note: Google Calendar does not allow removing an existing Meet link via patch; omit or set false to leave the link untouched."
+        description: "Add a Google Meet video conference link. On `update`, true adds a link and false REMOVES an existing one; omit it to leave the link as it is."
     defaults:
       calendarId: primary
 
@@ -158,10 +158,10 @@ operations:
     params:
       calendarId:
         type: string
-        description: "Calendar ID (default: 'primary')"
+        description: "Calendar ID. Use the `calendars` operation to list available IDs; required for events on shared calendars. Defaults to 'primary' on the event operations (`list`, `get`, `create`, `quickAdd`, `update`, `delete`). On `agenda`, a calendar name or ID to filter to — OMIT it to span all calendars, and do not pass 'primary', which is an API alias rather than an id agenda matches on. On `freebusy`, a comma-separated list of calendar IDs to check IN ADDITION to your own."
       eventId:
         type: string
-        description: "Event ID to delete"
+        description: "Event ID"
         required: true
     defaults:
       calendarId: primary
@@ -180,7 +180,7 @@ operations:
     params:
       timeMin:
         type: string
-        description: "Start of range (ISO 8601)"
+        description: "Start of range (ISO 8601). On `list`, defaults to today."
         required: true
       timeMax:
         type: string
@@ -188,7 +188,7 @@ operations:
         required: true
       attendees:
         type: string
-        description: "Comma-separated email addresses to check availability for"
+        description: "Comma-separated email addresses. On `update`, whatever you pass REPLACES the existing list — addresses you leave out are removed, and an empty string clears everyone. OMIT the parameter to leave the attendee list untouched while changing other fields. On `freebusy`, the addresses whose availability to check."
       calendarId:
         type: string
-        description: "Comma-separated calendar IDs to check (in addition to own calendar)"
+        description: "Calendar ID. Use the `calendars` operation to list available IDs; required for events on shared calendars. Defaults to 'primary' on the event operations (`list`, `get`, `create`, `quickAdd`, `update`, `delete`). On `agenda`, a calendar name or ID to filter to — OMIT it to span all calendars, and do not pass 'primary', which is an API alias rather than an id agenda matches on. On `freebusy`, a comma-separated list of calendar IDs to check IN ADDITION to your own."

package/build/factory/manifest/docs.yaml

@@ -4,6 +4,10 @@ requires_email: true
 google_service: docs
 operations:
 
+  # A document's text lives per-TAB, and `tabId` is the handle that addresses one — the
+  # same handle every write operation below takes. Reading without it spans the document;
+  # reading with it scopes both the text and the character indices to one tab, so an
+  # index measured here means the same thing to insertText (#157, #158).
   get:
     type: detail
     description: "get document content and metadata"
@@ -13,6 +17,9 @@ operations:
         type: string
         description: "Document ID"
         required: true
+      tabId:
+        type: string
+        description: "Tab to act on — a tabId from a previous get's tabIndex. Scopes the read on get; targets the edit on write/insertText/replaceText, which act on the FIRST tab when it is omitted (replaceText spans every tab). Character indices are per-tab."
 
   # `title` rides in the BODY — documents.create declares no parameters at all
   # (Discovery: `"parameters": {}`), so everything goes into the Document resource.
@@ -42,8 +49,11 @@ operations:
         required: true
       text:
         type: string
-        description: "Text to append (plain text)"
+        description: "Text to write (plain text) — appended to the end by write, inserted at `index` by insertText"
         required: true
+      tabId:
+        type: string
+        description: "Tab to act on — a tabId from a previous get's tabIndex. Scopes the read on get; targets the edit on write/insertText/replaceText, which act on the FIRST tab when it is omitted (replaceText spans every tab). Character indices are per-tab."
 
   insertText:
     type: action
@@ -56,12 +66,15 @@ operations:
         required: true
       text:
         type: string
-        description: "Text to insert"
+        description: "Text to write (plain text) — appended to the end by write, inserted at `index` by insertText"
         required: true
       index:
         type: number
-        description: "Character index to insert at (1 = start of document body)"
+        description: "Character index to insert at (1 = start of the tab's body)"
         required: true
+      tabId:
+        type: string
+        description: "Tab to act on — a tabId from a previous get's tabIndex. Scopes the read on get; targets the edit on write/insertText/replaceText, which act on the FIRST tab when it is omitted (replaceText spans every tab). Character indices are per-tab."
 
   replaceText:
     type: action
@@ -84,3 +97,6 @@ operations:
         type: boolean
         description: "Case-sensitive match (default: true)"
         default: true
+      tabId:
+        type: string
+        description: "Tab to act on — a tabId from a previous get's tabIndex. Scopes the read on get; targets the edit on write/insertText/replaceText, which act on the FIRST tab when it is omitted (replaceText spans every tab). Character indices are per-tab."