## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents read Gmail, Calendar, Drive, Docs, Sheets and Slides through the built-in Google Workspace connection > - Paperclip now has its own REST-backed Google tools in `server/src/google-workspace-rest-tools/`. No service uses them yet > - That folder guessed a result size limit of 250,000 bytes. It applied the limit only to Drive, Docs, Sheets and Slides. Gmail and Calendar had no limit > - The guess was wrong in both directions. It refused documents that Paperclip can deliver, and the folder should not know Paperclip's limits > - This pull request makes the limit a number that the gateway gives. The folder applies it to every tool in all six services through one check. It also brings three Google planning docs up to date > - The benefit is that a REST result is refused only when the gateway would also refuse the same result from Google's own MCP server ## Linked Issues or Issue Description Refs #22027, #22028, #22029, #22026 **Is your feature request related to a problem?** The REST tools refused results over a size the folder chose itself (250,000 bytes). Paperclip can deliver larger results: the runner saves a large result as an artifact and gives the agent a pointer. Gmail and Calendar results had no limit at all. **Describe the solution you'd like** The gateway gives the limit. The folder applies the given number to the final serialized result of every tool, with one helper. A result over the limit is an error that says how to ask for less. It is never cut short. **Describe alternatives you've considered** A larger number chosen from the runner's 1 GiB capture limit. Google's own transfer limit (20 MB per response) and memory use make that a poor choice. Also, results would then differ between the REST path and Google's MCP path. ### Limits a tool result passes on the way to an agent | Point | Limit | What happens over it | | --- | --- | --- | | Google response read by `google-http.ts` | 20 MB (`MAX_RESPONSE_BYTES`) | Tool error. Nothing returned | | REST folder result (new) | the number the gateway passes: 999,885 bytes | Tool error with "read less" advice. The gateway returns `tool_error` (502) | | Gateway read of a remote MCP response (`MAX_REMOTE_MCP_RESPONSE_BYTES` in `tool-gateway.ts`) | 1,000,000 bytes per JSON body or event-stream message | `mcp_remote_response_too_large` (502). This is the "1,000,000 bytes are rejected" statement in `doc/prompt-injection-prevention.md`. It applies to the Google MCP path only; the REST path has no HTTP read | | Injection screening model check | 256 KiB model request | Not a delivery limit. A larger result is checked by the built-in patterns only | | Gateway HTTP route (`POST /tool-gateway/.../tools/call`) | none in Paperclip | `res.json(result)` | | Runner (`captureRunnerToolResult`) | 500,000 bytes (`RUNNER_TOOL_RESULT_MAX_BYTES`) | Saved as an artifact. The agent gets a pointer and reads it with `read_tool_result` | | Runner capture | 1 GiB (`RUNNER_API_RESPONSE_MAX_BYTES`) | `SemanticToolOutcomeUnknownError` | The gateway wraps the result as `{ content, data: { content, structuredContent, ... } }`, so the payload occurs again. Measured: a Gmail result of 676,459 bytes from the folder became 1,017,386 bytes delivered (ratio 1.50). The ratio cannot be more than 2. ### The budget `GOOGLE_WORKSPACE_REST_MAX_RESULT_BYTES` in `tool-gateway.ts` = `MAX_REMOTE_MCP_RESPONSE_BYTES` less the JSON-RPC envelope and event-stream framing (`event: message\ndata: {"jsonrpc":"2.0","id":"paperclip-tool-<uuid>-version","result":...}`) = **999,885 bytes**. A result that Google's MCP server could deliver through the gateway is also delivered over REST, and the reverse. With the wrapper, the largest delivered result is less than 2 MB. The runner saves it as an artifact (far below 1 GiB). So the folder never refuses a result that the runner can give as a pointer. Practical limits at that budget (plain ASCII; escaped and non-ASCII characters count more): | Tool | Largest content | | --- | --- | | Gmail `get_message` | about 500 KB plain body, or about 250 KB each for plain plus HTML | | Calendar `get_event` | about 500 KB description | | Drive `read_file_content` | about 500 KB text | | Drive `download_file_content` | about 375 KB file bytes | | Docs `read_doc` | about 240 KB document text | | Slides `read_presentation` | about 250 KB text | | Sheets `get_values` | about 500 KB cell text, at most 50,000 cells | ## What Changed - `tool.ts`: `defineTool` takes `whenTooLarge` advice per read tool (required for reads, refused for writes) and a `ToolLimits` argument. It measures the final `CallToolResult` once (`withinResultBudget`) and replaces an oversized result with a `too_large` tool error. `FALLBACK_MAX_RESULT_BYTES` (250,000) applies only when a direct caller gives no limit. - `callGoogleWorkspaceRestTool` and `createGoogleWorkspaceRestServer` take `maxResultBytes`. A value that is not a positive integer is refused before any request. - All 23 read tools state their advice: a smaller `pageSize` for list tools, `messageFormat` or `view` for Gmail, a narrower range for Sheets, `fields` for Slides. Write tools are not checked: a completed write is never reported as an error, so an agent is not led to repeat it. - Drive, Docs, Slides and Sheets no longer have their own byte checks (`boundedStructuredResult`, `boundedResult`, `sizedResult`, `MAX_CONTENT_BYTES` removed). Drive downloads stop reading at the given limit. The Sheets 50,000-cell limit stays. - Two Drive tool descriptions no longer state a fixed number. - Adapter `google-workspace-rest-dispatch.ts`: `maxResultBytes` is a required input and is passed through. - `tool-gateway.ts`: new `GOOGLE_WORKSPACE_REST_MAX_RESULT_BYTES`, passed on the REST branch. - Folder README: new "Result size" section with the limits and costs; old 250,000-byte text replaced. - Docs: `doc/memory/google-connector-memory.md`, the production checklist and the code-fix plan now list #22026 to #22029, the REST status (36 of 36, none switched on), the November 17 decisions, the known differences from Google's tools, open risks and next steps. ## Verification - `cd server && npx vitest run src/google-workspace-rest-tools` passes (53 files, 1,361 tests with the adapter test). - New `result-budget.test.ts`: for Gmail (read, list), Calendar (list, read), Drive, Docs, Slides and Sheets, a result just under a given budget is returned and one just over is refused with the tool's advice. Without a budget, the fallback applies; with a larger budget, the same result is returned. Drive downloads use the given cap. A Gmail list tells the caller to lower `pageSize`. A Gmail draft result over the budget is still returned, not an error. `defineTool` refuses a read tool without advice and a write tool with it. - `npx vitest run src/services/google-workspace-rest-dispatch.test.ts`: the adapter passes the gateway's number, and the folder applies exactly that number. - `npx vitest run src/__tests__/google-workspace-rest-transport.test.ts` (24 tests): with Gmail on REST, a 330 KB email passes the gateway with screening, is more than 500,000 bytes delivered, and `captureRunnerToolResult` turns it into a `read_tool_result` pointer. A 520 KB email is refused with `tool_error` and the advice, after one Google request. - `npx tsc --noEmit -p server/tsconfig.json`: no errors. - `pnpm verify --explain`: broader verification required (a doc under `doc/` is a global CI input). CI supplies that coverage. - Time per call: the check is one `JSON.stringify` of the result. About 5 µs for a 4 KB result, 18 µs for 42 KB, 0.24 ms for 700 KB. Drive, Docs, Sheets and Slides had the same pass before, so they add nothing. Gmail and Calendar add this one pass. ## Risks - Gmail and Calendar results now have a limit. Direct callers that pass no limit get the 250,000-byte fallback. The gateway always passes its number. - Drive, Docs, Slides and Sheets accept results up to about 4 times larger than before through the gateway. Large results reach agents as artifact pointers. - Error text for oversized results changed to one shared form. - No service is switched to REST, so users see no change today. ## Model Used Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used in Claude Code with tool use (shell, file edits, GitHub CLI) and extended reasoning. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Google Workspace REST tools
Paperclip's own implementation of the tools that Google's hosted Workspace MCP
servers expose (for example https://gmailmcp.googleapis.com/mcp/v1), backed
by Google's generally available REST APIs.
It lives in this one folder, server/src/google-workspace-rest-tools/, inside
the server package. It is not a separate npm package, so nothing new is
published.
Gmail has all nine allowlisted tools: get_message, get_thread,
search_threads, list_threads, search_messages, get_draft,
list_drafts, list_labels and create_draft. Only create_draft writes.
There is no send, trash, delete or label-changing tool, and none may be added.
It also has all nine allowlisted Calendar tools (see "Calendar tools" below),
all eight allowlisted Drive tools (see "Drive tools" below), both Docs tools
and both Slides tools (see "Docs and Slides tools" below), and all six
allowlisted Sheets tools (see "Sheets tools" below).
Why this exists, and why it is temporary
Google's Workspace MCP servers are a Developer Preview and cannot be offered to the public. On 2026-11-17 the owner decided that Paperclip will launch on its own tools over the REST APIs. The tools are built so Paperclip can switch to Google's MCP servers later without a rewrite, and they live in this one folder so they can be deleted cleanly when that happens.
Boundary rules
- One entry point. Other server code may import only
index.ts. - Isolated imports, enforced by
boundary.test.ts. Source files import only files in this folder, Node built-ins,@modelcontextprotocol/sdkandzod(both existing server dependencies). Test files andfixtures/may also importvitestand@paperclipai/shared. Nothing in this folder imports other server code. The only server file that imports this folder is the gateway adapterserver/src/services/google-workspace-rest-dispatch.ts, throughindex.ts; the test checks that too. - Same tools as Google's MCP servers. Same tool names, same input fields, same result shape. Names, field names, types and enums come from Google's published reference (Gmail: https://developers.google.com/workspace/gmail/api/reference/mcp, recorded 2026-11-17). Where REST cannot match, the difference is listed below.
- Public surface is MCP only.
index.tsexports tool definitions (Tool), results (CallToolResult), an MCP server, and the MCP error thrown for token problems. No Google REST type is exported. - Knows nothing about Paperclip. No company, connection, grant, policy, audit, approval or screening code. Input is a service, a tool name, arguments and an access token. Output is an MCP result. Authorization, scope checks, approval, audit and injection screening stay with their current owners in the gateway.
- Stores nothing. No tokens, no content, no cache. The access token is used for one call and dropped.
- One file calls Google.
google-http.tsis the only place that callsgoogleapis.com. It sets the bearer header, allows only listed hosts, bounds each request (20 s deadline, 20 MB response, including the body read), maps Google errors, and retries a read (GET) once after a network error or HTTP 502/503/504. It never retries a write. A write that fails after it was sent (network error, dropped connection, timeout, caller cancellation, HTTP 5xx, or a success answer that is too large or not JSON) says that the change may or may not have been made. Every method other than GET (POST, PATCH, PUT, DELETE) is a write; the only exception is a POST the request marksreadOnly(Calendar's free/busy query).www.googleapis.comis allowed only under the prefixesGOOGLE_API_PATH_PREFIXESlists for it (/calendar/v3/,/drive/v3/,/upload/drive/v3/),docs.googleapis.comonly under/v1/documents/,slides.googleapis.comonly under/v1/presentations/,sheets.googleapis.comonly under/v4/spreadsheets/andgmail.googleapis.comonly under/gmail/v1/users/me/; every allowed host must have a prefix list (the type requires it, andgoogle-http.test.tsrequires an allowed and a rejected path for each). Paths are checked after URL normalization, so..and%2e%2esegments cannot leave them. Redirects are never followed: requests useredirect: "manual"and any 3xx is a tool error. - One tool, one file. Each tool in
gmail/,calendar/,drive/,docs/,slides/andsheets/is a set of pure functions (arguments to REST request, REST response to MCP result) plus a shortrunthat sequences them. The pure functions are unit tested without network. server.tsis thin MCP wiring:tools/listandtools/call.- The allowlist stays where it is.
toolScopesinpackages/shared/src/google-workspace-connectors.tsis the single list of allowed Google tools.allowlist.test.tsfails if this folder implements a tool that is not on it, if a tool's read-only hint disagrees with the allowlist's write flag, or if a description names a tool this folder does not list.
Errors
| Google answer | Result |
|---|---|
| 401 | Throws GoogleWorkspaceAuthError (reason: "unauthenticated", JSON-RPC data: { code: "unauthenticated", httpStatus: 401 }) |
403 with insufficient scope (ACCESS_TOKEN_SCOPE_INSUFFICIENT, insufficientPermissions, or WWW-Authenticate: error="insufficient_scope") |
Throws GoogleWorkspaceAuthError (reason: "insufficient_scope", data.code: "insufficient_scope", the value the gateway already recognizes) |
403 API not enabled (SERVICE_DISABLED, accessNotConfigured) |
Tool error result, without the project number |
403 exportSizeLimitExceeded (Drive) |
Tool error: the file is over Google's 10 MB export limit |
403 appNotAuthorizedToFile (Drive) |
Tool error saying drive.file covers only files this app created or opened, without the app's project number |
| Any 3xx redirect | Tool error; the redirect is not followed |
| Other 403, 404, 400, 429, 5xx, timeout, network failure | Tool error result (isError: true) with a short message |
| Invalid arguments | Tool error result, no request sent |
| Unknown tool | Throws McpError InvalidParams |
Token problems are thrown, not returned, so a caller can refresh the token or ask the user to reconnect exactly as it does for Google's MCP servers.
How it plugs in
The gateway calls this folder in process. There is no loopback or hosted MCP
endpoint. createGoogleWorkspaceRestServer() (a standard MCP server that reads
the token from the transport's auth info) stays available if an HTTP or stdio
deployment is ever needed; the gateway does not use it.
The switch
One setting per service, GOOGLE_WORKSPACE_TOOL_TRANSPORT in
packages/shared/src/google-workspace-connectors.ts:
google_mcp(every service today): calls go to Google's hosted MCP server for that service, exactly as before this folder existed.paperclip_rest: calls go to this folder.
googleWorkspaceToolTarget(name) returns the setting as transport. It is a
plain constant: no environment variable, instance setting or database row.
Where the gateway branches
-
Adapter.
server/src/services/google-workspace-rest-dispatch.tsis the only server file that imports this folder. It takes the gateway's resolved credential headers (it keeps only the bearer token), the call's cancellation signal, the gateway's egress-guarded fetch and the gateway's result limit (see "Result size"), and returns either the MCP result or a token problem (unauthenticatedorinsufficient_scope). -
Calls.
executeRemoteHttpTool()inserver/src/services/tool-gateway.ts. The REST branch runs after everything the MCP path runs first: the experimental-feature gate, per-caller grant selection, the allowlist and grant scope check. It then rechecks the current grant, calls the adapter with the call's deadline (and the run's stop signal when there is one), and returns through the same result handling as an MCP result. Approval, audit, invocation records and prompt-injection screening run in the callers ofexecuteRemoteHttpTool, so they apply unchanged. Token problems map to the MCP path's outcomes:insufficient_scopetooauth_insufficient_scope;unauthenticatedto a forced token refresh andoauth_refreshed_retry_required(never an automatic replay), ormcp_remote_statuswhen the connection cannot refresh. This folder turns a cancelled or timed-out request into a tool error result; the gateway checks its own signal after the call and reportstool_timeout, as on the MCP path. The audit record names the protocolGoogle Workspace REST. -
Discovery and health. The Google branch of
remoteTools()inserver/src/services/tool-access/catalog/discovery.ts. For apaperclip_restservice it runs this folder's probe (probeGoogleWorkspaceRestService) with the caller's token and granted scopes, then lists this folder's tools under the sameservice__toolnames, filtered by the granted scopes. The probe replaces Google'stools/listas the proof that the token works.GOOGLE_WORKSPACE_REST_PROBESinprobe.tsgives each service an ordered list of cheap reads, each with the scopes that allow it, and the probe uses the first one the grant allows:Service Read Allowed by Gmail users.getProfilegmail.readonlyCalendar one calendarList.listentrycalendar.calendarlist.readonly,calendar.readonlyCalendar one event of the primary calendar calendar.events.readonly,calendar.events,calendar.readonlyCalendar one minute of freeBusy.queryon the primary calendarcalendar.events.freebusyDrive about.getwithfields=kinddrive.readonly,drive.fileDocs and Slides have no probe: every read of either API needs a document or presentation ID, and Google does not document what a made-up ID returns, so a probe could wrongly mark a working grant unavailable.
Sheets has no probe: every Sheets REST read needs a spreadsheet ID, so a Sheets grant is listed without one.
A grant that allows none of them (for example compose-only Gmail) is listed without a probe. An insufficient-scope answer to a probe never makes a service unavailable. A 401 refreshes the token and probes once more; a second 401 on a managed grant marks it
needs_reauthorization, as the MCP path does. Any other probe failure makes that one service unavailable while the others stay usable. Health checks use the same branch.
MCP Tasks, MCP resources and elicitation only exist on the google_mcp path.
Measured with a stubbed fetch, the adapter adds about 15 µs per call. A full
gmail__get_message through executeTool (policy, records, screening) took a
median of 18.2 ms on either transport.
Result size
The caller sets the size limit. callGoogleWorkspaceRestTool takes
maxResultBytes, and every tool in all six services checks it the same way:
defineTool in tool.ts measures the final serialized CallToolResult once
(withinResultBudget) after the tool has built it. A result over the limit is
replaced by a tool error that gives its size and the limit, says it was not
returned, and says how to ask for less. Each tool states that advice in
whenTooLarge: a smaller pageSize for list tools, a lighter
messageFormat or view for Gmail, a narrower range for Sheets, fields for
Slides. Nothing is ever cut short. Write tools are not checked: their result
comes after the change was made, and an error then could lead the agent to
make the change twice. A write result echoes its request or Google's reply
to it, so its size follows the request. defineTool refuses a read tool without advice
and a write tool with it. Drive downloads also stop reading at the
limit, since larger content could never fit.
FALLBACK_MAX_RESULT_BYTES (250,000) in tool.ts applies only when a direct
caller passes no limit (tests, or createGoogleWorkspaceRestServer without the
option). This folder does not know Paperclip's limits.
The gateway passes GOOGLE_WORKSPACE_REST_MAX_RESULT_BYTES from
server/src/services/tool-gateway.ts: the gateway's limit on a response from a
remote MCP server (MAX_REMOTE_MCP_RESPONSE_BYTES, 1,000,000 bytes) less the
JSON-RPC and event-stream framing around the result, so 999,885 bytes. A
result Google's own MCP server could deliver through the gateway is also
delivered over REST, and the reverse. The gateway wraps the result for the
agent and repeats the payload, so the delivered result is up to twice as large
(measured 1.50 times for a plain-text email). The agent runner saves a
delivered result over 500,000 bytes as an artifact and gives the agent a
pointer it reads with read_tool_result, so a result near the limit is still
delivered in full.
Practical limits at that budget, measured with plain ASCII text (characters that JSON escapes, and non-ASCII characters, count more):
| Service | Largest content one call returns |
|---|---|
Gmail get_message |
about 500 KB of plain-text body, or about 250 KB each when the message has both plain and HTML bodies |
| Gmail lists | the whole page must fit; lower pageSize |
Calendar get_event |
about 500 KB of description |
Drive read_file_content |
about 500 KB of text |
Drive download_file_content |
about 375 KB of file bytes (base64 adds a third) |
Docs read_doc |
about 240 KB of document text (the text and the edit structure both carry it) |
Slides read_presentation |
about 250 KB of slide text; use fields for more |
Sheets get_values |
about 500 KB of cell text, and at most 50,000 cells |
The check costs one JSON.stringify of the result: about 5 µs for a 4 KB
result and 0.24 ms for a 700 KB one.
Flipping a service
- Implement every tool in that service's allowlist (
toolScopesin the shared file) in this folder, plus its probe reads and their scopes inprobe.tsand the service's API host ingoogle-http.ts. - Set the service to
paperclip_restinGOOGLE_WORKSPACE_TOOL_TRANSPORT.
googleWorkspaceRestTransportGaps() in the adapter, run by
google-workspace-rest-dispatch.test.ts, fails while any service set to
paperclip_rest is missing an allowlisted tool, so a partial flip cannot ship.
Known differences from Google's MCP tools
- Descriptions are our own wording; names, fields, types, enums, required
fields and annotations follow Google's reference. Descriptions name only
tools this folder implements (
allowlist.test.tschecks this), solist_labelspoints tolist_threadsrather than to Google's label-changing tools. A contract test against a recordedtools/listfrom Google's servers is planned once a listing is recorded on the enrolled internal account. - Result envelope. Results carry the object both as
structuredContentand as JSON text. Google's exact envelope has not been recorded yet. dateis the UTC calendar date of Gmail'sinternalDate. Google does not say which time zone it uses.senderand recipients are plain addresses parsed from the headers; display names are dropped. Bodies are decoded as UTF-8.- Same message everywhere.
get_message,get_thread,search_threads,list_threadsandsearch_messagesall map messages withtoMcpMessageingmail/message.ts, so one message looks the same from any of them at the same format.get_draftandlist_draftssharetoMcpDraft. - Large bodies. Gmail can store a body part separately and return only
its
attachmentId. Whenever bodies are returned (FULL_CONTENTforget_message,get_threadandsearch_messages;DRAFT_VIEW_FULLforget_draftandlist_drafts), the tool reads those bytes (users.messages.attachments.get, 10 at a time) before it answers. The firsttext/plainand firsttext/htmlbody parts are found depth first through nested multiparts. If any body part cannot be read, the whole call returns a tool error that starts with "Could not read the full body of this message"; it never returns a result, or a page, with a body missing. One call reads at most 20 such bodies (see "Google requests per call"). Google's reference does not say what its tools do here. - Addresses come from
gmail/address.ts, a small single-pass tokenizer over RFC 5322 address lists. It tracks quoted strings with escapes, nested comments, angle brackets and square-bracket domain literals (soops@[IPv6:2001:db8::1]stays whole), drops comments and display names, returns the members of groups without the group name, and returns nothing for an empty group such asundisclosed-recipients:;. Malformed input gives a best-effort list and never throws. Google's reference does not say how its tools parse these headers. labelIdskeeps user labels and the system labels Google lists (INBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, SENT, DRAFT, CHAT); category labels are dropped.label:in search queries. Google'ssearch_threadsreference says its query accepts label IDs, not display names. Gmail search (theqparameter that REST passes to Gmail) uses label names, with spaces written as hyphens, as in Gmail's own search operators (label:friends). REST parameters namedlabelIdstake IDs. Our query descriptions describe the REST behavior, andallowlist.test.tschecks that no description sayslabel:takes IDs.search_threadsmakes onethreads.listcall and then onethreads.getper thread (10 at a time), so a 50-thread page is 51 requests. A thread deleted between the two calls is left out.pageSizeabove 50 is capped at 50. Drafts are excluded by adding-in:draftunless the query itself usesin:draft,is:draftorin:anywhereoutside quoted text;includeTrashusesincludeSpamTrashplus-in:spam, with the same rule forin:spam. When terms are added, the caller's query is wrapped in parentheses first. Google's reference documents the default exclusions but not how its tool applies them.create_draft: for a reply, the draft is threaded (threadId,In-Reply-To,References) and an empty subject becomesRe: <original>, but the original message is not quoted under the new body as Google's tool does, and recipients are not filled in from the original: passto. The result is built from the request and Google'sdrafts.createanswer, without a second read;dateis the creation date (UTC). Attachments are refused, as Google's tool currently does. Long subjects and recipient lists are folded onto continuation lines (RFC 5322); non-ASCII subjects and single words longer than 900 characters become RFC 2047 encoded-words. Google's reference sets no length limits.get_threadmakes onethreads.getcall (format=full, or summary headers only forMINIMALandMETADATA_ONLY), then reads separately stored bodies. Messages keep Gmail's order, oldest first.list_draftsmakes onedrafts.listcall and then onedrafts.getper draft (10 at a time). A draft deleted between the two calls is left out. The query is passed to Gmail unchanged.pageSizeabove 50 is capped at 50. Google's annotationidempotentHint: falseis copied as published.list_labelsmakes onelabels.listcall. Gmail's REST list has no paging, sopageSize(default 100, maximum 500, neither set by Google) andpageToken(a position in the list sorted by name, then ID) are applied in this folder.threadsTotalandthreadsUnreadare left out: REST returns them only fromlabels.get, one request per label. A label with only one of its two colors set is returned withoutcolor.- Errors for Google failures are tool error results with our own short messages, not Google's raw error text (except for 400 and 403 messages, trimmed to one line).
Google requests per call
Reads that fan out run at most 10 at a time; the first failure stops new
requests. The 20 s timeout in google-http.ts applies to each request
attempt, not to the whole call, so a call that fans out can take longer than
20 s. Every request also stops when the caller's signal aborts; a caller
that needs a bound on the whole call passes a signal with that deadline (the
gateway passes its call deadline).
Each read may be retried once by google-http.ts, which the counts below do
not include. "Bodies" are separately stored bodies (at most two per message,
plain and HTML, and none for most mail). One call reads at most 20 of them
(MAX_SEPARATE_BODIES_PER_CALL in gmail/message.ts). When the messages in a
call need more, the call reads none and returns a tool error that starts with
"Could not read the full body of every message" and says to ask for fewer
results or to use get_message.
Quota units come from Gmail's published per-method costs
(https://developers.google.com/workspace/gmail/api/reference/quota, recorded
2026-11-17): messages.get and drafts.get 20 (60 with format=full),
threads.get 40 (120 with format=full), messages.attachments.get 20,
threads.list 10, messages.list and drafts.list 5, labels.list 1,
drafts.create 10. Gmail allows 6,000 units per user per minute.
| Tool | Requests at the maximum page size | Worst-case quota units |
|---|---|---|
get_message |
1 + up to 2 bodies = 3 | 60 + 40 = 100 |
get_thread |
1 + up to 20 bodies = 21 | 120 + 400 = 520 |
search_threads |
1 + 50 = 51 | 10 + 50 × 40 = 2,010 |
list_threads |
1 + 50 = 51 | 2,010 |
search_messages |
51; with FULL_CONTENT 1 + 50 + 20 = 71 |
1,005; with FULL_CONTENT 5 + 50 × 60 + 400 = 3,405 |
get_draft |
1 + up to 2 bodies = 3 | 60 + 40 = 100 |
list_drafts |
51; with DRAFT_VIEW_FULL (the default) 71 |
1,005; with DRAFT_VIEW_FULL 3,405 |
list_labels |
1 | 1 |
create_draft |
1, or 2 for a reply | 10, or 30 for a reply |
The worst single call (3,405 units) fits inside the 6,000-unit per-user
minute. At the default page size of 20 the worst is 1,605 units. Concurrency
does not change the total: the 10 parallel reads only spread one call's fixed
units over less time. A second maximal call in the same minute can exceed the
per-user quota; Google then answers 429, which becomes the rate_limited tool
error ("Google is rate limiting requests. Try again shortly."). Gmail's quota
page states no per-user concurrency limit.
Not verified against Google's servers
The allowlist in toolScopes names get_draft, list_threads and
search_messages, but Google's published Gmail MCP reference does not list
them (it lists create_draft, get_message, get_thread, label_message,
label_thread, list_drafts, list_labels, search_threads,
unlabel_message and unlabel_thread). Their inputs and results are our
design, built from the documented sibling tools, and may not match what
Google's servers return if they ever expose tools with these names:
get_draft: inputdraftId(required) andview(DraftViewfromlist_drafts); result is oneDraft, the shapelist_draftsandcreate_draftreturn. Onedrafts.get, plus bodies.list_threads: inputpageSize,pageToken,includeTrashandviewas insearch_threads, pluslabelIds(at most 20; a thread must have all of them) instead ofquery; result issearch_threads's. Drafts are excluded unlessDRAFTis among the labels; spam and trash are included whenSPAMorTRASHis among them.search_messages: input assearch_threads, withmessageFormatfromget_messageinstead ofview; result is{ messages, nextPageToken, resultCountEstimate }withget_message'sMessage. Unlikeget_message, the default (andMESSAGE_FORMAT_UNSPECIFIED) isMINIMAL, so a search does not pull every body. Onemessages.list, then onemessages.getper message, plus bodies withFULL_CONTENT.
A switch back to google_mcp would drop these three unless Google adds them.
To check when a live tester exists: record read_doc and read_presentation
answers from Google's Docs and Slides MCP servers for a test document and
deck, and compare their content with ours. Google publishes only that
content is an object; our text form and structure are unverified against
Google's server.
Calendar tools
Names, input fields, enums, result shapes and annotations come from Google's
Calendar MCP reference
(https://developers.google.com/workspace/calendar/api/v3/reference/mcp,
recorded 2026-11-17). All calls go to the Calendar REST API v3 at
https://www.googleapis.com/calendar/v3/. Scopes below are the narrowest
one each REST call accepts among those toolScopes.calendar allows.
| Tool | REST calls | Works with |
|---|---|---|
list_calendars |
calendarList.list |
calendar.calendarlist.readonly |
get_event |
events.get |
calendar.events.readonly or calendar.events |
list_events |
events.list (plus a one-field events.list for the calendar's time zone when a time has no offset and no timeZone is given) |
calendar.events.readonly or calendar.events |
search_events |
events.list with q on primary |
calendar.events.readonly or calendar.events |
suggest_time |
freeBusy.query; without the free/busy permission, events.list on each attendee's calendar; a one-field events.list on primary for the time zone when none is given |
calendar.events.freebusy, or calendar.events.readonly / calendar.events with the fallback |
create_event |
events.insert (plus the time zone read for a timed event without timeZone) |
calendar.events |
update_event |
events.get, then events.patch with If-Match |
calendar.events |
delete_event |
events.get, then events.delete |
calendar.events |
respond_to_event |
events.get, then events.patch of attendees with If-Match |
calendar.events |
events.list and events.get accept calendar.events.freebusy,
calendar.events.readonly and calendar.events, so the time zone read works
for every grant. freeBusy.query does not accept calendar.events, which is
why suggest_time has a fallback (see open questions). Google's reference
for freeBusy.query
(https://developers.google.com/workspace/calendar/api/v3/reference/freebusy/query,
recorded 2026-11-17) says: "This request allows authorization with at least
one of the following scopes:" and lists only
https://www.googleapis.com/auth/calendar.readonly,
https://www.googleapis.com/auth/calendar,
https://www.googleapis.com/auth/calendar.events.freebusy and
https://www.googleapis.com/auth/calendar.freebusy.
Time handling
- Times without an offset are read in
timeZonewhen given, otherwise in the event's own time zone (update_event), otherwise in the calendar's time zone read from Google. A time zone is never guessed, and the server's own zone is never used. Unknown or non-IANA names (including+05:00) are refused. - A stated offset (
Z,-07:00) is always used as given. - A local time that does not exist (DST spring forward) moves forward by the
gap; a repeated local time (DST fall back) takes the first occurrence. This
is the same rule as JavaScript Temporal's
compatible. - Timed events are sent as
dateTimewith an explicit offset plustimeZone, so Google never has to resolve a local time. Arithmetic usesIntlonly; no date library. - All-day events (
allDay: true) use only the dates. The end is exclusive, as in Google Calendar: an end on the start date, or an end at midnight, means through the day before; an end later in a day includes that day. list_eventsdefaults to now through 7 local days later (7 × 24 hours when no time zone was needed). Recurring events are expanded into occurrences (singleEvents=true).update_event: changing only the start keeps the elapsed duration; changing onlytimeZonekeeps the same moment and shows it in the new zone; changing only the start of an all-day event keeps its number of days.
Notifications
Write tools follow the defaults Google's MCP reference documents:
create_event, update_event and delete_event default to ALL (Google
emails every attendee); respond_to_event defaults to EXTERNAL_ONLY.
NOTIFICATION_LEVEL_UNSPECIFIED means the same default. NONE,
EXTERNAL_ONLY and ALL map to REST sendUpdates=none|externalOnly|all,
and sendUpdates is always sent explicitly. Each tool description says what
its default sends.
How suggest_time works
- Resolve the time zone (see above) and the range; at most 62 days.
- Read busy times for every attendee with one
freeBusy.query(a read, so it may be retried once). If Google answers that the grant lacks the free/busy permission, read each attendee's calendar withevents.listinstead, counting events that are not cancelled, not marked free, and not declined by the calendar's owner; all-day events count from midnight to midnight in that calendar's zone. - If any attendee's availability cannot be read (free/busy errors, not shared, not found), return an error naming them. It never suggests a time from partial data.
- Merge all busy times, take the free gaps inside the range, and intersect
them with the allowed daily windows:
startHourtoendHourlocal time (default the whole day;24:00means midnight), skipping Saturdays and Sundays whenexcludeWeekendsis set.endHourmust be later thanstartHour; overnight windows are not supported. - Return free periods at least
durationMinuteslong (default 30), earliest first, at mostpreferences.pageSize(default 5, at most 50). Each slot is a whole free period, not split into meeting-length pieces, and itsstart/endare in the resolved zone.
Limits: attendees whose calendars are not shared with the user at all make the call fail rather than be ignored; there is no ranking by preference beyond earliest first; working hours and out-of-office settings are not read.
Differences from Google's Calendar MCP tools
update_eventis annotateddestructiveHint: true(deliberate). It overwrites fields, can remove attendees and replaces reminders, so approval and confirmation in Paperclip must treat it as destructive. Google's reference marks it non-destructive. It staysidempotentHint: true: the same patch applied twice leaves the event the same.respond_to_eventstays non-destructive (it changes only the user's own response).allowlist.test.tschecks the write tools' annotations.- Time zone when none is given. Google says its server resolves the
user's time zone. Here it is the target calendar's time zone (the primary
calendar for
suggest_time), read fromevents.list, since the user settings API needs a scope outside the allowlist. search_eventsis keyword search (RESTq: title, description, location, attendees, organizer, every term must match) on the primary calendar across all dates, not semantic search. A recurring series is returned once, as the series. Default page size 25.list_eventsorderBy: startTimeDesc. REST only sorts ascending, so this reads every matching page (up to 2,000 events; more is an error asking for a narrower range), reverses it, and pages by offset.list_eventspage tokens are ours (pc1.plus base64url JSON). They carry the first page's resolved time range, so later pages use the same range even when it defaulted to "now", plus Google's page token or the newest-first offset. A token from another order, or a raw Google token, is refused.create_eventdoes not add the signed-in user as an attendee when others are invited (Google's tool does on the primary calendar); learning the user's address needs a scope outside the allowlist.delete_eventrefuses a whole recurring series (deliberate). RESTevents.deleteand Google's tool delete the whole series when given the series' ID. Here, if the event read before deletion hasrecurrenceand norecurringEventId, the tool returns an error asking for one occurrence's ID (fromlist_events) and sends no delete. The person approving the call sees only an event ID, and a whole series is a much larger change than it looks. Single events and single occurrences are deleted as usual, one ID per call, and the result is the event as read before deleting, withstatus: cancelled.update_eventandrespond_to_eventon a recurring event. A series' ID changes (or responds for) the whole series; one occurrence's ID changes only that occurrence. Both descriptions say so, and the result shows which: a series hasrecurrenceand norecurringEventId; an occurrence hasrecurringEventId.update_eventandrespond_to_eventread the event first and patch withIf-Match. If the event changed in between, nothing is changed and the tool says so.update_eventwith no changes returns the event without writing.respond_to_eventneeds the user to be an attendee on that calendar's copy (self: true); otherwise it refuses without writing.googleMeetUrlaccepts onlyhttps://meet.google.com/xxx-xxxx-xxxlinks or bare meeting IDs.- Event results omit
labelandtaskId(not in REST).availabilitycomes from RESTtransparency;conferenceUrlfromhangoutLinkor the video entry point.
Drive tools
Names, input fields, result shapes and annotations come from Google's Drive
MCP reference
(https://developers.google.com/workspace/drive/api/reference/mcp, recorded
2026-11-17) and the tools/list of Google's hosted Drive MCP server on the
same date, which adds snippetVerbosity, includeRichMetadata,
revisionId, pregeneratedId and inheritedPermissionsDisabled to the
published pages. All calls go to the Drive REST API v3 at
https://www.googleapis.com/drive/v3/ (uploads at
https://www.googleapis.com/upload/drive/v3/). The allowlist gives the six
reads drive.readonly and the two writes drive.file. Each REST method below
accepts that scope according to its reference page (recorded 2026-11-17), so
no broader scope is needed or requested.
What drive.file allows
files.copy accepts only drive, drive.appdata, drive.file and
drive.photos.readonly; drive.readonly cannot copy. Google's scope guide
(https://developers.google.com/workspace/drive/api/guides/api-specific-auth)
says drive.file covers files "that you open with an app or that the user
shares with an app". So with drive.file:
create_filecreates new files and folders in My Drive, and in folders this app created or was given.copy_filecopies files this app created or was given. Whether Google also lets it copy a file the same token can only read throughdrive.readonlyis not documented and has not been tried against Google (see open questions). When Google refuses, the tool error says thatdrive.filecovers only files this app created or opened, and that nothing was created. The same applies to aparentIdthe app cannot use.- Neither tool changes, moves, shares, trashes or deletes an existing file, and no tool in this folder does.
Content
| File | read_file_content |
download_file_content default |
|---|---|---|
| Google Doc | files.export as text/markdown |
text/plain |
| Google Sheet | text/csv of the first sheet, after a line saying only the first sheet is shown |
text/csv, first sheet only (the description says so and names the XLSX type for every sheet) |
| Google Slides | text/plain |
text/plain |
| Google Drawing | not supported | image/svg+xml |
| Apps Script | not supported | application/vnd.google-apps.script+json |
| Other Google types (folder, form, site, shortcut) | not supported | tool error |
text/*, JSON, XML, YAML, +json and +xml types |
the stored bytes as UTF-8 | the stored bytes |
| Anything else (PDF, Office, images, video) | not supported | the stored bytes |
exportMimeType picks the export format for Google files and is ignored for
other files, as in Google's reference. It must be one of the formats Google's
export table lists for that file type (EXPORT_FORMATS in
drive/content.ts, from
https://developers.google.com/workspace/drive/api/guides/ref-export-formats);
anything else is refused before a request is sent. Every request uses the
fileId the caller passed, never an ID taken from Google's answer. download_file_content returns
{ id, title, mimeType, content }: content is base64 and mimeType is the
type of the returned bytes (the export format for Google files).
"Not supported" means fileContent: "" with textFormattingNotSupported: true, the field Google's result has for this case. Text that is not valid
UTF-8 is also not supported.
Size cap. Every Drive tool is bound by the caller's result limit (see
"Result size"). The result carries the payload twice, as structuredContent
and as its JSON text. Content is also never read past the limit, since more
could never fit: a stored file whose metadata size is larger is refused before
any download, and exports and revisions are read through
GoogleHttp.download, which stops at the limit. Both
limits are far under Google's 10 MB export limit
(https://developers.google.com/workspace/drive/api/reference/rest/v3/files/export)
and the 20 MB MAX_RESPONSE_BYTES. A refused result is an error that says
nothing was returned and how to ask for less (a smaller pageSize, no
includeRichMetadata or includeComments, another export format, or
read_file_content for a Google file's text). It never returns cut-short
content. Google's exportSizeLimitExceeded answer gives a similar error. create_file
uploads at most 5 MB, the limit for one multipart upload.
Redirects. files.export and alt=media downloads are answered by
www.googleapis.com itself. google-http.ts never follows a redirect (it
sends redirect: "manual", and the gateway's guarded fetch never follows
one either), so a download Google redirects elsewhere is a tool error, not a
request to a host outside the allowlist.
Search
search_files takes Google's MCP query language (title contains 'x' and modifiedTime > '...'). drive/query.ts tokenizes and parses it into a tree,
checks each term and operator against the list Google publishes, and writes a
new Drive q string from the tree. Values are always re-quoted with ' and
\ escaped, so text inside a value can never become an operator; tests cover
quote, backslash and parenthesis injection. Mapping: title → name;
parentId = 'x' → 'x' in parents; owner = 'x' → 'x' in owners; != on
those → not ...; visibility = 'anyone' or 'domain' → both of Drive's
...CanFind and ...WithLink values; other terms pass through. creator,
sharedFrom, sharedTo, followUp, folderProperties and
visibility = 'external' have no Drive q equivalent and are refused with an
error rather than ignored. Unless the query uses trashed,
and trashed = false is added, as Google's tool does.
Drive's name contains is a prefix match ("HelloWorld" matches 'Hello', not
'World'), so title contains is too; the query help says so and suggests
fullText contains for a word inside a title. When Google answers
incompleteSearch: true (it could not search every corpus), both list tools
return incompleteSearch: true so an agent does not take a short list as
proof that a file does not exist. Google's MCP result has no such field.
Google requests per call
search_files, list_recent_files and get_file_metadata: 1.
get_file_permissions: 1 per 100 permissions, at most 10 (more is an error).
download_file_content: 2 (1 when the stored size is over the cap).
read_file_content: 1 for unsupported types, otherwise 2, plus 1 per 100
comment threads with includeComments, at most 10 (more is an error, never a
partial list). create_file and copy_file: 1. Page size for search_files
and list_recent_files: default 10, at most 100 (Drive allows 1,000). Reads
may be retried once by google-http.ts. Writes never are, and any failure
after a write was sent says it may or may not have happened.
Differences from Google's Drive MCP tools
- No content snippets. REST has no generated snippet, so
contentSnippetis never returned.excludeContentSnippetsandsnippetVerbosityare accepted (and still may not both be set) but change nothing. - Rich metadata.
includeRichMetadataaddsownerName,lastModifyingUserName,lastModifyingUserEmailandvisibility.visibilitycomes from the file'sanyoneanddomainpermissions and is absent when Google does not show the user the file's sharing.lastCommentedTimeis not returned; REST has no such field. - Text, not extraction. Google's
read_file_contentalso reads PDFs, Office files, images and video transcripts. REST can only do that by converting the file into a new Google file, which is a write, so those types returntextFormattingNotSupported: true. - Spreadsheets read as CSV of the first sheet only, since Drive's text exports of a spreadsheet hold only the first sheet. Every sheet needs the Sheets API.
- Comments are listed in
unanchoredCommentsand never placed in the text, socontentAnchoredCommentsis always empty; REST anchors are opaque. revisionIdworks only for files that are not Google files.list_recent_filesorderBymaps to Drive'srecency desc,modifiedTime descandmodifiedByMeTime desc; other values fall back to recency, as Google documents.search_filesorderByacceptsmodifiedTimeandviewedByMeTime, withascordesc; anything else is an error. Without it, Drive's own order is used, which may differ from Google's relevance order.- Shared drives. Lists include shared-drive items the user can see
(
includeItemsFromAllDrives), within Drive's defaultusercorpus. create_fileconversion uses a fixed table (text, Markdown, HTML, RTF, Word and OpenDocument text to Docs; CSV, TSV, Excel and OpenDocument sheets to Sheets; PowerPoint and OpenDocument presentations to Slides) instead of reading Drive'simportFormats. Without content, only Docs, Sheets, Slides and folders can be created.copy_filesends no name or folder unless given, so the copy's default name and folder are the REST defaults. Folders cannot be copied.pregeneratedIdis passed to Drive as the new file'sid. This folder has no tool that generates IDs.
Docs and Slides tools
Names and input fields come from Google's MCP references
(https://developers.google.com/workspace/docs/api/reference/mcp/tools_list/read_doc,
.../update_doc,
https://developers.google.com/workspace/slides/api/reference/mcp/tools_list/read_presentation
and .../update_presentation, recorded 2026-11-17). Annotations follow them
except destructiveHint on update_doc (see the differences below). Each
tool makes one REST call; read_doc makes a second only when Google refuses
the first for the user's access (see "Suggestions and comments").
| Tool | REST call | Works with | Google documentation |
|---|---|---|---|
read_doc |
documents.get with includeTabsContent=true and an explicit suggestionsViewMode |
documents.readonly or documents |
https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/get |
update_doc |
documents.batchUpdate |
documents |
https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/batchUpdate |
read_presentation |
presentations.get |
presentations.readonly or presentations |
https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations/get |
update_presentation |
presentations.batchUpdate |
presentations |
https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations/batchUpdate |
What the read tools return
Google documents both results only as { content: object }, "a JSON
representation" of the file, and does not say what is inside. Here content
holds:
text: the whole file as Markdown-style text. Docs: every tab (child tabs included, each under=== Tab: Parent / Child ===when there is more than one), headings as#, list items with their real numbering (1.,a.,iv., nested formats such as1.2., start numbers, numbering that continues across interrupting paragraphs), tables as| cells |with nested tables flattened into one cell, merged table cells placed on the full grid (every row has the table's column count; cells covered by a merge read(merged left)or(merged up), never a blank), links as[text](url)(heading, bookmark and tab links as#heading=…,#bookmark=…,#tab=…), footnote references as[^n]with the footnotes after the body, headers and footers labelled default, first page or even pages, person and date chips, rich links, page and column breaks, and, in theSUGGESTIONS_INLINEview only, pending suggestions as{+inserted+}and{-deleted-}. Slides: each slide as## Slide n(marked skipped when it is), title placeholders as###, bullets with their own glyph, tables, groups, word art, and each slide's speaker notes underSpeaker notes:.- A structure for edits. Docs:
tabs[]with every paragraph's and table cell'sstartIndex,endIndex, named style and list, plus headers, footers and footnotes by segment ID. A paragraph'stextis exact: each non-text index (an image, a footnote reference, a chip) is one U+FFFC, sotext.lengthequalsendIndex - startIndex. Slides:slides[]with each page element'sobjectId, type, placeholder and raw text, table cells by row and column (Slides tables are placed on the grid by each cell'slocationand spans, sincetableCellsleaves out covered cells), and the speaker notes shape'sobjectId. revisionId, which the update tools require.notes: what could not be shown as text, with a count, and for Docs always which suggestions view was used.- Docs:
suggestionsViewMode, the view the document was read in. - With
commentsIncluded, a[Comments]section (commentsViewModeon both APIs).
Suggestions and comments
read_doc always asks for suggestionsViewMode=SUGGESTIONS_INLINE, so
pending suggested edits are shown and the indices are the ones
documents.batchUpdate needs (the Document reference: "When editing a
document, changes must be based on a document with SUGGESTIONS_INLINE").
Google answers 403 to that view when the user may not see suggestions; without
an explicit view a viewer would silently get PREVIEW_WITHOUT_SUGGESTIONS.
On a 403 permission answer the tool reads again with
PREVIEW_WITHOUT_SUGGESTIONS (without comments, which Google returns only
with inline suggestions). That result says, in suggestionsViewMode and
notes, that pending suggestions are not shown and that its indices may not
be valid for update_doc; if comments were asked for, [Comments] and
notes say they are not available with the user's access. Any other failure
(not found, API disabled, a missing Docs permission on the grant) is returned
as is, without a second read. A document that is readable is never turned
into an error by these options.
read_presentation with commentsIncluded asks for
commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED. If Google refuses that with a
permission error, the tool reads only the presentation's ID to check that the
presentation itself is readable; if it is, it returns an error saying comments
are not available with the user's access and that it can be read without
commentsIncluded. If not, Google's own error is returned.
read_presentation with fields returns Google's resource limited to those
fields, unchanged, as Google's tool does.
What cannot be represented, and is listed in notes when present: pictures
(shown as [image: title or alt text]), drawings, charts, equations (the Docs
API does not return their content), dropdown values, Slides videos (shown with
their link), and text that slide masters and layouts put on every slide.
Formatting other than headings, lists and links (bold, colors, fonts, sizes)
is not in text. Checklist items render as plain list items: the Docs API
does not say whether a box is ticked.
A result over the caller's limit (see "Result size") is refused with an error
that gives the size and returns nothing; it is never cut short. The final
serialized MCP result carries the content twice (as JSON text and as
structured content), and read_doc also repeats each paragraph's text in its
edit structure. To read a
large presentation in parts, pass fields, for example
["slides(objectId,pageElements(objectId,shape.text))"]. read_doc has no
way to read part of a document, since Google's tool has no such input and
documents.get cannot select one tab; a document whose result would be over
the limit cannot be read through this tool.
How the update tools work
Google's tools take documents.batchUpdate and presentations.batchUpdate
requests as they are, so these do too: the requests are posted unchanged and
in the caller's order, in one call. Google applies them in order and all or
none; each request sees the file as changed by those before it. Reordering
them here would change what dependent requests (insert, then style the
inserted text) do, so nothing is reordered. The descriptions tell callers to
order several index-based edits from one read from the highest index to the
lowest; the tests show that order gives the intended result and the reverse
does not.
writeControl.requiredRevisionId is required (Google makes it optional). It
is the revisionId from the read tool. If the file changed since, Google
rejects the whole batch and the tool answers that the file is no longer at
the revision you read, nothing was changed, and to read it again. A rejection
counts as a conflict when Google's structured error.status is
FAILED_PRECONDITION or ABORTED, or a reason in error.details names a
revision or an unmet condition; only when neither field says so does the
message decide ("required revision", "revision ID" or "latest revision").
Any other 400 returns Google's own message.
targetRevisionId (Docs), which would apply the edit to a newer version, is
refused. The answer includes the new revision in writeControl, also for
Slides (Google's Slides tool lists only replies). A write is never retried;
a failure after it was sent carries the uncertain-outcome warning.
Each request must name exactly one request kind; at most 500 per call.
The requests can delete or replace content in the one file the call names:
text (deleteContentRange, deleteText, replaceAllText), tabs
(deleteTab) and slides or page elements (deleteObject), as in Google's
tools. Both update descriptions say so. The tools cannot create, delete, move,
copy or share files, and there is no tool that can.
Allowed request kinds
Each update tool accepts only the request kinds in a closed list:
DOCS_REQUEST_KINDS in docs/request-kinds.ts and SLIDES_REQUEST_KINDS in
slides/request-kinds.ts, built from Google's REST request references
(https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/request,
https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations/request,
recorded 2026-11-17). A kind is allowed only when it acts within the one file
being edited. Any kind not on the list, including one Google adds later, is
refused with an error that names it, and nothing is sent. The same table
builds the lists in the tool descriptions and drives the tests, and a test
checks it covers every kind in Google's reference.
Docs: every kind in Google's documents.batchUpdate reference and in its
update_doc MCP reference is listed. All are allowed except insertRichLink
(refused); insertInlineImage and replaceImage are allowed only in the
restricted form below.
Slides: every kind in Google's presentations.batchUpdate reference and in
its update_presentation MCP reference (which adds importSlides,
createAudio and updateAudioProperties) is listed. All are allowed except
createSheetsChart, replaceAllShapesWithSheetsChart, refreshSheetsChart,
importSlides and createAudio (refused); createVideo, createImage,
replaceImage, replaceAllShapesWithImage and updatePageProperties are
allowed only in the restricted forms below. No other kind can link content
from another file: linked charts come only from the refused Sheets chart
kinds, and linked slides only from the refused importSlides.
The tests keep Google's full lists and check that each kind is classified explicitly; only a kind on neither list falls through to "not a request kind this tool accepts".
Refused, because they read another file:
| Tool | Kind | Reason |
|---|---|---|
update_doc |
insertRichLink |
A smart chip that points to another file and shows its title. |
update_presentation |
createSheetsChart, replaceAllShapesWithSheetsChart, refreshSheetsChart |
Read a chart from a Google Sheets spreadsheet. |
update_presentation |
importSlides |
Copies slides from another presentation (in Google's MCP tool list, not in REST). |
update_presentation |
createAudio |
Inserts an audio file from Google Drive (in Google's MCP tool list, not in REST). |
Refused forms of allowed kinds: createVideo is accepted only with
source: "YOUTUBE" (a DRIVE video is another file). Image kinds
(insertInlineImage and replaceImage in Docs; createImage, replaceImage,
replaceAllShapesWithImage and a stretchedPictureFill.contentUrl page
background in Slides) are allowed with a public image link, since Google
fetches it without the user's data, but refused when the link is on
drive.google.com or docs.google.com, which names another file. Links in
text styles stay allowed: they only point somewhere and read nothing.
This is a deliberate difference from Google's tools, which accept every request kind.
Both update tools are annotated destructiveHint: true and
idempotentHint: false, because a batch can delete or overwrite content and
repeating it repeats the edit. Google marks update_doc non-destructive; this
is a deliberate difference so that approval and confirmation in Paperclip
match what the tool can do. allowlist.test.ts checks all four tools'
annotations.
Differences from Google's Docs and Slides MCP tools
contentis the text form and structure above, not the raw REST resource (exceptread_presentationwithfields). Google does not publish the inner format ofcontent, and ours has not been compared with an answer from Google's server (see "Not verified against Google's servers").requiredRevisionIdis required andtargetRevisionIdis refused.update_docis annotated destructive (Google: not destructive).read_docalways setssuggestionsViewModeand falls back toPREVIEW_WITHOUT_SUGGESTIONSfor users who may not see suggestions.- Both update tools accept only a closed list of request kinds and refuse kinds and forms that read another file (see "Allowed request kinds").
- At least one request is required.
- Descriptions are our own wording. The
documentIddescription does not name Drive's file ID field.
Sheets tools
Names, input fields, result shapes and annotations come from Google's Sheets
MCP reference
(https://developers.google.com/workspace/sheets/api/reference/mcp, recorded
2026-11-17). All calls go to the Sheets REST API v4 at
https://sheets.googleapis.com/v4/spreadsheets/; google-http.ts allows that
host only under that path, checked after URL normalization. Each tool works
with exactly the scopes toolScopes.sheets allows.
Every tool makes exactly one Google request. Writes are never retried; a write that fails after it was sent carries the usual "may or may not have been made" warning.
Values
get_valuesreturns formatted values, as Google Sheets displays them (valueRenderOption=FORMATTED_VALUE,majorDimension=ROWS, both sent explicitly; these are the REST defaults, and Google's tool exposes no render option). Numbers, currency, percentages and dates come back as the displayed text ("$1,200.50","12%","1/5/2026"), booleans as"TRUE"/"FALSE", errors as their text ("#DIV/0!"), and formula cells as their result. Google's answer is returned unchanged: trailing empty rows and columns are left out, so rows can differ in length; an empty range has novaluesfield; in a merged area only the top-left cell holds the value. One range per call, as in Google's tool (novalues.batchGet).- Unformatted values, formulas and several ranges come from
get_spreadsheetwithrangesandincludeGridData: each cell hasuserEnteredValue(including the formula),effectiveValue(dates and times as serial numbers, days since 1899-12-30) andformattedValue; merged areas are listed inmerges. The Spreadsheet resource is returned unchanged undercontent.fieldstakes Google's field-mask syntax, including groups such assheets.properties(sheetId,title); a mask with any character other than letters, digits,_ . , ( ) / *, or with unbalanced parentheses, is refused before sending. update_valueswrites raw values (RAW): strings are stored as given, so"=A1","2026-01-05"and"1,000"stay text. Google's reference does not name the option; RAW is our reading of it, because Google ships a separateupdate_formulastool.update_formulasusesUSER_ENTERED, so a string starting with=becomes a formula and other text may be parsed by the spreadsheet's locale. Both take strings, finite numbers, booleans andnull(skip the cell);""clears a cell; anything else is refused before sending.- Ranges are checked before sending (
sheets/range.ts): A1 (A1,A1:C10,A:C,2:5,A2:C,$A$1) or R1C1 (R1C1:R10C3), with an optional sheet name. A sheet name with anything other than letters, digits and_must be in single quotes with apostrophes doubled ('Q1 Plan'!A1,'Bob''s list'!A:A); an unquoted one is refused with that hint. A bare name is a sheet or named range. Columns are limited toZZZand rows to 10,000,000.
Bounds
- At most 50,000 cells per call, read or written (
MAX_CELLS_PER_CALL). Reads count the cells Google returns (valuesrows, orrowDatavalues in grid data); writes count the cells sent (values/formulas, or the rows ofupdateCellsandappendCells). - A tool's whole result is bound by the caller's limit (see "Result size"),
measured on this folder's own result, which carries the value twice (as
structuredContentand as JSON text, since MCP clients read either). A write request body is at most 1,000,000 characters. - Over a limit, a read returns an error that starts with the size and asks for
a narrower range, fewer or narrower
ranges, or fewerfields, to read in smaller pieces; a write sends nothing. Nothing is ever cut short and presented as complete. A Google answer over the 20 MB transport limit gets the same narrowing message. - Server-side operations in
update_spreadsheet(for examplerepeatCell,sortRange,findReplace,copyPaste) are bounded by Google, not here.
Write results
Write results are Google's REST response under content, plus status, a
sentence naming what changed. Google says its result has a status field but
not what it holds.
update_values/update_formulas:Updated 4 cells in 'Q1 Plan'!A1:B2 (2 rows × 2 columns) as raw values., from Google'supdatedRangeandupdatedCells.insert_dimension: the inserted rows or columns, 1-based (sheet ID 0, rows 6–8), and that no values were written.update_spreadsheet: each request in order with the range it touched (1. deleteDimension on sheet ID 0, columns B–C), and the cells written byupdateCells/appendCells. Where each request type keeps its range (for exampleaddNamedRange.namedRange.range) is listed once inREQUEST_TARGETS; a test fails if a supported type has no entry.
update_spreadsheet operations
Google's reference lists 74 request types. 64 are accepted, each request must have exactly one of them, and anything else is refused before sending. Refused:
- Comments (
insertComment,addCommentReply,updateCommentPost,deleteComment,deleteCommentReply): not part of the Sheets REST API. - Data sources (
addDataSource,updateDataSource,deleteDataSource,refreshDataSource,cancelDataSourceRefresh): they need a BigQuery scope outside the allowlist, and Google's insufficient-scope answer would wrongly ask the user to reconnect.
Google's documented list includes operations that remove content, and they
are accepted as documented: deleteSheet, deleteDimension, deleteRange,
deleteDuplicates, deleteTable, deleteNamedRange, deleteEmbeddedObject,
deleteFilterView, deleteConditionalFormatRule, deleteProtectedRange,
deleteBanding, deleteDeveloperMetadata, deleteDimensionGroup and
clearBasicFilter; cutPaste, findReplace, sortRange, pasteData,
trimWhitespace and randomizeRange change existing cells. No operation
deletes or creates a spreadsheet or changes its sharing. Because of these,
update_spreadsheet says destructiveHint: true, where Google's reference
says false.
Differences from Google's Sheets MCP tools
get_spreadsheetcommentsIncluded: trueis refused.spreadsheets.getcannot return comments (they are in the Drive API, outside the Sheets scopes).falseor unset works.update_spreadsheetwriteControlis refused. Sheetsspreadsheets.batchUpdatehas no required-revision check, so a write cannot be made conditional; anywriteControlis an error rather than ignored.update_spreadsheetrefuses comment and data source requests (above) and is marked destructive.insert_dimensionrefusesDIMENSION_UNSPECIFIED(Google says not to use it),endIndexnot greater thanstartIndex, andinheritFromBeforewithstartIndex0, before sending.statusin write results is our sentence; Google's value is not documented.- Not verified against Google's servers: whether Google's
get_valuesuses formatted values and whether itsupdate_valuesusesRAW(both are the closest reading of the reference). A recorded comparison on the enrolled internal account would settle both.
Open questions
- Whether an OAuth client marked as an AI-powered agent may call the REST APIs.
- Each Google Cloud project behind a connection needs the REST APIs enabled
(Gmail now; Drive, Docs, Sheets, Slides and Calendar as their tools land).
Without that, calls return the
api_disabledtool error. freeBusy.querydoes not acceptcalendar.events, and the read & write Calendar selection grantscalendar.calendarlist.readonlyandcalendar.eventsonly (thecalendar.events→calendar.events.freebusyimplication ingoogleWorkspaceEffectiveScopesis ours, not Google's). Those users get theevents.listfallback, which cannot see coworkers who share only free/busy. Addingcalendar.events.freebusy(already one of the 14 submitted scopes) to thecalendar.writeprofile would fix that.- Whether
files.copywith a token that holdsdrive.readonlyanddrive.filecan copy a file the app never created or opened. Google's scope pages do not say; one live call on the test account will tell. If it cannot,copy_filecopies only files this app created or that were opened with it.
Removal procedure
- Set every service in
GOOGLE_WORKSPACE_TOOL_TRANSPORTtogoogle_mcp. - Delete this folder,
server/src/google-workspace-rest-tools/. - Delete
server/src/services/google-workspace-rest-dispatch.tsand its test, and the two call sites: thepaperclip_restbranch inexecuteRemoteHttpTool(server/src/services/tool-gateway.ts), withGOOGLE_WORKSPACE_REST_MAX_RESULT_BYTESthere, andgoogleWorkspaceRestToolsinserver/src/services/tool-access/catalog/discovery.ts. Deleteserver/src/__tests__/google-workspace-rest-transport.test.ts. - Check that the build, typecheck and tests pass, then delete the setting
and
transportitself if nothing else uses them.
Development
cd server && npx vitest run src/google-workspace-rest-tools
Test fixtures in fixtures/ and each service's fixtures/ folder are synthetic, in the shape
of Google's REST responses. They contain no real mail, addresses or IDs.