Gmail

Email. Search, read, send, reply to, draft, label, and delete messages and the conversation threads they sit in.

Measured routing accuracy

27 golden cases replayed through the router over the whole index: measured over corpus ea4f12ad2948 (65 toolkits, 2283 tools indexed and 13 declared uncallable), 15 cases written by hand and 11 cases from the paraphrase pass, plus 1 context case whose intent names no app and is decided by the session. A case counts as top-1 when its gold tool ranked first and top-8 when it reached the slate at all.

The sweep is offline: the reranker is a deterministic identity fake that returns candidates in the order retrieval produced them, so top-1 measures retrieval order rather than a reranked slate. just eval-live measures the same cases through the live reranker.

Authentication

Connect an entity with ConnectionsService.InitiateConnection, naming this toolkit's slug. Credentials stay in the connections vault; callers hold connected-account ids only.

oauth2

Tools

28 action tools. The catalog-wide slug is gmail.<tool>, which is what search_tools returns and call_tool takes.

gmail.search_messages

Search or list emails in the mailbox using Gmail query syntax (from:, to:, subject:, is:unread, label:, has:attachment, newer_than:7d). Use when the user wants to find, look up, or check mail. Returns message and thread ids; results are not sorted by recency. Fetch full content with get_message.

Class read (reads only). Scopes https://www.googleapis.com/auth/gmail.readonly. Calls GET /users/me/messages.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "hunt down an email about something", "dig through my inbox for a message", "see if I got anything from someone", "pull up mail mentioning a topic", "track down that old email".

gmail.get_message

Get one email's full content by message id: headers (From, To, Subject), body, snippet, labels, and attachment ids. Use after search_messages to read a specific message. Use internalDate for recency, not the Date header. For a whole conversation use get_thread instead.

Class read (reads only). Scopes https://www.googleapis.com/auth/gmail.readonly. Calls GET /users/me/messages/{{params.message_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "pull up that email and show me what it says", "open it up and let me see the whole thing", "show me everything that message contains".

gmail.get_attachment

Download an email attachment by message id and attachment id. Use when the user wants a file, PDF, image, or invoice attached to a message. Attachment ids come from the message payload returned by get_message. Returns base64url-encoded file bytes.

Class read (reads only). Scopes https://www.googleapis.com/auth/gmail.readonly. Calls GET /users/me/messages/{{params.message_id}}/attachments/{{params.attachment_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "grab the file they sent me", "save that attachment to my computer", "pull down the PDF from that email", "fetch the file that was attached".

gmail.modify_message_labels

Add or remove labels on a single email: mark read or unread (UNREAD), archive (remove INBOX), star (STARRED), or apply a custom label. Takes label ids, not names; resolve ids with list_labels. For many messages at once use batch_modify_messages; for a whole conversation use modify_thread_labels.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /users/me/messages/{{params.message_id}}/modify.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "flag this one as unread again", "tag it with a category", "sort this email into a folder", "get this out of my inbox without trashing it", "keep it but hide it from my inbox".

gmail.batch_modify_messages

Add or remove labels on up to 1000 emails in one call: bulk archive, mark all read or unread, or label many messages at once. Takes message ids plus label ids from list_labels. For a single message use modify_message_labels.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /users/me/messages/batchModify.

Arguments:

Also retrieved by: "clean up my inbox by handling a bunch of these at once", "tidy up all these newsletters in one go", "sort a pile of emails into a folder together", "mass update the status on several of these".

gmail.trash_message

Move an email to the trash. Use when the user wants to trash, remove, or get rid of a message. Recoverable for about 30 days via untrash_message. For permanent removal use delete_message; to trash a whole conversation use trash_thread.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls POST /users/me/messages/{{params.message_id}}/trash.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "bin that email", "toss this message out", "chuck it in the trash", "send it to the bin".

gmail.untrash_message

Restore an email from the trash back to the mailbox. Use when the user wants to recover, undelete, or un-trash a message they trashed. Only works before the trash is purged.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /users/me/messages/{{params.message_id}}/untrash.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "bring that email back from the trash", "I didn't mean to bin it, get it back", "pull that message out of the trash", "recover the one I just tossed".

gmail.delete_message

Permanently delete one email, bypassing the trash. Unrecoverable; prefer trash_message when the user might want it back. Use only when the user explicitly asks for a message to be gone forever.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes https://mail.google.com/. Calls DELETE /users/me/messages/{{params.message_id}}.

Arguments:

Also retrieved by: "wipe that email for good", "nuke this message completely", "scrub it from my mailbox entirely", "erase it permanently, no recovering it".

gmail.batch_delete_messages

