Allows connecting to a Gmail account, checking connection status, and sending emails through the connected account.
Click on "Deploy 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 AI Agent MCP Server Send email to bob@company.com subject Update body Check attached."
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 that provides Gmail integration capabilities for AI models and tools. This server enables AI assistants to connect to Gmail accounts, check connection status, and send emails through a secure interface.
The server implements the following Gmail-related tools:
connect-gmailInitiates a connection to a Gmail account. This tool will provide a redirect URL for OAuth authentication.
check-gmail-connectionChecks the current Gmail connection status and displays user profile information including email address, total messages, and total threads.
send-emailSends an email through the connected Gmail account. Parameters:
to: The email address of the recipient
subject: The subject of the email
body: The body content of the email
Related MCP server: gmail-mcp
Composio API Key: You'll need a Composio API key to use the Gmail integration. You can get one by signing up at Composio.
Gmail Account: A Gmail account that you want to connect to the AI agent.
You can configure the Gmail AI agent server in your MCP client. Here is an example configuration for Claude Desktop (Settings -> Developer -> Edit Config):
{
"mcpServers": {
"gmail-agent": {
"command": "node",
"args": ["path/to/your/gmail-mcp/dist/index.js"],
"env": {
"COMPOSIO_API_KEY": "<YOUR_COMPOSIO_API_KEY>"
}
}
}
}If you're running from source:
# Clone the repository
git clone <repository-url>
cd gmail-mcp
# Install dependencies
npm install
# Build the project
npm run build
# Run the server
npm startThen configure your MCP client to point to the built server:
{
"mcpServers": {
"gmail-agent": {
"command": "node",
"args": ["/path/to/gmail-mcp/dist/index.js"],
"env": {
"COMPOSIO_API_KEY": "<YOUR_COMPOSIO_API_KEY>"
}
}
}
}Configure the server in your MCP client (like Claude Desktop)
Restart your client to load the new configuration
Connect to Gmail by using the connect-gmail tool - this will provide an OAuth link
Authorize the connection by clicking the provided link and following the Gmail authorization flow
Check connection using check-gmail-connection to verify everything is working
Send emails using the send-email tool with recipient, subject, and body parameters
The server uses OAuth 2.0 for secure Gmail authentication
No passwords are stored locally
All Gmail operations are performed through secure API calls
The connection is maintained securely through Composio's infrastructure
Initial Setup: Use connect-gmail to start the OAuth flow
Verification: Use check-gmail-connection to confirm successful connection
Email Operations: Use send-email to compose and send emails through your connected Gmail account
Connection Issues: If you encounter connection problems, try using connect-gmail again to re-authenticate
API Key Issues: Ensure your Composio API key is correctly set in the environment variables
Permission Errors: Make sure you've granted the necessary permissions during the OAuth flow
Check Gmail connection status
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only says 'Check', implying read-only, but fails to disclose return value, error behavior (e.g., if not connected), or side effects. Inadequate for a tool with zero annotation coverage.
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 4-word sentence, front-loaded with purpose. No filler. Every word earns its place.
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?
Despite simplicity, description omits output specification and prerequisites. For a tool with no output schema and no annotations, the agent needs to know what the response looks like and if prior authentication is required. Incomplete.
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?
Zero parameters, schema coverage 100% (empty schema). Baseline 4 as per rule for 0 params. Description adds no parameter-specific info, but none 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?
Description clearly states verb+resource: 'Check Gmail connection status'. This distinguishes it from sibling tools like connect_gmail (establishes connection) and get_emails (data retrieval). No 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 on when to use this tool vs alternatives, no prerequisites (e.g., 'call connect_gmail first'), and no exclusions. The agent must infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Connect to Gmail
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description must disclose behavior. It only states 'Connect to Gmail' without explaining authentication, side effects, or prerequisites. The agent cannot infer what the connection entails.
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 phrase, which is concise but lacks sufficient detail to be valuable. It earns its place but does not convey necessary 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?
With no annotations, output schema, or detailed description, the tool is severely underdocumented. The description alone is completely inadequate for a tool that likely involves auth and state changes.
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?
Zero parameters exist and schema coverage is 100%, so the description does not need to add parameter info. Baseline 4 is appropriate as no negative impact.
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 'Connect' and resource 'Gmail', giving a clear basic purpose. However, it does not distinguish from sibling 'check_gmail_connection', which may overlap. The purpose is clear but lacks specificity.
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 vs alternatives like 'check_gmail_connection'. The description gives no context for usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Forward an email to other recipients
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | The email address to forward to | |
| emailId | Yes | The ID of the email to forward | |
| message | No | Additional message to include with the forward |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It does not disclose whether the original email is included, if message is appended, or any side effects like changing read status.
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 6 words with no unnecessary information. 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?
With no output schema, 3 parameters, and no annotations, the description lacks details on return values, error handling, or behavior. For a mutation tool, 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?
Schema coverage is 100%, so baseline is 3. The description does not add extra meaning beyond the schema's parameter descriptions, which are straightforward, so it neither improves nor hinders.
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 (forward) and resource (an email) and target (to other recipients). It distinguishes from 'reply_to_email' and 'send_email' by using the term 'forward', but could be more specific about the behavior (e.g., including original content).
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 like 'reply_to_email' or 'send_email'. The description does not mention prerequisites or error conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a specific email by ID
| Name | Required | Description | Default |
|---|---|---|---|
| emailId | Yes | The ID of the email to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic operation. It does not disclose any behavioral traits (e.g., read-only, auth requirements) beyond the action itself.
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 wasted words, front-loading the core purpose. It is efficient, though could benefit from slight expansion.
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 read tool with one parameter and no output schema, the description is adequate but does not mention what fields are returned (e.g., full email content vs. metadata), leaving some ambiguity.
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 'emailId'. The description adds no extra meaning beyond the schema, so 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 ('Get') and the resource ('specific email by ID'), distinguishing it from sibling tools like 'get_emails' (plural) and 'search_emails'.
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 'search_emails' or 'get_emails', nor any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get emails from inbox
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Gmail search query to filter emails | |
| labelIds | No | Array of label IDs to filter by | |
| maxResults | No | Maximum number of emails to retrieve (default: 10) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear the full burden of behavioral disclosure. The description only states 'Get emails from inbox' but does not clarify that this is a read-only operation, whether it fetches only basic fields or full email bodies, or any rate limits or auth requirements. It fails to convey the tool's safety profile.
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 at five words, fitting in one short sentence. It is front-loaded and easy to scan. However, it is so brief that 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 that the tool has 3 parameters, no output schema, and no annotations, the description is insufficiently complete. It does not explain what the returned data looks like (e.g., list of email objects), pagination behavior, or default order. The agent lacks context to effectively 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?
Schema description coverage is 100%, so the baseline is 3. The tool description adds no additional meaning beyond the schema, which already contains adequate descriptions for all three parameters (query, labelIds, maxResults).
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 emails from inbox' is clear in stating the tool retrieves emails. However, it does not differentiate from sibling tool 'get_email' (which likely retrieves a single email) or 'search_emails' (which may have different parameters). A more specific description like 'Get list of emails matching query from inbox' would improve 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?
The description provides no guidance on when to use this tool versus alternatives such as 'search_emails' or 'get_email'. There is no mention of prerequisites (e.g., being connected to Gmail), limitations, 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.
Get Gmail settings
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose behavioral traits beyond the action. Since no annotations are present, the description should explain aspects like read-only nature, authentication requirements, or the type of data returned. It fails to do so.
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 (two words) and front-loaded. Every word serves a purpose, 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?
For a simple tool with no parameters and no output schema, the description is minimally adequate. However, it does not clarify the return value or any side effects, which could be helpful for an agent to understand the tool's 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 tool has zero parameters, so schema coverage is trivially 100%. The description is adequate as there are no parameters to explain.
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 Gmail settings' clearly indicates the action (get) and resource (Gmail settings). It differentiates from sibling tools that perform other operations like sending emails or checking connections. However, it could be more specific about which settings are retrieved.
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 description lacks context such as prerequisites or comparison with other tools for similar purposes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark emails as read
| Name | Required | Description | Default |
|---|---|---|---|
| emailIds | Yes | Array of email IDs to mark as read |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description is a tautology, failing to disclose any behavioral traits like side effects, authentication needs, or reversibility.
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 it is under-specified rather than concise, lacking necessary details 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?
For a simple tool with no output schema, the description should provide more behavioral context; without annotations, it is inadequate 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?
Schema coverage is 100% and the parameter 'emailIds' already has a description in the schema; the tool description adds no additional meaning or context beyond that.
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 'Mark emails as read' uses a specific verb-resource combination and clearly distinguishes from siblings like mark_as_unread and move_to_trash.
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 prerequisites or scenarios for marking emails as read.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark emails as unread
| Name | Required | Description | Default |
|---|---|---|---|
| emailIds | Yes | Array of email IDs to mark as unread |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states the action is a mutation but does not disclose any side effects, permission requirements, or return behavior. Adequate but could be more informative.
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 wasted words. It is appropriately sized for the tool's simplicity.
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 nature of the tool (one parameter, no output schema), the description covers the core function. However, it lacks information about edge cases (e.g., marking already unread emails) or error handling, which would make it 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?
The input schema already documents the parameter 'emailIds' with 100% coverage. The description adds no extra meaning beyond the schema, so 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 (mark emails as unread) with a specific verb and resource, distinguishing it from the sibling tool 'mark_as_read' which does the opposite.
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 usage for marking emails as unread, and the sibling 'mark_as_read' provides a clear alternative. However, no explicit when-to-use or when-not-to-use guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move emails to trash
| Name | Required | Description | Default |
|---|---|---|---|
| emailIds | Yes | Array of email IDs to move to trash |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden but only states the basic action. It does not disclose whether the action is reversible, any required permissions, or side effects like label changes.
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 and front-loaded. However, for such a simple tool, it is appropriately sized; no wasted 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?
Given the tool's simplicity (one parameter, no output schema), the description is reasonably complete. It states the core action, but could add minor context like recovery from trash.
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%; the schema already describes the parameter. The description adds no 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?
Description clearly states the action (move) and resource (emails) with a specific destination (trash). It directly differentiates from sibling tools like mark_as_read or send_email.
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 permanent deletion or archiving. No mention of prerequisites or context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reply to an existing email
| Name | Required | Description | Default |
|---|---|---|---|
| emailId | Yes | The ID of the email to reply to | |
| message | Yes | The reply message content |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose whether the reply includes original content, sets reply headers, or any other behavioral details.
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, front-loaded, no wasted words. Could benefit from more detail but remains 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?
With no output schema and no annotations, the description is minimal. It lacks information about reply formatting, required actions before replying, or optional parameters like cc.
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 descriptions for both parameters. The tool description adds no extra meaning; 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 'Reply to an existing email' clearly states the verb (reply) and resource (email), distinguishing it from siblings like 'send_email' (new email) and 'forward_email'.
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 'forward_email' or 'send_email'. No prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search emails using Gmail search syntax
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Gmail search query (e.g., 'from:example@gmail.com', 'subject:meeting', 'is:unread') | |
| maxResults | No | Maximum number of results to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden of behavioral disclosure. It does not mention that the tool is read-only, whether it supports pagination, rate limits, or what the output format is. The description is too brief to inform an agent of expected behavior 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 a single, clear sentence with no redundant information. It is appropriately concise and front-loaded with the core 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?
For a search tool with 2 parameters, no output schema, and no annotations, the description is incomplete. It does not explain the return format, pagination behavior, or whether it retrieves full messages or just metadata. An agent would lack critical operational 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?
Schema description coverage is 100%, so the baseline is 3. The description adds no new meaning beyond the schema's parameter descriptions; it merely echoes the concept of Gmail search syntax already present in the query parameter description. No additional context is provided for 'maxResults'.
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 'Search emails using Gmail search syntax' clearly identifies the tool's function as searching emails with a specific syntax. The verb 'Search' is appropriate and distinguishes it from sibling tools like 'get_emails' or 'get_email', though it doesn't explicitly differentiate its capabilities.
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 'get_emails' or 'search_emails' (if there are multiple search tools). No context is given about prerequisites or conditions that favor this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send an email
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | The email address of the recipient | |
| body | Yes | The body of the email | |
| subject | Yes | The subject of the email |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden of behavioral disclosure. It does not mention any behavioral traits like authentication requirements, rate limits, or side effects, leaving the agent without important safety 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 extremely short (3 words), which is concise but lacks necessary detail. It is not front-loaded with critical information, and the minimalism comes at the cost of clarity and utility.
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 (3 parameters, no output schema, no annotations), the description should cover basic context like expected behavior or error handling. It fails to provide any completeness, leaving the agent with insufficient information for 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?
Since schema description coverage is 100%, baseline score is 3. The description adds no additional meaning beyond the input schema, failing to clarify parameter usage or constraints beyond what is already structured.
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 'Send an email' is a clear but very minimal statement of the tool's action. It uses a specific verb and resource, but it does not differentiate from siblings like forward_email or reply_to_email, making it only slightly above tautology.
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 forward_email or reply_to_email. The description lacks any context about preferred scenarios or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.1check_gmail_connectionconnect_gmailforward_emailget_emailget_emailsget_gmail_settingsmark_as_readmark_as_unreadmove_to_trashreply_to_emailsearch_emailssend_emailScored across 12 tools
Each tool has a clearly distinct purpose, with no overlap. Even get_emails and search_emails are differentiated by scope (inbox vs. general search).
All tool names follow a consistent verb_noun snake_case pattern (e.g., send_email, mark_as_read), making them predictable and easy to understand.
12 tools is well-scoped for a Gmail assistant, covering essential operations without being overwhelming or too sparse.
Covers core CRUD operations and email management, but lacks features like label management, draft creation, or permanent deletion, which are minor gaps.
Manage Gmail messages, threads, labels, drafts, and settings from your workflows. Send and organiz…
Connect any mailbox to Claude, ChatGPT & AI: read, send, reply, schedule & search emails.
Manage Gmail end-to-end: search, read, send, draft, label, and organize threads. Automate workflow…
Permissioned access to Gmail, Drive and Calendar via the user's own Google account