Loading ToolBench
MCP server for Gmail label management with auto-refreshing OAuth2
The Gmail Labels MCP server demonstrates solid tool design with clear naming conventions, comprehensive descriptions, and well-structured schemas. All 7 tools follow verb-first naming (gmail_*), each with actionable descriptions that explain purpose, parameters, and usage examples. Input schemas are properly typed with JSON Schema. However, there are gaps in output schema documentation and some description improvements could be made. Tool descriptions average ~220 characters, which is within the baseline range (p10=34, p90=392). Parameters are consistently documented with types, defaults, and constraints. Error handling is present but could be more specific about recovery steps.
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"
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?"
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?"
Output schemas not documented in source code. Tool descriptions mention what is returned (e.g., 'List of labels with their IDs, names, types, and message counts') but no structured JSON Schema is visible for response objects. LLMs cannot reliably parse unmarked output structure.
Error handling responses not documented. No visible specification of what errors are retryable, how to recover, or what the LLM should do next. Error responses should guide the agent toward a solution (e.g., 'Label not found. Call gmail_list_labels to see available label IDs').
No dry-run or confirmation pattern for destructive operation. gmail_delete_label irreversibly deletes a label, but there is no confirmation step or dry-run option. Agents could accidentally delete important labels without explicit user confirmation.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | C | 63 | 2025-06-18+ | v2 |
| 2026-03-09 | F | 48 | - | v1 |
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"]
Search Gmail messages using Gmail search syntax. Args: - query (string): Gmail search query (e.g. 'from:alice@example.com has:attachment after:2024/01/01') - max_results (number): Max results to return (1-500, default 20) Supported search operators: from, to, cc, bcc, subject, has:attachment, is:unread, is:starred, is:important, before, after, newer_than, older_than, filename, label Returns: List of matching message IDs and thread IDs. Examples: - Use when: "Find all unread emails from alice" - Use when: "Search for emails with attachments from last week" - Use when: "Find messages in the Finance label from this month"
Pagination guidance missing for gmail_search_messages. Tool accepts max_results (1-500, default 20) but does not specify how to retrieve the next page of results. No cursor, offset, or continuation token mechanism is documented, limiting LLM ability to iterate through large result sets.
Tool descriptions include example values (e.g., 'Finance/Invoices', 'Label_123', 'abc123') that LLMs may reuse literally in subsequent calls instead of adapting to actual context. Use parameter constraints (enums, patterns, minLength/maxLength) instead.