Google Workspace

Fetch a single message by id. See get_thread for the detail levels and the account rule.

Fetch several messages of one mailbox in one call, up to 25 ids, in the order given (a repeated id once). Use it after list_history or a search when you need the bodies of messages from different threads. A message that cannot be read comes back as {id, partial: true, reason} in its place and the others still arrive. See get_thread for the detail levels and the account rule; 'metadata' keeps a long list cheap.

A Google Slides deck's structure with the object ids batch_update_presentation needs: per slide its layout, every element (shapes with type, placeholder and full text, images, tables cell by cell, lines, videos, Sheets charts, groups) with size and transform, and the speaker notes' shape id; plus layouts, masters and the page size. A shape's text is exact, so offset k is index k for insertText and text ranges. Sizes show as "3000000 EMU"; requests take {magnitude, unit}. A long deck is cut at a slide (`nextSlide`: read on with from_slide). format raw returns the API's JSON, narrowed by `fields`. Returns revisionId.

A spreadsheet's structure with the ids batch_update_spreadsheet needs: per sheet its sheetId, size, frozen rows and columns, merges, conditional format rules (with their index), basic filter, filter views, protected and banded ranges, charts, slicers, tables and row/column groups, plus named ranges; ranges as A1. No cell data (get_values, read_rows). format raw returns the API's JSON for `ranges`, with grid data if asked, narrowed by `fields`: the way to read cell formats, notes, validation and pivots.

Fetch one thread with all its messages, their attachment metadata and their bodies. Thread ids are per-mailbox: pass the account that search_threads reported alongside the id.

A PNG thumbnail URL per slide, rendered by Google. The URLs expire after about half an hour.

A Meet transcript as text, one line per thing said: "[0:12:05] Ana Popescu: ...", the time counted from when the transcript began. Long ones come in parts of about max_chars; pass nextPageToken back to read on. The transcript is the name list_meetings gives (conferenceRecords/.../transcripts/...).

Values of several A1 ranges in one read, as Sheets renders them (FORMATTED_VALUE), as numbers (UNFORMATTED_VALUE: a double, so read_rows is the tool for money) or as formulas (FORMULA), chosen by A1 ranges or by data_filters. A large answer is cut at a row (`totalRows` says how many there were).

Every attachment matching a Gmail query, downloaded to a folder in ONE call, with a manifest. Use it for a month of invoices ('has:attachment after:2026/08/01 before:2026/09/01') instead of walking threads and calling get_attachment per file. Do NOT use Gmail's own 'download all attachments' zip as an alternative: it is keyed by thread id and silently omits parts keyed by message id. Returns counts (threadsMatched, attachmentsFound, savedCount) so the harvest can be reconciled against Gmail's own has:attachment count, each saved file with its size and sha256, plus a per-file failure list. Files are named <message id>-<filename>; two of one name both survive. A client that asks for progress hears each attachment saved, out of how many; cancelling stops the harvest, which then ends as cancelled.

Check that every grant is alive, per product and per account. Under `gmail`, per grant: the mailbox each credential resolves to, the scope Google actually GRANTED (not the one credentials.json declares), whether it can write, and the OAuth client the live token belongs to; an account may hold its own gmail.modify grant and a gmail.readonly one, and `activeGrant` is the one the tools use. Under `calendar`: that the grant refreshes, which account it resolves to (the consent screen offers every account signed in), and whether it carries the scopes the tools need. Under `drive`: which account the grant acts as and the storage used. Under `editors` (Docs, Sheets, Slides), per account: the address, the granted scopes, and whether each of the three APIs is enabled in the grant's Cloud project. Under `tasks`, `contacts` and `meet`, per account with a grant: the address, the granted scopes, and whether the API answers (`disabled` when its Cloud project has not enabled it); contacts also says which sources it reads. Under `config`: where the state directory, the OAuth client, the mailboxes and each account's address come from (a variable, or what setup or a consent saved; a variable that is set wins). Checks EVERY account by default. Run this before concluding the server is broken, and before retrying a write that refused.

Add or replace hyperlinks on existing plain text cells in one atomic batch. Keeps their values, validation and all other formatting. Row and column are 1-based. Every cell must still contain expected_text; formulas, rich text and chips are refused before any write.

