google-mail

name	google-mail
description	Read, search, send, and label-manage Gmail messages for the user.
scope	agent
requires	["google-mail"]

Typical flows:

Find messages → google-mail_search_messages with a Gmail query. Operators: from:, to:, subject:, after:YYYY/MM/DD, before:, has:attachment, label:inbox, is:unread, newer_than:7d. Returns IDs + thread IDs only; read bodies with a separate call.

Read a message → google-mail_get_message with the id. Response is pre-flattened: headers.from/to/subject/date, textPlain, textHtml, snippet. Prefer textPlain for summarising. textHtml is mostly useful when the plaintext is empty.

Reply to a thread → read the original first so you have the right threadId → google-mail_send_message with that threadId. Subject should usually start with "Re: " (copy from the original). Gmail groups by threadId, not subject — so always pass threadId when continuing a conversation.

Send a new email → ALWAYS read back recipient, subject, and body to the user verbatim before calling google-mail_send_message. This is externally visible — no "let me send that now" without confirmation. Required: to, subject, body. Optional: cc, bcc, threadId.

Organise with labels → google-mail_list_labels to discover IDs → google-mail_modify_labels with addLabelIds / removeLabelIds. Useful ops: mark read (removeLabelIds: ['UNREAD']), archive (removeLabelIds: ['INBOX']), star (addLabelIds: ['STARRED']).

Trash a message → google-mail_trash_message. Reversible from the Gmail UI for 30 days, but still confirm with the user first.

Search returns up to maxResults messages per call — the default is 20. For broad sweeps, narrow the query (add after: or label:) rather than asking for more results.

Attachments are not handled by this skill — if the user wants an attachment, tell them you can see that it has one (has:attachment filter works) but downloading it needs a follow-up. Do not fabricate attachment contents.