Permanently delete many emails at once by id, bypassing the trash. Unrecoverable; meant for bulk cleanup such as retention enforcement. Verify the id list first. When recovery may be needed, trash messages individually with trash_message instead.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes https://mail.google.com/. Calls POST /users/me/messages/batchDelete.

Arguments:

Also retrieved by: "wipe out a bunch of old emails for good", "purge these messages completely", "clear out a pile of emails permanently", "nuke all of these at once".

gmail.list_threads

List email conversations (threads) with Gmail query syntax and pagination. Use when the user thinks in conversations rather than single messages. Spam and trash are excluded unless the query targets them. Returns thread ids and snippets; read one with get_thread.

Class read (reads only). Scopes https://www.googleapis.com/auth/gmail.readonly. Calls GET /users/me/threads.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "show me my conversations", "what discussions do I have going", "pull up my email threads", "list out the conversations in my inbox".

gmail.get_thread

Get every message in one email conversation by thread id. Use when the user wants the whole thread, the back-and-forth, or the full history with someone. Message order is not guaranteed; sort by internalDate. For a single message use get_message.

Class read (reads only). Scopes https://www.googleapis.com/auth/gmail.readonly. Calls GET /users/me/threads/{{params.thread_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "catch me up on this whole conversation", "show me every message in this exchange", "what's the full history on this discussion", "read the entire back and forth".

gmail.modify_thread_labels

Add or remove labels on an entire conversation, affecting all its messages: archive a thread, mark it read, or label it. Takes label ids from list_labels, not display names. For one message only, use modify_message_labels.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /users/me/threads/{{params.thread_id}}/modify.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "mark this whole conversation as handled", "tag the whole exchange", "get this whole discussion out of my inbox".

gmail.trash_thread

Move a whole conversation and all its messages to the trash. Use when the user wants to trash or get rid of an entire thread. Recoverable for about 30 days via untrash_thread. For one message use trash_message; for permanent removal use delete_thread.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls POST /users/me/threads/{{params.thread_id}}/trash.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "bin this whole conversation", "toss out this entire discussion", "chuck this exchange in the trash".

gmail.untrash_thread

Restore a trashed conversation and its messages back to the mailbox. Use when the user wants to recover or undelete a thread they trashed.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /users/me/threads/{{params.thread_id}}/untrash.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "bring this conversation back from the trash", "recover the whole discussion I just tossed", "pull this exchange out of the bin".

gmail.delete_thread

Permanently delete a conversation and every message in it, bypassing the trash. Unrecoverable; prefer trash_thread when the user might want it back. Use only on an explicit request to erase a thread forever.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes https://mail.google.com/. Calls DELETE /users/me/threads/{{params.thread_id}}.

Arguments:

Also retrieved by: "wipe out this entire conversation for good", "nuke this whole discussion permanently", "erase this exchange completely, no recovering it".

gmail.create_draft

Create an email draft without sending: compose a message and save it for later review. Takes a base64url-encoded RFC 2822 MIME message; set thread_id to draft a reply inside an existing conversation. Returns a draft id for send_draft. To send immediately use send_email.

Class write (writes, no confirmation needed). Scopes https://www.googleapis.com/auth/gmail.compose. Calls POST /users/me/drafts.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "start writing something I'm not ready to send yet", "stash a message for later without sending it", "jot down a note I'll finish later", "put together something I can review first".

gmail.list_drafts

List saved email drafts with pagination. Use when the user asks what drafts exist or wants to find an unsent message. Returns draft ids; read one with get_draft. Ordering is not guaranteed.

Class read (reads only). Scopes https://www.googleapis.com/auth/gmail.readonly. Calls GET /users/me/drafts.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what unsent messages do I have sitting around", "show me what I haven't sent yet", "pull up what I've started but not finished".

gmail.get_draft

Get one saved draft's content by draft id, to inspect or show the unsent message before sending. Draft ids come from list_drafts or create_draft.

Class read (reads only). Scopes https://www.googleapis.com/auth/gmail.readonly. Calls GET /users/me/drafts/{{params.draft_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "pull up that unsent note", "show me what I've written so far", "open the one I saved earlier".

gmail.update_draft

Replace a saved draft's content by draft id. Overwrites the entire draft, not individual fields; supply the complete new MIME message. Use when the user edits, revises, or fixes an unsent draft.

Class write (writes, no confirmation needed). Scopes https://www.googleapis.com/auth/gmail.compose. Calls PUT /users/me/drafts/{{params.draft_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "fix up that unsent message", "change what I wrote before I send it", "edit the note I haven't sent yet".

gmail.send_draft