The Google accounts this server reaches, per product. Start here: every other tool takes one of these labels. Under `gmail`: the mailboxes, which one a tool uses when no account is given, and which grant each runs on: `modify` (its own; the write tools work) or `readonly` (a read-only grant; the write tools refuse). Under `calendar`: the accounts whose calendars it reaches, the address each grant must resolve to, and the time zone. Under `drive`: which grant Drive runs on (its own once begin_consent made one, else an rclone remote's when one is configured). Under `editors`: the accounts Docs, Sheets and Slides can act as (one may run on the Drive grant; any other needs a grant made with begin_consent). Under `tasks`, `contacts` and `meet`: the accounts with a grant for Google Tasks, for contacts and the directory, and for Meet's records. Says nothing about whether a grant is alive; that is health, which costs a round trip to Google.

Every calendar each account can see (its own, shared ones, subscriptions, holidays), with its id, the account's access to it, and whether agenda reads it by default.

The comment threads on a Doc, Sheet, deck or any Drive file, each with its author, time, text, the text it quotes, whether it is resolved, and its replies (with any resolve or reopen action). Counts the open and resolved threads.

The account's drafts, newest first, with recipients, subject, snippet and each draft's webUrl.

The mailbox's Gmail filters: criteria, the labels each adds and removes (by name), and `query`, the search its criteria amount to, for applying it to mail already there with modify_labels_matching.

The direct children of one folder. Give file_id or path; empty path means the root of My Drive. Google Docs come back with isNative true and bytes null, because a Doc has no stored bytes.

Messages added since a historyId: incremental sync instead of re-searching the same window. Take the anchor from health's historyId, store it, pass it back next run. Anchors are per-mailbox, so keep one per account. Gmail expires old anchors: a 404 here means the anchor is too old and a full search_threads is needed to re-baseline.

List Gmail labels (system and user-defined) for one account.

A deck's (or template's) layouts, by name, and the placeholders each has (TITLE, SUBTITLE, BODY, ...).

