src/tools/gmail/README.md

Gmail

Tools for reading, drafting, sending, deleting, organizing, and triaging Gmail messages on the authenticated user's account. Uses the gmail.modify OAuth scope, which covers read, send, draft, label changes, and trash but not permanent message deletion.

Messages

Tool	Description
listMessages	Lists or searches messages using the full Gmail query syntax (e.g. is:unread from:foo newer_than:7d)
getMessage	Fetches a single message with decoded headers, plain-text body, HTML body, and attachment metadata
sendEmail	Sends a plain-text email; supports cc/bcc and threaded replies via replyToMessageId
trashMessage	Moves a message to Trash (reversible from the Gmail UI Trash folder for 30 days). Not a permanent delete
modifyMessageLabels	Adds and/or removes labels on a message — used for star, archive, mark read, and custom-label tagging
listLabels	Lists all system and user-created Gmail labels with their IDs, for use with the other tools

Drafts (compose / review / send)

Tool	Description
createDraft	Creates a draft instead of sending. Use this when an AI composes an email the user should review
listDrafts	Lists drafts with recipients, subject, and snippet
getDraft	Fetches one draft with full headers and body
updateDraft	Replaces a draft's contents (full replace, not patch). Use to iterate before sending
sendDraft	Sends an existing draft by ID — pairs with createDraft for the compose-review-send loop
deleteDraft	Permanently deletes a draft. Not moved to Trash — gone

Composite triage

Tool	Description
triageInbox	One call returns N unread messages with full content + per-message heuristic flags (newsletter detection via List-Unsubscribe, meeting reference, contains question, action requested) PLUS aggregate stats (top senders, category breakdown). Designed for AI inbox triage in a single round-trip

Common label IDs

System labels you can pass to modifyMessageLabels and listMessages.labelIds without calling listLabels first:

• INBOX, SENT, DRAFT, TRASH, SPAM
• UNREAD, STARRED, IMPORTANT
• CATEGORY_PERSONAL, CATEGORY_SOCIAL, CATEGORY_PROMOTIONS, CATEGORY_UPDATES, CATEGORY_FORUMS

Custom labels (anything you created in the Gmail UI) have opaque IDs like Label_1234567890 — fetch them with listLabels.