List all labels (tags) in the Gmail account.

Returns both system labels (INBOX, SENT, TRASH, etc.) and user-created labels. Use this to find label IDs needed for add/remove operations.

Returns: List of labels with their IDs, names, types, and message counts.

Examples:

• Use when: "Show me all my Gmail labels"

• Use when: "What label ID does 'Finance' have?"

Create a new user label (tag) in Gmail.

Args:

• name (string): Label name. Supports nesting with "/" (e.g., "Finance/Invoices")

Returns: The created label with its ID, name, and visibility settings.

Examples:

• Use when: "Create a label called 'Compliance'"

• Use when: "Add a new Gmail tag 'Projects/Alpha'"

Delete a user-created label from Gmail. System labels cannot be deleted.

Args:

• label_id (string): The label ID to delete (use gmail_list_labels to find IDs)

Note: Deleting a label removes it from all messages but does not delete the messages.

Examples:

• Use when: "Delete the label with ID Label_123"

• Use when: "Remove the 'OldProject' label"

Add or remove labels (tags) on a specific Gmail message.

Args:

• message_id (string): The Gmail message ID

• add_label_ids (string[]): List of label IDs to add (optional)

• remove_label_ids (string[]): List of label IDs to remove (optional)

Use gmail_list_labels to find label IDs. Common system label IDs:

• INBOX, STARRED, IMPORTANT, SENT, TRASH, SPAM, UNREAD, READ

Returns: Updated message with its current label IDs.

Examples:

• Use when: "Tag message abc123 with label Label_456"

• Use when: "Remove INBOX label from message abc123 (archive it)"

• Use when: "Star message abc123" -> add_label_ids: ["STARRED"]

Add or remove labels on all messages in a Gmail thread at once.

Args:

• thread_id (string): The Gmail thread ID

• add_label_ids (string[]): Label IDs to add to all messages in the thread

• remove_label_ids (string[]): Label IDs to remove from all messages in the thread

Returns: Updated thread with message count and affected message IDs.

Examples:

• Use when: "Label this entire conversation as 'Compliance'"

• Use when: "Archive this thread" -> remove_label_ids: ["INBOX"]

Retrieve the current labels on a specific Gmail message.

Args:

• message_id (string): The Gmail message ID

Returns: Message metadata including subject, snippet, and current label IDs.

Examples:

• Use when: "What labels does message abc123 have?"

• Use when: "Is message abc123 starred?"

Search Gmail messages using a query and apply label changes to all matching messages.

Args:

• query (string): Gmail search query (same syntax as Gmail search box)

• add_label_ids (string[]): Label IDs to add to all matching messages

• remove_label_ids (string[]): Label IDs to remove from all matching messages

• max_results (number): Max messages to process (default: 20, max: 100)

Common query examples:

• "from:sender@example.com" - emails from a sender

• "subject:invoice" - emails with 'invoice' in subject

• "is:unread" - unread emails

• "after:2024/01/01 before:2024/12/31" - date range

Returns: Count of messages updated and their IDs.

Examples:

• Use when: "Label all emails from compliance@firm.com as 'Compliance'"

• Use when: "Archive all emails with subject 'Newsletter'"