The Google Meet meetings one account took part in, each with its transcripts, smart notes (Gemini's notes) and recordings, as Meet records them: for a calendar event (event_id from agenda: its Meet call, and for one occurrence the sitting that started within an hour of it), for a Meet link or code (meeting), or else for the last days (at most 30: Meet keeps records 30 days). A transcript or notes is a Google Doc: its document id opens with read_document; get_transcript reads a transcript as lines with who said what. Reading an event needs the account's calendar grant too.

Every permission on a Drive file: each person, group, domain or link with its role, expiry and id, whether it comes from a shared drive, and the link sharing in one line. Read it before share_file, update_permission or remove_permission.

A Drive file's revisions, oldest first: id, time, who made it, size and checksum for files with bytes, whether it is kept forever or published, and for a Doc, Sheet or deck the formats an old revision can be saved as with download_revision.

A spreadsheet's title, locale, time zone and sheets (id, name, size, frozen rows).

Every Google Tasks list of each account (every account by default), with the taskListId the other task tools take; the default list is marked.

Tasks across every account by default, from every list unless task_list names one, in each list's own order. Open tasks only unless include_completed. due_from and due_to keep the tasks due between those dates (inclusive), which leaves out tasks with no due date. Each task carries account, taskListId and taskId for the write tools, parent when it is a subtask, and its link in Google Tasks. agenda with include_tasks shows the tasks due beside the events.

Report threads or messages as spam: into SPAM and out of the inbox, as Gmail's own button does.

Add and remove labels on threads or messages. In Gmail these ARE the everyday actions: archive = remove INBOX; mark read = remove UNREAD (unread = add it); star = add STARRED; important = IMPORTANT. Labels may be given by id or by name, case-insensitively. For threads, ids that failed are listed under `failed` beside the ones changed.

Add and remove labels on EVERY thread a Gmail search matches, as Gmail's "select all conversations that match this search" does: file a sender under a label and archive it (add the label, remove INBOX), mark old mail read (remove UNREAD). A dry run by default: it returns how many threads match and a sample, and changes nothing. With dry_run false it refuses when the search matches more than `limit`, and otherwise changes every match, listing any thread that failed. To be able to find and reverse a large change later, also add a marker label created for it (e.g. 'cleanup/2026-10').

Move one or many files into a folder, optionally renaming a single one. Sources are paths, or "id:<fileId>" to name one directly. Works the same for a Google Doc as for a PDF, which is the reason to use this instead of moving files in a synced local copy: moving a Doc's placeholder there deletes the Doc and uploads a small shortcut file in its place. Call with dry_run first; the plan names every collision.

Move a task: under parent (a subtask; top level when omitted), after previous (first among its siblings when omitted), and into another list of the same account with to_list. A repeating task cannot change lists.

The reverse of resolve_path: where a file sits, as a path, by walking its parents to the root.

Every slide's layout, title, other text (tables as rows) and speaker notes, in order.

Export a Google Doc, Sheet or Slide deck as text and return it. Sheets come back as CSV. A Doc has no bytes to download, and this fetches its words in one request. Binary files are refused on purpose; download_file saves their bytes.

A Google Doc as markdown (headings, lists, tables, bold/italic/links), with an index of its sections: each heading's stable id and path ("Plan > Risks"). Pass `section` (an id, a path or a unique title) to read one section. Returns revisionId for a later edit's expected_revision. Reads the first tab unless `tab` names another; images, footnotes and the like are left out, and `notShown` counts them.

Rows as objects keyed by the header row. Values are typed: numbers stay numbers, dates are ISO strings (sheet-local time), and a currency cell is {value, amount, formatted} with `amount` its exact decimal string. Each row has `_row`, its row number. Empty rows are skipped.

Sparse cells with entered formulas, shown values, hyperlinks, rich-text links, smart chips and notes. Row and column numbers are 1-based. offset counts physical rows; follow nextOffset until null. Use this before changing a link or formula, rather than inferring it from read_rows display text.

Remove one permission from a file: that person, group, domain or link loses access. Inherited shared-drive access cannot be removed here. It changes who can open the file: do it only on the user's explicit go for this file and these people.

Change a file's name in place. Names cannot contain a slash; Drive has no path, only parents.

Answer a message, threaded properly for every party: the original's threadId, In-Reply-To and References, a 'Re:' subject, and the recipients Gmail's own Reply picks (Reply-To when the original has one, else From; a reply to a message you SENT goes to its recipients). Goes out from the alias the original reached. Creates a DRAFT unless send is true. `to` replaces the computed recipients; `cc` and `bcc` add to them.

A reply on a comment thread, and/or its resolve or reopen (`action`), as the account; what the comment box's Reply and Resolve buttons do.

Walk a path and return the id it names. A path is a QUERY on Drive, not an address: two objects may hold the same name in one folder, and this reports that as an error listing both ids rather than picking one. Use it before any tool that writes. A Drive name may itself contain a slash (Google Meet writes folders like "Weekly sync - 2030/01/15"); those are reachable only by id, which find_files returns.

Answer an invitation: accepted, declined or tentative. Changes only your own answer. The organiser sees it on the event either way; send_updates=all also emails them.

Developer metadata: key/value tags a program attaches to the spreadsheet, a sheet, or rows and columns (createDeveloperMetadata in batch_update_spreadsheet), which then name those cells in data_filters. One tag by metadata_id, or every tag data_filters match (e.g. [{"developerMetadataLookup": {"metadataKey": "invoice-table"}}]), each with where it is attached as A1.

Search threads with Gmail query syntax, e.g. 'from:billing.example.com after:2026/01/01 has:attachment', 'subject:invoice newer_than:30d', 'label:INBOX is:unread'. Searches EVERY registered mailbox by default and tags each result with the account it came from, so a question that does not know which mailbox holds the answer needs one call. Returns summaries; use get_thread for bodies.

Send an existing draft as it stands. SENDING IS OUTWARD-FACING AND CANNOT BE UNDONE: only send when the user has explicitly approved THIS message (its recipients and its text) in the current conversation. Otherwise create a draft and give the user its webUrl. Returns the sent message's webUrl.

Send a NEW message immediately. SENDING IS OUTWARD-FACING AND CANNOT BE UNDONE: only send when the user has explicitly approved THIS message (its recipients and its text) in the current conversation. Otherwise create a draft and give the user its webUrl. Prefer create_draft. To answer an existing message use reply, which threads it. Returns the sent message's webUrl.

Who the threads matching a query come from: per sending domain, busiest first, the thread and unread counts, the newest and oldest date, and its busiest addresses. The starting point for sorting a mailbox into labels and filters. A thread's sender is the author of its latest message you did not send. One mailbox per call. A few hundred threads take seconds; past that Gmail's quota allows about 25 threads a second, so a 3000-thread inbox takes about two minutes.

Give a person or group (email_address), a domain, or anyone with the link access to a Drive file, as reader, commenter, writer (organizer roles on shared drives), with an optional expiry. Drive's email goes out only with notify: true, with `message` in it. Making someone the owner needs transfer_ownership: true. It changes who can open the file: do it only on the user's explicit go for this file and these people.

A token meaning "from now on". Keep it, and hand it to drive_changes later. This is the cheap half of keeping anything in step with Drive: one call, no listing.