Send an existing saved draft as-is by draft id. Recipients come from the draft's own To, Cc, and Bcc headers and cannot be added here. Immediate and irreversible. If the draft lacks recipients, fix it with update_draft first, or use send_email.

Class write (writes, no confirmation needed). Scopes https://www.googleapis.com/auth/gmail.compose. Calls POST /users/me/drafts/send.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "go ahead and fire that off", "ship the message I saved earlier", "that one's ready, send it now", "push out the note I put together".

gmail.delete_draft

Permanently delete a saved draft by draft id. Not recoverable; the unsent message is discarded. Only affects drafts, never sent or received mail. Verify the draft id before calling.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes https://www.googleapis.com/auth/gmail.compose. Calls DELETE /users/me/drafts/{{params.draft_id}}.

Arguments:

Also retrieved by: "toss that unsent message", "get rid of the one I started", "scrap what I was writing".

gmail.list_labels

List every label in the mailbox, system (INBOX, UNREAD, STARRED, SPAM, TRASH) and user-created, with their ids. Use to resolve a label name to the label id other tools require; display names do not work as ids. Also answers what labels or folders exist.

Class read (reads only). Scopes https://www.googleapis.com/auth/gmail.labels. Calls GET /users/me/labels.

Takes no arguments.

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what folders do I have set up", "show me my categories and tags", "what tags exist in my mailbox", "what are all my organizing labels called".

gmail.get_label

Get one label's details by label id: name, type, unread and total message and thread counts, and visibility. Use list_labels first to resolve the id. Answers questions like how many unread messages a label has.

Class read (reads only). Scopes https://www.googleapis.com/auth/gmail.labels. Calls GET /users/me/labels/{{params.label_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "how many unread emails are under that folder", "what's the count on this tag", "how many messages are filed under this one".

gmail.create_label

Create a new label (folder or tag) for organizing mail. Use when the user wants a new category, folder, or tag. Returns the label id that labeling tools require; they do not accept display names. Label names must be unique.

Class write (writes, no confirmation needed). Scopes https://www.googleapis.com/auth/gmail.labels. Calls POST /users/me/labels.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "set up a new folder for something", "make a new tag to sort messages", "start a new category for my mail".

gmail.update_label

Rename a user-created label or change its visibility by label id. Use when the user renames a label or folder. System labels such as INBOX or SENT cannot be modified.

Class write (writes, no confirmation needed). Scopes https://www.googleapis.com/auth/gmail.labels. Calls PATCH /users/me/labels/{{params.label_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "rename that folder", "change what this tag is called", "give this one a new name".

gmail.delete_label

Permanently delete a user-created label definition, removing it from every message it is applied to; the messages themselves are kept. System labels cannot be deleted. To take a label off specific messages instead, use modify_message_labels.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes https://www.googleapis.com/auth/gmail.labels. Calls DELETE /users/me/labels/{{params.label_id}}.

Arguments:

Also retrieved by: "get rid of that tag for good", "remove this folder, I don't need it anymore", "delete this category entirely".

gmail.send_email

Send an email immediately. Use when the user wants to email, message, or forward something to someone. Takes a base64url-encoded RFC 2822 MIME message with To, Subject, and body. Irreversible; confirm recipients first. To reply inside an existing conversation use reply_to_thread; to save without sending use create_draft.

Class write (writes, no confirmation needed). Scopes https://www.googleapis.com/auth/gmail.send. Calls POST /users/me/messages/send.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "fire off a message to someone", "shoot them a quick note", "get a message out to them with the details", "ping them over mail with an update", "drop them a line about something".

gmail.reply_to_thread

Send a reply inside an existing email conversation by thread id. Use when the user wants to reply, respond, or write back on a thread. Keep the original subject with a Re: prefix and set In-Reply-To and References headers in the MIME message, or the reply starts a new thread. For a fresh email use send_email.

Class write (writes, no confirmation needed). Scopes https://www.googleapis.com/auth/gmail.send. Calls POST /users/me/messages/send.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "write back on this conversation", "answer them in this exchange", "respond to what they said in this discussion", "get back to them on this one".

Triggers

Triggers are app-initiated. They are not retrievable as tools and cannot be called; subscribe with TriggersService.CreateSubscription and events arrive as signed deliveries.

new_email

Fires when a watched mailbox changes, which is how Gmail reports new mail. Carries the Pub/Sub message whose base64 data holds the mailbox address and the history id; read the new messages with search_messages or list_history after it fires.

Payload fields (anything the schema does not declare never reaches a subscriber):

Inbound webhooks

Providers post to /webhooks/gmail. Posts that fail verification are rejected before anything is stored, and the ingest path refuses every post while the secret variable is unset.

Mappings are tried in order and the first match wins.