The Gmail MCP server provides a standardized interface via Model Context Protocol for comprehensive Gmail API management, including:
Email Management: Send, retrieve, modify, delete, and batch process messages; manage attachments
Label Operations: Create, update, delete, and list labels with customization options
Thread Management: List, retrieve, modify, trash/untrash, and delete email threads
Draft Operations: Create, retrieve, update, delete, and send email drafts
Settings Configuration: Manage vacation responder, IMAP/POP settings, language preferences, delegates, filters, forwarding addresses, send-as aliases, and S/MIME configurations
User Management: Retrieve profiles, set up and stop push notifications for mailbox changes
Provides comprehensive Gmail API access including sending/drafting emails, message and thread management, label operations, attachment handling, settings configuration (vacation responder, IMAP/POP), and mailbox history tracking.
Enables OAuth2 authentication using Google Cloud credentials for secure access to Gmail services.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Gmail MCP send an email to john@example.com about tomorrow's meeting"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server implementation for the Gmail API, providing a standardized interface for email management, sending, and retrieval.
Complete Gmail API coverage including messages, threads, labels, drafts, and settings
Support for sending, drafting, and managing emails
Label management with customizable colors and visibility settings
Thread operations for conversation management
Settings management including vacation responder, IMAP/POP, and language settings
History tracking for mailbox changes
Secure OAuth2 authentication using Google Cloud credentials
Related MCP server: Gmail MCP Server
For simplest installation, install Node.js 18+. If you would like to build locally, you will also need to install pnpm.
To run this MCP server, you will need to set up a Google API Client for your organization, with each user running a script to retrieve their own OAuth refresh token.
Go to the Google Cloud Console.
Create a new project or select an existing one.
Enable the Gmail API for your project.
Go to Credentials and create an OAuth 2.0 Client ID. Choose "Desktop app" for the client type.
Download and save the OAuth keys JSON as ~/.gmail-mcp/gcp-oauth.keys.json. ⚠️ NOTE: to create ~/.gmail-mcp/ through MacOS's Finder app you need to enable hidden files first.
(Optional) For remote server installation (ex. using Smithery CLI), note the CLIENT_ID and CLIENT_SECRET from this file.
Have the user copy ~/.gmail-mcp/gcp-oauth.keys.json to their computer at the same path.
Run npx @shinzolabs/gmail-mcp auth.
A browser window will open where the user may select a profile, review the requested scopes, and approve.
(Optional) For remote server installation, note the file path mentioned in the success message (~/.gmail-mcp/credentials.json by default). The user's REFRESH_TOKEN will be found here.
There are several options to configure your MCP client with the server. For hosted/remote server setup, use Smithery's CLI with a Smithery API Key. For local installation, use npx or build from source. Each of these options is explained below.
To add a remote server to your MCP client config.json, run the following command from Smithery CLI:
npx -y @smithery/cli install @shinzo-labs/gmail-mcpEnter your CLIENT_ID, CLIENT_SECRET, and REFRESH_TOKEN when prompted.
If you are developing your own agent application, you can use the boilerplate code here.
To install the server locally with npx, add the following to your MCP client config.json:
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"@shinzolabs/gmail-mcp"
]
}
}
}Download the repo:
git clone https://github.com/shinzo-labs/gmail-mcp.gitInstall packages and build with pnpm (inside cloned repo):
pnpm i && pnpm buildAdd the following to your MCP client config.json:
{
"mcpServers": {
"gmail": {
"command": "node",
"args": [
"/path/to/gmail-mcp/dist/index.js"
]
}
}
}Variable | Description | Required? | Default |
| Port for the temporary OAuth authentication server | No |
|
| Google API client ID (found in | Yes if remote server connection |
|
| Google API client secret (found in | Yes if remote server connection |
|
| Path to the user credentials file | No |
|
| Path to the Google API Client file | No |
|
| Directory for storing configuration files | No |
|
| OAuth refresh token (found in | Yes if remote server connection |
|
| Port for Streamable HTTP transport method | No |
|
| Enable telemetry | No |
|
get_profile: Get the current user's Gmail profile
stop_mail_watch: Stop receiving push notifications
watch_mailbox: Set up push notifications for mailbox changes
list_messages: List messages with optional filtering
get_message: Get a specific message
get_attachment: Get a message attachment
modify_message: Modify message labels
send_message: Send an email message to specified recipients
delete_message: Permanently delete a message
trash_message: Move message to trash
untrash_message: Remove message from trash
batch_modify_messages: Modify multiple messages
batch_delete_messages: Delete multiple messages
list_labels: List all labels
get_label: Get a specific label
create_label: Create a new label
update_label: Update a label
patch_label: Partial update of a label
delete_label: Delete a label
list_threads: List email threads
get_thread: Get a specific thread
modify_thread: Modify thread labels
trash_thread: Move thread to trash
untrash_thread: Remove thread from trash
delete_thread: Delete a thread
list_drafts: List drafts in the user's mailbox
get_draft: Get a specific draft by ID
create_draft: Create a draft email in Gmail
update_draft: Replace a draft's content
delete_draft: Delete a draft
send_draft: Send an existing draft
get_auto_forwarding: Get auto-forwarding settings
update_auto_forwarding: Update auto-forwarding settings
get_imap: Get IMAP settings
update_imap: Update IMAP settings
get_pop: Get POP settings
update_pop: Update POP settings
get_vacation: Get vacation responder settings
update_vacation: Update vacation responder
get_language: Get language settings
update_language: Update language settings
list_delegates: List account delegates
get_delegate: Get a specific delegate
add_delegate: Add a delegate
remove_delegate: Remove a delegate
list_filters: List email filters
get_filter: Get a specific filter
create_filter: Create a new filter
delete_filter: Delete a filter
list_forwarding_addresses: List forwarding addresses
get_forwarding_address: Get a specific forwarding address
create_forwarding_address: Create a forwarding address
delete_forwarding_address: Delete a forwarding address
list_send_as: List send-as aliases
get_send_as: Get a specific send-as alias
create_send_as: Create a send-as alias
update_send_as: Update a send-as alias
patch_send_as: Partial update of a send-as alias
verify_send_as: Send verification email
delete_send_as: Delete a send-as alias
list_smime_info: List S/MIME configurations
get_smime_info: Get a specific S/MIME config
insert_smime_info: Upload a new S/MIME config
set_default_smime_info: Set default S/MIME config
delete_smime_info: Delete an S/MIME config
Contributions are welcomed and encouraged! Please read CONTRIBUTING.md for guidelines on issues, contributions, and contact information.
Shinzo Labs collects limited anonymous telemetry from this server to help improve our products and services. No personally identifiable information is collected as part of this process. Please review the Privacy Policy for more details on the types of data collected and how to opt-out of this telemetry.
MIT
Adds a delegate to the specified account
| Name | Required | Description | Default |
|---|---|---|---|
| delegateEmail | Yes | Email address of delegate to add |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description fails to disclose any behavioral traits such as side effects, permission requirements, or what happens if the delegate already exists. The description carries the full burden but provides no additional context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but too terse to provide necessary context. It could be expanded slightly to improve clarity without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool simplicity and lack of output schema or annotations, the description is insufficient. It does not clarify what 'specified account' refers to, nor does it describe the response or error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the single parameter 'delegateEmail', and the description does not add meaning beyond what the schema provides. With 100% schema coverage, baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Adds' and resource 'delegate', clearly indicating the action. It is distinct from siblings like 'remove_delegate' and 'list_delegates', though it does not specify which account is affected.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'remove_delegate' or 'get_delegate'. There is no mention of prerequisites or scenarios where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete multiple messages
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | The IDs of the messages to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description does not disclose behavioral traits such as irreversibility, partial success handling, or required permissions beyond implying a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise at two words, front-loading the core action, though it could expand slightly without losing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool, the description is adequate but lacks details about return behavior or error scenarios, leaving some gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with param 'ids' described as 'The IDs of the messages to delete', so the description adds no new meaning beyond the schema, earning a baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description specifies verb (delete) and resource (multiple messages), clearly distinguishing from sibling 'delete_message' which handles single messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this tool versus alternatives like 'delete_message' (single) or 'trash_message' (soft delete), nor any prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Modify the labels on multiple messages
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | The IDs of the messages to modify | |
| addLabelIds | No | A list of label IDs to add to the messages | |
| removeLabelIds | No | A list of label IDs to remove from the messages |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states the basic action. It does not disclose behavioral traits such as atomicity, error handling, rate limits, or what happens if some message IDs are invalid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence that is concise but lacks detail. It is not overly verbose, but it could benefit from additional context without becoming wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters, no output schema, and no annotations, the description is insufficiently complete. It does not explain batch behavior, such as whether modifications are atomic or how errors are handled.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage for each parameter. The description adds no additional semantics beyond the schema's parameter descriptions, resulting in a baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool modifies labels on multiple messages, distinguishing it from single-message operations like modify_message and delete operations like batch_delete_messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given on when to use this tool versus alternatives. The description implies batch usage but does not mention scenarios or contrasts with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a draft email in Gmail. Note the mechanics of the raw parameter.
| Name | Required | Description | Default |
|---|---|---|---|
| raw | No | The entire email message in base64url encoded RFC 2822 format, ignores params.to, cc, bcc, subject, body, includeBodyHtml if provided | |
| threadId | No | The thread ID to associate this draft with | |
| to | No | List of recipient email addresses | |
| cc | No | List of CC recipient email addresses | |
| bcc | No | List of BCC recipient email addresses | |
| subject | No | The subject of the email | |
| body | No | The body of the email | |
| includeBodyHtml | No | Whether to include the parsed HTML in the return for each body, excluded by default because they can be excessively large |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It mentions 'mechanics of the raw parameter' but fails to disclose that the raw parameter overrides other fields, which is a critical behavioral trait.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two short sentences, front-loading the main purpose. No unnecessary information, though it could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and the complexity of the raw parameter overriding, the description is incomplete. It does not explain the implications of the raw parameter or provide a complete picture of the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for each parameter. The description adds minimal value by drawing attention to the raw parameter, but does not significantly enhance understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a draft email') and the resource ('in Gmail'), which is specific and distinguishable from sibling tools like 'send_draft' or 'delete_draft'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., send_draft). The description only hints at the raw parameter mechanics but does not provide usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a filter
| Name | Required | Description | Default |
|---|---|---|---|
| criteria | Yes | Filter criteria | |
| action | Yes | Actions to perform on messages matching the criteria |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for disclosing behavioral traits. It fails to mention any side effects, authentication requirements, idempotency, or return value, leaving the agent blind to important behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short but lacks essential detail, making it under-specified rather than concise. It does not front-load key information or structure usefully.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested objects, many fields, no output schema) and the lack of annotations, the description is completely incomplete. It fails to provide context about return values, error conditions, or how filters interact with the system.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the input schema already describes all parameters thoroughly. The description adds no additional meaning, meeting the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Creates a filter' is a tautology, restating the tool name without specifying what kind of filter or context. It does not indicate the system (e.g., Gmail) or distinguish from other create tools like create_draft or create_label.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The sibling list includes many creation tools, but the description gives no context for selecting create_filter over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a forwarding address
| Name | Required | Description | Default |
|---|---|---|---|
| forwardingEmail | Yes | An email address to which messages can be forwarded |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description only says 'Creates', implying mutation but not disclosing behavioral traits such as whether it triggers a verification email, duplicates handling, or return value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded, with no wasted words; however, it could be more informative without being longer.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with one parameter and no output schema, the description is sufficient for basic understanding but lacks context on side effects or related processes like verification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes the single parameter; the description adds no additional meaning beyond the verb.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Creates' and the resource 'forwarding address', which distinguishes it from siblings like 'delete_forwarding_address' and 'list_forwarding_addresses'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs alternatives, or any prerequisites like authentication or existing address verification.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new label
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The display name of the label | |
| messageListVisibility | No | The visibility of messages with this label in the message list | |
| labelListVisibility | No | The visibility of the label in the label list | |
| color | No | The color settings for the label |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description does not disclose behavior such as what happens if label name already exists, or any limitations on label creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is very short (4 words), which is concise but lacks necessary details. Could add a sentence about behavior without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and complex behavioral aspects (visibility, color, naming conflicts), the description is incomplete for an agent to confidently use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with descriptions. The tool description adds no additional meaning beyond the schema, achieving baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new label' clearly states the action and resource. It distinguishes from siblings like delete_label or patch_label, but does not provide context that it's for Gmail labels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like update_label or patch_label. No mention of prerequisites or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a custom send-as alias
| Name | Required | Description | Default |
|---|---|---|---|
| sendAsEmail | Yes | The email address that appears in the 'From:' header | |
| displayName | No | A name that appears in the 'From:' header | |
| replyToAddress | No | An optional email address that is included in a 'Reply-To:' header | |
| signature | No | An optional HTML signature | |
| isPrimary | No | Whether this address is the primary address | |
| treatAsAlias | No | Whether Gmail should treat this address as an alias |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description bears full burden but only states 'creates,' implying mutation. It omits permissions, idempotency, error conditions (e.g., duplicate alias handling), or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief (one sentence), which is concise but at the cost of necessary details. It could include more context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters and no output schema or annotations, the description fails to explain return values, success indicators, or edge cases, leaving the agent with insufficient information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-documented. The description adds no extra meaning beyond 'creates'; baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Creates a custom send-as alias' clearly states the action (create) and resource (send-as alias), effectively distinguishing it from sibling tools like patch_send_as (update) and delete_send_as.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., patch_send_as for updates). The description lacks context about prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a draft
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the draft to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description should disclose behavioral traits. It only states the basic action, omitting whether deletion is permanent, requires permissions, or has side effects on related resources.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with one sentence, but it lacks structure and front-loading of key information. However, it is not verbose and avoids irrelevant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description is minimally adequate. However, it could mention whether the operation is reversible or if any confirmation is required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the parameter 'id' has a clear description in the schema. The description adds no additional meaning, but the schema already sufficiently documents the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Delete a draft' with a specific verb and resource. It is not a tautology and distinguishes from sibling tools like create_draft or send_draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., delete_message, trash_message). There are no prerequisites, exclusions, or use-case hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes a filter
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the filter to be deleted |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It does not state whether deletion is permanent, if there are side effects, or any authorization needs. This is insufficient for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at three words, front-loading the purpose. However, it sacrifices necessary detail, making it slightly too terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool with one parameter and no annotations or output schema, the description should at least indicate if it returns a response or side effects. It does not, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no extra meaning beyond the schema's parameter description. It does not provide any additional context about the parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Deletes a filter' with a specific verb and resource. It distinguishes from sibling tools like create_filter, get_filter, and list_filters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, no prerequisites or exclusions mentioned. The description entirely lacks usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes the specified forwarding address
| Name | Required | Description | Default |
|---|---|---|---|
| forwardingEmail | Yes | The forwarding address to be deleted |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description does not disclose any behavioral traits beyond the deletion action, such as irreversibility, permission requirements, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is front-loaded and efficient, but could include more context without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 param, no output schema, no annotations), the description lacks behavioral context and usage guidelines, making it incomplete for safe selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter 'forwardingEmail', which provides adequate detail. Description does not add additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Deletes' and resource 'specified forwarding address', distinguishing it from sibling tools like create_forwarding_address or get_forwarding_address.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., modifying or listing forwarding addresses). No mention of prerequisites such as the address existing or potential conflicts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a label
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the label to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose behavioral traits beyond the action itself, such as irreversibility, required permissions, or impacts on related resources (e.g., messages using the label). With no annotations provided, the description carries the full burden but fails to address these critical aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (three words) but lacks any informative content beyond the tool name. While concise, it does not earn its place by adding value; it merely restates the obvious.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input schema and lack of output schema, the description should still cover return values (e.g., success/failure), error conditions, or behavior for non-existent labels. It does not, leaving the agent with incomplete context for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the required parameter 'id', so the description adds no additional meaning. Schema description coverage is 100%, meeting the baseline for a score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the resource ('a label'), making the purpose obvious. However, it does not differentiate from sibling tools like 'patch_label' or 'update_label', which could confuse an AI agent choosing between modification and deletion operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., 'patch_label' for updates, 'batch_modify_messages' for bulk actions). There is no mention of prerequisites, side effects, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Immediately and permanently delete a message
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the message to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It states the message is deleted immediately and permanently, which are key behavioral traits. However, it does not mention irreversibility or side effects (e.g., cannot be undone), though 'permanent' strongly implies that. For a simple deletion, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: only five words. No unnecessary details. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description is nearly complete. It covers the core functionality and permanence. Missing details like error handling (e.g., message not found) are minor, as such issues are implied by typical API behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'id', with a clear description. The tool description adds no extra meaning beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: delete a message immediately and permanently. This distinguishes it from sibling tools like trash_message (which likely soft-deletes) and untrash_message. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
While the description implies permanence, it does not explicitly state when to use this tool versus alternatives like trash_message. No exclusions or when-not-to-use guidance are provided. It relies on the user inferring that 'permanent' means this is for hard deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes the specified send-as alias
| Name | Required | Description | Default |
|---|---|---|---|
| sendAsEmail | Yes | The send-as alias to be deleted |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the action but omits behavioral traits like whether deletion is permanent, effects on other settings, or permissions required. This is insufficient for an agent to safely invoke the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no fluff. It is efficient but could benefit from additional context without being overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required param, no output schema, no annotations), the description minimally covers the action. However, it lacks completeness regarding side effects and error handling, which are important for a delete operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'sendAsEmail' clearly described as 'The send-as alias to be deleted'. The description repeats no param info, so the schema does the work. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Deletes' and the resource 'specified send-as alias', making it immediately obvious what the tool does. It also inherently distinguishes from sibling tools like 'create_send_as' or 'get_send_as'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool, prerequisites (e.g., alias must exist), or alternatives. Without context, an agent might misuse it or fail to handle error cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes the specified S/MIME config for the specified send-as alias
| Name | Required | Description | Default |
|---|---|---|---|
| sendAsEmail | Yes | The email address that appears in the 'From:' header | |
| id | Yes | The immutable ID for the S/MIME config |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description should disclose behavioral traits. It only states that deletion occurs, but does not mention irreversibility, impact on other settings, or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that efficiently states the action and resource. No unnecessary words or details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with well-described parameters, the description is adequate but could be improved by mentioning that the deletion is permanent or referencing related tools like set_default_smime_info.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes both parameters with clear descriptions. The description adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'Deletes', the resource 'S/MIME config', and the alias context 'specified send-as alias'. It clearly distinguishes this from sibling tools like insert_smime_info, get_smime_info, list_smime_info, and set_default_smime_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool, prerequisites, or alternatives. It lacks any context about required permissions or conditions for deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a thread
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the thread to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present to indicate safety or destructiveness, and the description does not disclose behavioral traits beyond the basic action. For instance, it does not state whether deletion is irreversible, if it cascades to messages, or what happens to related resources. The description adds no value beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single phrase with no wasted words. It is front-loaded and efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema), the description covers the basic purpose but lacks behavioral details that would be helpful, such as the permanence of deletion or any side effects. It is minimally complete but could be improved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the input schema already describes the one parameter adequately. The description adds no additional meaning beyond what the schema provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Delete a thread'. It is specific enough to distinguish from siblings like 'trash_thread' and 'modify_thread', but could more explicitly note that this is a permanent deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not indicate when to use this tool versus alternatives like 'trash_thread', nor does it mention any prerequisites or side effects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a message attachment
| Name | Required | Description | Default |
|---|---|---|---|
| messageId | Yes | ID of the message containing the attachment | |
| id | Yes | The ID of the attachment |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description is minimal and does not disclose behavioral traits such as read-only nature or potential side effects. Annotations are absent, leaving the agent with no safety information beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundancy, and no extra information. Efficiently communicates the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is too brief. It fails to explain what the tool returns (e.g., attachment content, metadata, binary data), leaving a critical gap for an agent to understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage for both parameters, so the schema alone sufficiently explains each field. The description adds no extra semantic value beyond what the schema provides, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get a message attachment', matching the tool name and resource. It's concise and unambiguous, though it doesn't distinguish from other 'get' siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like get_message or list_messages. No context provided for prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gets auto-forwarding settings
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only states the basic action. It does not confirm that the operation is read-only, mention any permissions, or describe side effects, leaving the agent with minimal insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence conveys the purpose without any extra words. It is perfectly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no parameters, the description is minimal. While it is functional, it could be improved by hinting at the structure or common fields of the auto-forwarding settings, but it meets the minimum for a simple getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so schema coverage is trivially 100%. The description adds no further meaning, but as per calibration guidelines, 0 parameters gives a baseline of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Gets auto-forwarding settings' clearly states the action (gets) and the resource (auto-forwarding settings), distinguishing it from siblings like update_auto_forwarding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_forwarding_address or update_auto_forwarding. The description lacks context for choosing this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gets the specified delegate
| Name | Required | Description | Default |
|---|---|---|---|
| delegateEmail | Yes | The email address of the delegate to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation ('Gets'), but without annotations, it does not explicitly state behavioral traits like idempotency, auth requirements, or side effects. It is minimally adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence with no wasted words. Front-loads the action and resource efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get operation with one parameter and no output schema, the description does not specify what is returned. It is adequate but could be more complete by hinting at the return value or structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear parameter description in the schema. The tool description adds no extra meaning beyond what the schema already provides, so baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Gets') and the resource ('the specified delegate'), distinguishing it from siblings like list_delegates (list all) and remove_delegate (delete).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or when not to use. The purpose is implied by the parameter (delegateEmail) and sibling context, but the description lacks explicit alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a specific draft by ID
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the draft to retrieve | |
| includeBodyHtml | No | Whether to include the parsed HTML in the return for each body, excluded by default because they can be excessively large |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description should disclose behavioral traits like read-only nature or side effects. It only states the basic purpose, omitting any behavioral specifics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with key information. While very concise, it could be slightly more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a simple retrieval tool with no output schema, the description should at least hint at the return value or behavior. It lacks completeness for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The tool description adds no additional meaning beyond the schema, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (get) and resource (draft by ID). However, it does not explicitly distinguish itself from sibling tools like list_drafts or get_message, relying on the tool name for differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., list_drafts for all drafts). The description lacks context for appropriate usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gets a filter
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the filter to be fetched |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. 'Gets a filter' is too minimal; it does not state that the operation is read-only, mention any required permissions, or describe the return value or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (three words), which is concise but not sufficiently informative. It lacks structure and fails to convey necessary details, making it inadequate despite its brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even for a simple tool with one parameter and no output schema, the description should specify the type of filter or what the return is. It is incomplete and does not provide enough context for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters, and the description adds no additional meaning beyond the schema's 'id' description. Baseline 3 is appropriate since schema does the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Gets' and resource 'a filter', which is clear but generic. It does not differentiate from sibling tools like 'get_draft' or 'get_label', so the purpose is only moderately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. With siblings like 'list_filters' and 'delete_filter', the description lacks any usage context or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gets the specified forwarding address
| Name | Required | Description | Default |
|---|---|---|---|
| forwardingEmail | Yes | The forwarding address to be retrieved |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits. It only states 'Gets' implying read-only, but lacks details on error behavior, auth requirements, or what happens if the address does not exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no redundancy. For a simple getter, this is appropriately minimal and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 param, no output schema), the description is minimally sufficient but could mention return type or common error scenarios for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for the single parameter is 100% and the description adds nothing beyond the schema. Baseline 3 is appropriate as the schema already documents the parameter adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'gets' and the resource 'forwarding address', making the purpose unambiguous. However, it does not differentiate from sibling 'get_*' tools beyond the resource name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like get_auto_forwarding or list_forwarding_addresses. The description gives no context about prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gets IMAP settings
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description implies a safe read operation but does not explicitly disclose side effects or permissions. Minimal transparency for a simple getter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with no wasted words, but could be slightly more descriptive without hurting brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks information about return values, prerequisites, or what 'IMAP settings' entails. For a tool with no output schema, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. Baseline score of 4 applies as no additional parameter info is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Gets IMAP settings' clearly states the verb and resource, distinguishing it from sibling tools like update_imap and other get_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, no prerequisites or context about IMAP setup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a specific label by ID
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the label to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description does not disclose behavioral traits such as permissions, rate limits, or side effects, leaving the agent to assume it is a simple read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence with no wasted words, conveying the essential information efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, no annotations), the description is minimally sufficient but lacks any background on labels or prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the parameter 'id' is described adequately in the schema; the tool description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('get'), the resource ('label'), and the selection criterion ('by ID'), effectively distinguishing it from sibling tools like list_labels or update_label.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives is provided, though the purpose is obvious enough for a single-resource retrieval; it could mention that list_labels retrieves all labels.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gets language settings
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must convey behavioral traits. It states 'Gets' which implies a read-only, non-destructive operation. However, it lacks confirmation of no side effects, authorization needs, or any rate limits. The transparency is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—only three words—with no redundant information. Every word is necessary, and it is front-loaded with the core purpose. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters, no output schema, and no annotations, the description is minimally complete. It tells the agent what the tool does, but could be improved by specifying the scope (e.g., current user's language settings). Given the abundance of sibling get tools, more context would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and the schema description coverage is 100% (vacuously). The description adds no extra meaning beyond the schema, but baseline for 0 parameters is 4, as no parameter documentation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Gets language settings' clearly identifies the action (gets) and resource (language settings). It is specific enough to distinguish from other get tools like get_profile or get_vacation, but does not elaborate on which language settings are targeted, which could be ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not mention when to use this tool versus alternatives such as update_language, nor does it specify context like prerequisites or typical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a specific message by ID with format options
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the message to retrieve | |
| includeBodyHtml | No | Whether to include the parsed HTML in the return for each body, excluded by default because they can be excessively large |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of transparency. It correctly indicates a read operation ('Get') but does not disclose other behavioral traits such as required permissions, error cases, or any side effects. Minimal but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at 8 words, with no wasted text. It front-loads the key action. However, it could include slightly more structure or context (e.g., mentioning the optional parameter) without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic functionality but lacks information about return format, error handling, or result limits. Given the absence of an output schema and the presence of many sibling tools, a bit more detail would be beneficial, though it is minimally sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are documented in the schema. The description only adds the vague phrase 'format options' without elaborating which parameter that corresponds to (likely includeBodyHtml). The schema itself provides sufficient detail, so the description adds little extra meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'message', specifying 'by ID' and mentioning 'format options'. It distinguishes itself from list-oriented siblings like 'list_messages' and other get tools for different resources, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you have a specific message ID but provides no explicit guidance on when to use this tool versus alternatives (e.g., list_messages, get_thread). No exclusions or comparative context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gets POP settings
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only says 'Gets' implying read-only, but does not disclose any behavioral traits (e.g., idempotency, caching, or permissions needed).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two-word description is concise and front-loaded, but could be slightly more descriptive without adding verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a parameterless getter, but lacks details on return value or format. Could mention that it fetches current POP settings, which is implied by sibling update_pop.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. Description adds nothing beyond the tool name, but baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Gets POP settings', indicating a read operation on POP settings, distinct from sibling getters like get_imap or get_auto_forwarding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this tool versus alternatives. Does not mention prerequisites, side effects, or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current user's Gmail profile
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a read operation ('Get') but does not disclose further behavioral traits such as authentication requirements or what the profile contains. With no annotations, the description carries the burden but is minimally adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words, front-loading the key action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description is adequate but incomplete—it does not mention what fields are returned in the profile, which would help an agent understand the output without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty (no parameters), so schema description coverage is 100%. The description adds no additional parameter information, but no parameters exist, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the specific resource 'current user's Gmail profile', which is distinct from sibling get_ tools that target specific sub-resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives; usage is implied as the go-to for retrieving the user's profile, but no exclusions or context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gets the specified send-as alias
| Name | Required | Description | Default |
|---|---|---|---|
| sendAsEmail | Yes | The send-as alias to be retrieved |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation through 'Gets', but with no annotations provided, it does not disclose additional traits like required permissions or side effects. Adequate for a simple getter, but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence of 7 words with no filler. All text is relevant to the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, no output schema), the description is adequate but does not explain what is returned or the need for the alias to exist. Minor gaps for a complete picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds only 'to be retrieved', which echoes the schema description. No extra meaning beyond the schema, so baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Gets the specified send-as alias' uses a specific verb (Gets) and resource (send-as alias), clearly distinguishing it from sibling tools like list_send_as or create_send_as.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives such as list_send_as or verify_send_as. The description lacks context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gets the specified S/MIME config for the specified send-as alias
| Name | Required | Description | Default |
|---|---|---|---|
| sendAsEmail | Yes | The email address that appears in the 'From:' header | |
| id | Yes | The immutable ID for the S/MIME config |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Absent annotations (readOnlyHint, destructiveHint), the description merely says 'Gets', implying a read operation, but does not disclose behavioral traits like what happens if the config does not exist, authorization requirements, or side effects. The agent is left to infer behavior from the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it is slightly vague ('the specified S/MIME config') and could be more front-loaded with the key action and resource. Still, it is efficient and avoids unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description is insufficiently complete. It fails to mention the return format, error handling, or how the S/MIME config is scoped to the send-as alias. Given the tool's simplicity, more detail would aid reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described. The description adds no meaning beyond the schema; it does not clarify the relationship between sendAsEmail and id or specify format constraints. Baseline 3 is appropriate since schema covers the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it 'Gets the specified S/MIME config for the specified send-as alias', identifying the specific verb (gets), resource (S/MIME config), and scope (by send-as alias). It effectively distinguishes from siblings like insert_smime_info, delete_smime_info, and list_smime_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as list_smime_info for retrieving all configs or insert_smime_info for creating new ones. There are no prerequisites, exclusions, or context for conditional use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a specific thread by ID
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the thread to retrieve | |
| includeBodyHtml | No | Whether to include the parsed HTML in the return for each body, excluded by default because they can be excessively large |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description alone must disclose behavior. It only states the purpose, omitting what the response contains, side effects, or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff. Every word contributes to the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and the description does not explain the return value (e.g., thread structure). In a server with many sibling tools, this lack of detail may hinder correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage for both parameters. The description does not add any additional meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (get), resource (thread), and method (by ID). It distinguishes from sibling tools like get_message or get_draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as list_threads or modify_thread. The description is purely declarative without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get vacation responder settings
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only states the action without any details on authentication, permissions, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a single sentence, but it could be slightly more informative without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with no parameters, the description is minimally adequate, but it lacks any information about the output or what settings are included.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the description does not need to add parameter information. A baseline score of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get vacation responder settings' provides a specific verb and resource, clearly distinguishing it from sibling tools like 'update_vacation' and 'get_auto_forwarding'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use or not use this tool, nor any mention of prerequisites or alternatives, despite the presence of many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert (upload) the given S/MIME config for the specified send-as alias
| Name | Required | Description | Default |
|---|---|---|---|
| sendAsEmail | Yes | The email address that appears in the 'From:' header | |
| encryptedKeyPassword | Yes | Encrypted key password | |
| pkcs12 | Yes | PKCS#12 format containing a single private/public key pair and certificate chain |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description fails to disclose behavioral traits such as whether the operation is idempotent, whether it replaces existing config, or any permission requirements. For a mutation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that efficiently communicates the tool's purpose without any redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description should provide more context about success/error behavior, how the S/MIME config relates to send-as, and any side effects. It falls short.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all three parameters. The description adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (insert/upload), the resource (S/MIME config), and the context (for a send-as alias). It distinguishes from sibling tools like delete_smime_info, get_smime_info, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the delegates for the specified account
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states a read operation (list), which is transparent, but it does not disclose any behavioral traits such as permissions required, potential side effects, or return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. It is front-loaded with the key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and zero parameters, the description is minimal. It does not mention what the list contains, pagination, or ordering. For a simple list tool, this is adequate but could provide more detail about the output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so there is nothing to document. With 100% schema coverage and zero parameters, the description does not need to add parameter meaning beyond the schema; the baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists delegates for the specified account, using a specific verb ('Lists') and resource ('delegates'). It distinguishes from siblings like add_delegate (add), get_delegate (single), and remove_delegate (delete).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool vs alternatives like get_delegate. It implies a listing operation, but no exclusions or context for when to choose listing over retrieving a single delegate are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List drafts in the user's mailbox
| Name | Required | Description | Default |
|---|---|---|---|
| maxResults | No | Maximum number of drafts to return. Accepts values between 1-500 | |
| q | No | Only return drafts matching the specified query. Supports the same query format as the Gmail search box | |
| includeSpamTrash | No | Include drafts from SPAM and TRASH in the results | |
| includeBodyHtml | No | Whether to include the parsed HTML in the return for each body, excluded by default because they can be excessively large |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must bear the full burden. It fails to disclose any behavioral traits (e.g., read-only nature, response structure, pagination). The agent cannot infer safety or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently communicates the tool's purpose. It is front-loaded and contains no unnecessary information, though it could benefit from additional context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 optional parameters, no output schema, and no annotations, the description is incomplete. It does not explain how to effectively use parameters like 'q' or 'includeBodyHtml', nor the expected return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 4 parameters, so the baseline is 3. The tool description adds no additional meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List drafts in the user's mailbox' with a specific verb and resource. It distinguishes from sibling tools like list_messages by targeting drafts, though it could be more explicit about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., get_draft, list_messages). No exclusions or context provided, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the message filters of a Gmail user
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a read operation, but with no annotations, it fails to disclose additional behavioral traits such as pagination, permissions required, or whether it returns all filters. The description adds minimal value beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the key information. Every word is necessary and there is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately states the tool's purpose but omits details about the return value (e.g., that it returns a list of filter objects). Given the absence of an output schema, this gap reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters with 100% coverage. The description does not need to explain parameters further, and its meaning is clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('lists'), the resource ('message filters'), and the scope ('of a Gmail user'). It distinguishes this tool from sibling list tools like list_labels and list_messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, use cases, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the forwarding addresses for the specified account
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only states the basic action. It does not mention whether results are paginated, what authentication is required, or any side effects. The read-only nature is implied but not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is front-loaded and immediately communicates the tool's action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, no output schema), the description is adequate but lacks depth. It does not explain what the output contains or any constraints (e.g., account scope). Additional context about return format or pagination would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and schema description coverage is 100%. Since there are no parameters to document, the description adds no additional meaning, which is acceptable. A baseline of 4 is appropriate for a no-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Lists' and the resource 'forwarding addresses for the specified account', making the purpose unmistakable. However, it does not differentiate from sibling list tools like list_filters or list_labels, which are similarly named but operate on different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_forwarding_address (singular) or create_forwarding_address. The description lacks context about prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all labels in the user's mailbox
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It indicates a safe read operation but lacks details about potential rate limits, ordering, or pagination. The description is minimal and does not disclose any behavioral traits beyond the basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no extraneous words. It is front-loaded and every word contributes to the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (no params, no output schema), the description is complete in stating its core purpose. However, it lacks details about the return format or any limitations, which would be helpful for an agent. The description is adequate but not fully informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is trivially 100%. Per guidelines, a baseline of 4 is assigned since no parameter information is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'list', the resource 'labels', and the scope 'user's mailbox'. This clearly distinguishes it from sibling tools like create_label, delete_label, and get_label.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives, nor does it mention when not to use it or prerequisites. It simply states what it does, leaving the agent to infer the context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List messages in the user's mailbox with optional filtering
| Name | Required | Description | Default |
|---|---|---|---|
| maxResults | No | Maximum number of messages to return. Accepts values between 1-500 | |
| pageToken | No | Page token to retrieve a specific page of results | |
| q | No | Only return messages matching the specified query. Supports the same query format as the Gmail search box | |
| labelIds | No | Only return messages with labels that match all of the specified label IDs | |
| includeSpamTrash | No | Include messages from SPAM and TRASH in the results | |
| includeBodyHtml | No | Whether to include the parsed HTML in the return for each body, excluded by default because they can be excessively large |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure, but it only mentions 'optional filtering' without explaining key behaviors like pagination, rate limits, or return format. This is insufficient for an agent to understand what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (one sentence) but lacks structure and detail. While concise, it could be improved with brief examples or hints about common use cases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema covers parameters well, but the description does not explain the return value (e.g., list of message summaries) or pagination behavior. For a tool with 6 parameters and no output schema, more context is needed for complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters have complete descriptions in the input schema (100% coverage), so the description adds no additional meaning. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list messages) and scope (user's mailbox) with optional filtering. However, it does not differentiate from sibling tools like list_drafts or list_threads, which could cause ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., get_message for a single message, batch_delete for deletions). The description lacks any usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the send-as aliases for the specified account
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry full burden. It only states the action, lacking details on pagination, ordering, scope requirements, side effects, or behavior for empty results. For a read operation, minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise and front-loaded with key action and resource. No wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is too sparse. Missing details on return format, pagination, error conditions, or whether it lists all aliases or active ones. Adequate for a trivial tool but incomplete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0 parameters and description coverage is 100%. Description implicitly conveys that no parameters are needed (account inferred from context). While it doesn't explain why, it is sufficient given the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Lists' and resource 'send-as aliases' with context 'for the specified account'. However, it does not clarify how the account is specified given the empty input schema (no parameters). Sibling 'get_send_as' suggests listing vs getting, but not explicitly differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings like 'get_send_as', 'create_send_as', or 'delete_send_as'. Missing context on prerequisites, authorization, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists S/MIME configs for the specified send-as alias
| Name | Required | Description | Default |
|---|---|---|---|
| sendAsEmail | Yes | The email address that appears in the 'From:' header |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only says 'lists'. It does not disclose read-only nature, required permissions, error behavior, or return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundancy, perfectly concise for the information conveyed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple list operation, but missing details like whether it returns all configs and any pagination. Could be improved by noting difference from get_smime_info.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes the parameter. The description adds no extra meaning beyond 'specified alias', so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists S/MIME configs for a specified send-as alias, using a specific verb and resource. It distinguishes from siblings like get_smime_info (singular) and insert_smime_info (create).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as get_smime_info, insert_smime_info, or delete_smime_info. The description does not mention exclusions or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List threads in the user's mailbox
| Name | Required | Description | Default |
|---|---|---|---|
| maxResults | No | Maximum number of threads to return | |
| pageToken | No | Page token to retrieve a specific page of results | |
| q | No | Only return threads matching the specified query | |
| labelIds | No | Only return threads with labels that match all of the specified label IDs | |
| includeSpamTrash | No | Include threads from SPAM and TRASH in the results | |
| includeBodyHtml | No | Whether to include the parsed HTML in the return for each body, excluded by default because they can be excessively large |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only says 'List threads' without disclosing behavior like ordering, authentication requirements, or whether it is read-only. It fails to add behavioral context beyond the minimal purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded and contains no unnecessary words. It efficiently states the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal given the tool has 6 parameters, no output schema, and no annotations. It does not explain return values, ordering, defaults, or how threads are defined, leaving the agent with incomplete context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so the schema already documents all parameters adequately. The description does not add any additional meaning beyond what is already in the schema, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool lists threads in the user's mailbox, using a specific verb and resource. It distinguishes from sibling tools like get_thread (single thread) and list_messages (messages, not threads).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_thread or list_messages. It does not mention any context for selection among many thread-related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Modify the labels on a message
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the message to modify | |
| addLabelIds | No | A list of label IDs to add to the message | |
| removeLabelIds | No | A list of label IDs to remove from the message |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only says 'modify the labels' without detailing behavior for conflicting add/remove, invalid IDs, or return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is concise and front-loaded, but could be expanded slightly for completeness without losing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lack of output schema and annotations, plus no description of return values or error handling, makes it incomplete for a simple mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing clear parameter descriptions. The description adds no extra meaning beyond the schema, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool modifies labels on a message, distinguishing it from siblings like batch_modify_messages and modify_thread.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool vs. alternatives (e.g., batch_modify_messages for multiple messages) or prerequisites like label existence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Modify the labels applied to a thread
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the thread to modify | |
| addLabelIds | No | A list of label IDs to add to the thread | |
| removeLabelIds | No | A list of label IDs to remove from the thread |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It only states 'modify the labels' without noting side effects, such as whether removing all labels deletes the thread or how adding/removing affects existing labels. The behavior is implied but not explicitly described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant information. It is front-loaded with the core action and resource, making it quick to parse and free of waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (3 parameters, no output schema), the description is mostly adequate but misses details like whether add and remove can be used simultaneously or if there is a limit on label count. It does not clarify if modifying the thread affects all messages within it, which is important context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three parameters (id, addLabelIds, removeLabelIds), so the schema already explains the parameters. The description 'Modify the labels applied to a thread' adds no additional meaning beyond the schema, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool modifies labels on a thread, specifying the verb 'modify' and the resource 'labels applied to a thread'. This distinguishes it from sibling tools like modify_message (which modifies message labels) and batch_modify_messages (which modifies multiple messages).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like modify_message or batch_modify_messages. There is no mention of prerequisites, when not to use it, or related tools, leaving the agent without decision support for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Patch an existing label (partial update)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the label to patch | |
| name | No | The display name of the label | |
| messageListVisibility | No | The visibility of messages with this label in the message list | |
| labelListVisibility | No | The visibility of the label in the label list | |
| color | No | The color settings for the label |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only says 'partial update'. It does not disclose idempotency, error behavior, or any side effects beyond the basic operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single sentence, front-loading the purpose. However, it could include slight expansion for clarity without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, nested objects, and no output schema, the description lacks sufficient context. It does not mention return values, error conditions, or comparison to update_label.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters are already described. The description adds the semantic hint that only provided fields are updated, which is valuable but minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Patch an existing label' using a standard verb for partial update, and specifies the resource. It distinguishes from siblings like create_label and update_label.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The term 'partial update' implies when to use this tool, but there is no explicit guidance on when to use update_label instead, nor any prerequisites or exclusions. The agent must infer from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Patches the specified send-as alias
| Name | Required | Description | Default |
|---|---|---|---|
| sendAsEmail | Yes | The send-as alias to be updated | |
| displayName | No | A name that appears in the 'From:' header | |
| replyToAddress | No | An optional email address that is included in a 'Reply-To:' header | |
| signature | No | An optional HTML signature | |
| isPrimary | No | Whether this address is the primary address | |
| treatAsAlias | No | Whether Gmail should treat this address as an alias |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It only says 'patches', which implies a partial update, but does not mention authentication requirements, idempotency, failure scenarios, or side effects. This is insufficient for an agent to understand the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of a single sentence that front-loads the action and resource. However, given the number of parameters and sibling tools, slightly more context (e.g., 'partial update') would benefit without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description does not explain the partial update behavior, mention the output (no output schema), or provide any context about which fields are updatable. For a tool with six parameters and many siblings, this is under-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, documenting all six parameters. The description adds no additional meaning beyond what is in the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'patches' and the resource 'send-as alias', making the purpose clear. However, it does not differentiate from the sibling tool 'update_send_as', which might imply a full update. A distinction between partial (patch) and full update would improve clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as 'update_send_as' or 'create_send_as'. No context or exclusions are given, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Removes the specified delegate
| Name | Required | Description | Default |
|---|---|---|---|
| delegateEmail | Yes | Email address of delegate to remove |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden for behavioral transparency. It only states the action without disclosing effects like whether removal is immediate, reversible, or requires permissions. Missing critical traits for a destructive tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but underspecified. It sacrifices necessary detail for brevity, making it insufficient for effective use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description fails to explain return values, side effects, or confirmation of removal. It is incomplete for a deletion operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear parameter description for 'delegateEmail'. The tool description adds no extra meaning beyond 'delegate', so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Removes the specified delegate' clearly states the action and object, but lacks differentiation from sibling delegate tools like 'add_delegate' or 'list_delegates'. The verb 'removes' makes the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like 'add_delegate' or 'get_delegate'. There is no mention of prerequisites, when not to use, or context for removal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send an existing draft
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the draft to send |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description fails to disclose behavioral traits such as side effects (e.g., draft deletion after sending), authorization requirements, or error conditions. The agent has minimal insight beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no waste. However, it lacks structure (e.g., no separation of purpose and usage).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description provides minimal context. It omits information about what happens after sending (e.g., draft status change) and potential failure modes, leaving gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions, so baseline is 3. The description adds no extra meaning beyond what the schema already provides for the 'id' parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Send' and resource 'existing draft', distinguishing from siblings like create_draft and delete_draft. However, it does not explicitly differentiate from send_message, which could cause confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use send_draft versus alternatives like send_message or create_draft. There are no prerequisites or exclusions mentioned, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send an email message to specified recipients. Note the mechanics of the raw parameter.
| Name | Required | Description | Default |
|---|---|---|---|
| raw | No | The entire email message in base64url encoded RFC 2822 format, ignores params.to, cc, bcc, subject, body, includeBodyHtml if provided | |
| threadId | No | The thread ID to associate this message with | |
| to | No | List of recipient email addresses | |
| cc | No | List of CC recipient email addresses | |
| bcc | No | List of BCC recipient email addresses | |
| subject | No | The subject of the email | |
| body | No | The body of the email | |
| includeBodyHtml | No | Whether to include the parsed HTML in the return for each body, excluded by default because they can be excessively large |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only states the basic action. It omits critical details like authentication requirements, failure modes, or whether the message is actually sent immediately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but includes an uninformative note. It could be more concise while being more helpful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters and no output schema, the description is insufficient. It does not explain return values, the interplay between raw and other parameters, or any side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds only a vague note about the 'raw' parameter, which does not provide meaningful additional context beyond what the schema already explains.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the main function: sending an email message to recipients. It distinguishes from sibling tools like create_draft or send_draft, though it lacks specificity about the platform (e.g., Gmail).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs. alternatives (e.g., send_draft) or when not to use it. The note about the 'raw' parameter is vague and does not clarify usage trade-offs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sets the default S/MIME config for the specified send-as alias
| Name | Required | Description | Default |
|---|---|---|---|
| sendAsEmail | Yes | The email address that appears in the 'From:' header | |
| id | Yes | The immutable ID for the S/MIME config |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral traits. It fails to disclose whether the operation is idempotent, if it overrides an existing default, what happens if the config doesn't exist, or any required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded and efficient. However, it could incorporate additional context without becoming overly verbose, such as specifying that the config must already exist.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two required parameters and no output schema. The description covers the core purpose but lacks behavioral details and differentiation from siblings. It is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, defining sendAsEmail and id. The description adds no further meaning beyond the schema, which is sufficient for a baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (sets) and the resource (default S/MIME config) with context (for a send-as alias). It differentiates from siblings like insert_smime_info and delete_smime_info, but does not explicitly contrast them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like insert_smime_info or list_smime_info. The description implies setting a default, but does not specify prerequisites or scenarios where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop receiving push notifications for the given user mailbox
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must cover behavioral traits. It only states the basic action, missing details like whether a watch must be active, error states, or authorization needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded, no wasted words. Perfectly concise for the action described.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters or output schema, the description provides minimal but adequate information for a stop action. However, it lacks details on side effects, prerequisites, and response behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters, so the description adds value by explaining the function (stopping notifications). Yet, it does not explain how the mailbox is identified (likely implicit from context).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it stops push notifications for a user mailbox (specific verb+resource). However, it does not explicitly distinguish from sibling tools like watch_mailbox beyond being the inverse, leaving some ambiguity about context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., it pairs with watch_mailbox). Lacks instructions on prerequisites or conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a message to the trash
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the message to move to trash |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fails to disclose consequences such as reversibility, permission requirements, or side effects on labels. For a mutation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant words, front-loaded, and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple schema and no output schema, the description is minimally complete but lacks behavioral context compared to siblings like delete_message. It could mention recoverability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the 'id' parameter with 100% coverage. The description does not add meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Move') and resource ('a message') with the destination ('to the trash'), distinguishing it from siblings like delete_message (permanent) and untrash_message (reverse).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives like delete_message or untrash_message. It is implied for soft deletion, but no explicit context or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a thread to the trash
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the thread to move to trash |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided and description lacks details on side effects, reversibility, or permissions. Only states basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words, front-loaded with essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Minimal for a mutation tool with no output schema or annotations. Does not explain what 'trash' means or its effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter 'id', so baseline applies. Description adds no extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'move' and the resource 'thread to trash', distinguishing it from siblings like delete_thread and trash_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this tool versus alternatives like delete_thread or trash_message.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a message from the trash
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the message to remove from trash |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully convey behavioral traits. It only states the core action without disclosing side effects (e.g., restored location, label restoration) or any prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. It communicates the tool's purpose efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (single parameter) and absence of an output schema, the description is minimally complete. However, it lacks context about the result of the operation (e.g., message restored to original folder) and how it interacts with sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter 'id' is adequately described in the schema. The description does not add additional meaning beyond what the schema provides, but the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('remove') and the resource ('a message from the trash'), distinguishing it from sibling tools like 'trash_message' (move to trash) and 'delete_message' (permanent deletion).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as trash_message or delete_message. The description does not provide context for its appropriate use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a thread from the trash
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the thread to remove from trash |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It describes the action simply but lacks details on side effects, permissions, or reversibility. The action is straightforward, so minimal disclosure is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no unnecessary words. Every part is essential and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is sufficient. It could mention being the inverse of 'trash_thread' but is complete enough for an agent to understand its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the 'id' parameter completely. The description adds no additional meaning beyond what the schema provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Remove' and the resource 'a thread from the trash', distinguishing it from sibling tools like 'untrash_message' by specifying thread.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly mention when to use this tool versus alternatives like 'trash_thread' or 'delete_thread', though the context implies it reverses trash. No explicit when-not or alternatives provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Updates automatic forwarding settings
| Name | Required | Description | Default |
|---|---|---|---|
| enabled | Yes | Whether all incoming mail is automatically forwarded to another address | |
| emailAddress | Yes | Email address to which messages should be automatically forwarded | |
| disposition | Yes | The state in which messages should be left after being forwarded |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description gives no behavioral details (e.g., idempotency, side effects, permissions). The agent has no insight beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (5 words) but lacks necessary context. It is front-loaded but overly minimal, sacrificing completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, no annotations, and a minimal description, the tool definition is incomplete. An agent needs more context about the behavior and return values to use this tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage with clear explanations for each parameter, including an enum for disposition. The description adds no value beyond what the schema already provides, so it meets the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Updates') and resource ('automatic forwarding settings'), making the purpose evident. However, it does not differentiate from sibling tools like get_auto_forwarding, but the name itself implies mutation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_auto_forwarding or create_forwarding_address. The description lacks context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Updates IMAP settings
| Name | Required | Description | Default |
|---|---|---|---|
| enabled | Yes | Whether IMAP is enabled for the account | |
| expungeBehavior | No | The action that will be executed on a message when it is marked as deleted and expunged from the last visible IMAP folder | |
| maxFolderSize | No | An optional limit on the number of messages that can be accessed through IMAP |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only says 'Updates', implying mutation, but omits details like whether changes are immediate, require account reconnection, or have side effects on existing sessions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short but not packed with information. It could be expanded to include important context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 3 parameters and no output schema, the description is too minimal. It lacks information about success/failure responses, required permissions, and relationship to related tools like 'get_imap'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions, so the description itself adds no new meaning. Baseline 3 is appropriate as the description does not augment the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it updates IMAP settings. The verb 'Updates' and resource 'IMAP settings' are specific, but it doesn't differentiate from sibling tools like 'update_pop' or 'get_imap'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., 'get_imap' for reading, 'update_pop' for POP). Missing context on prerequisites or effects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing label
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the label to update | |
| name | No | The display name of the label | |
| messageListVisibility | No | The visibility of messages with this label in the message list | |
| labelListVisibility | No | The visibility of the label in the label list | |
| color | No | The color settings for the label |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description only says 'Update an existing label' without any behavioral details such as whether it replaces all fields, requires the label to exist, or returns a response. This is highly insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
While very short, the description is under-specified and fails to provide necessary context. Conciseness should not come at the cost of completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, nested objects, no output schema, and no annotations, the description is grossly incomplete. It does not mention which fields can be updated (name, visibility, color) or any other critical context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds no additional meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Update' and the resource 'existing label', which is distinct from create, delete, or get operations. However, it does not explicitly differentiate from 'patch_label' which may be a partial update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like patch_label, or any prerequisites. The description is too minimal to direct correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Updates language settings
| Name | Required | Description | Default |
|---|---|---|---|
| displayLanguage | Yes | The language to display Gmail in, formatted as an RFC 3066 Language Tag |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose behavioral traits. It only states 'updates' but does not mention whether the operation is reversible, requires authentication, or has side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and concise. However, it could provide slightly more informative content without compromising brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool with one parameter and no output schema, the description is complete in a minimal sense but lacks context about the update behavior, default values, or what the response looks like.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single parameter, including a description of the RFC 3066 Language Tag format. The tool description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Updates language settings' clearly indicates the action (update) and resource (language settings). It distinguishes from sibling tools like 'get_language' (read) and other update tools for different settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as 'get_language' for reading or other update tools. No prerequisites or context for use are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Updates POP settings
| Name | Required | Description | Default |
|---|---|---|---|
| accessWindow | Yes | The range of messages which are accessible via POP | |
| disposition | Yes | The action that will be executed on a message after it has been fetched via POP |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is the sole source of behavioral context. It only states 'Updates POP settings', implying mutation, but omits details on required permissions, side effects (e.g., whether existing settings are overwritten), error conditions, or response behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. While it is brief, it directly states the purpose. It could benefit from slight expansion, but it remains appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and annotations, the description is incomplete. It does not explain what happens after an update (e.g., return value), does not mention any constraints or ordering of parameters, and lacks any contextual information about the mailbox or account settings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters with detailed descriptions and enums (100% coverage). The description adds no additional parameter meaning beyond what the schema already provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (updates) and resource (POP settings), distinguishing it from sibling tools like get_pop or update_imap. However, it is minimal and does not elaborate on what POP settings entail, which would help further clarify its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as update_imap or update_auto_forwarding. It lacks context on prerequisites, typical use cases, or any when-not-to-use indications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Updates a send-as alias
| Name | Required | Description | Default |
|---|---|---|---|
| sendAsEmail | Yes | The send-as alias to be updated | |
| displayName | No | A name that appears in the 'From:' header | |
| replyToAddress | No | An optional email address that is included in a 'Reply-To:' header | |
| signature | No | An optional HTML signature | |
| isPrimary | No | Whether this address is the primary address | |
| treatAsAlias | No | Whether Gmail should treat this address as an alias |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It merely states 'Updates', implying mutation, but fails to disclose any behavioral traits such as required permissions, idempotency, side effects, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It is concise and front-loaded, though it sacrifices completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters and no output schema or annotations, the description is too minimal. It lacks information about return values, error states, or any behavioral context that would help an agent use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all parameters already clearly described in the input schema. The description adds no additional meaning or context beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Updates' and the resource 'send-as alias', making the action clear. However, it does not distinguish this tool from its sibling 'patch_send_as', which likely performs a similar update operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'patch_send_as' or 'create_send_as'. There is no mention of prerequisites, context, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update vacation responder settings
| Name | Required | Description | Default |
|---|---|---|---|
| enableAutoReply | Yes | Whether the vacation responder is enabled | |
| responseSubject | No | Optional subject line for the vacation responder auto-reply | |
| responseBodyPlainText | Yes | Response body in plain text format | |
| restrictToContacts | No | Whether responses are only sent to contacts | |
| restrictToDomain | No | Whether responses are only sent to users in the same domain | |
| startTime | No | Start time for sending auto-replies (epoch ms) | |
| endTime | No | End time for sending auto-replies (epoch ms) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only says 'Update', implying mutation, but does not explain whether the update merges or overrides, if authentication is required, or what side effects occur. This lack of detail impairs safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence that is efficient and easy to parse. It is appropriately front-loaded, but for a tool with 7 parameters, a bit more context could be added without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, and the moderate complexity of 7 parameters, the description is insufficient. It omits information on return values, idempotency, and how omitted optional parameters are handled, leaving gaps for reliable use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema description coverage is 100%, the baseline is 3. The tool description adds no extra meaning beyond the existing parameter descriptions, so it neither harms nor improves semantic clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update vacation responder settings' clearly states the verb and resource, making the tool's purpose immediately understandable. It distinguishes from sibling tools like get_vacation (read) and other update tools (e.g., update_auto_forwarding) by specifying 'vacation responder', but does not explicitly differentiate among them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, when it is appropriate, or warn against misuse, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sends a verification email to the specified send-as alias
| Name | Required | Description | Default |
|---|---|---|---|
| sendAsEmail | Yes | The send-as alias to be verified |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It only states the action, omitting side effects (e.g., email sent to alias owner), required state (alias must be unverified), or outcome (e.g., user must follow link). Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence with no wasted words. Information is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks critical context: no mention of return value, error states (e.g., alias already verified), or required user steps. Despite simplicity of the action, the description is incomplete for an agent to understand full implications.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter sendAsEmail is described in the schema as 'The send-as alias to be verified.' The description does not add extra meaning or format details beyond the schema. With 100% schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Sends a verification email') and the target resource ('to the specified send-as alias'). It uniquely identifies the tool's purpose among siblings like create_send_as or get_send_as, which focus on other operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description implies usage when verification is needed, but lacks context such as prerequisites (alias existence, unverified status) or comparative notes with other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Watch for changes to the user's mailbox
| Name | Required | Description | Default |
|---|---|---|---|
| topicName | Yes | The name of the Cloud Pub/Sub topic to publish notifications to | |
| labelIds | No | Label IDs to restrict notifications to | |
| labelFilterAction | No | Whether to include or exclude the specified labels |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only states 'Watch for changes' without disclosing side effects (e.g., creating a subscription), permissions required, rate limits, or how to stop the watch. The behavioral impact is vague.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence with no wasted words. However, it is so concise that it omits important context, making it slightly less effective than a well-balanced description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters (including an enum) and no output schema, the description is insufficient. It does not explain the watch mechanism, return behavior, or relationship to sibling 'stop_mail_watch'. More detail is needed for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with clear descriptions for each parameter. The description adds no additional meaning beyond the schema, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Watch for changes to the user's mailbox' clearly identifies the verb (Watch) and resource (mailbox), distinguishing it from most sibling tools. However, it does not explicitly indicate that this tool starts a watch, which could be inferred from the sibling 'stop_mail_watch'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'stop_mail_watch' or other mailbox-related tools. The description lacks context about prerequisites, setup, or lifecycle.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct operation or resource (e.g., create_draft vs. send_draft vs. delete_draft), with clear descriptions preventing confusion. Even similar endpoints like list_messages and list_threads are unambiguously different.
Almost all tools follow the verb_noun pattern (e.g., create_label, delete_message), but minor variations like patch_label, set_default_smime_info, and verify_send_as break complete uniformity. This is acceptable but not perfect.
64 tools is on the high side, covering many Gmail features. While each tool has a role, the sheer number can overwhelm agents. However, the scope of Gmail justifies many endpoints, so it's borderline rather than excessive.
The tool surface covers all major Gmail operations: CRUD for labels, drafts, messages, threads, filters, forwarding, send-as, S/MIME, and settings (IMAP, POP, vacation, auto-forwarding, language, delegates). No obvious gaps for typical email management.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Manage Gmail end-to-end: search, read, send, draft, label, and organize threads. Automate workflow…
Manage Gmail messages, threads, labels, drafts, and settings from your workflows. Send and organiz…
AI email inbox and sending tools with attachments, search, live events, and webhooks.
Read, search, send, organize, draft and schedule email across your inboxes from any MCP client.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/shinzo-labs/gmail-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
