MCP Emails

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. Description adds valuable context: live scan, recent window, no storage between calls, sorting by recency, and limitations of message_count. No contradictions.

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 moderately long but well-structured with clear sections. It is front-loaded with the key purpose and includes important details without being overly verbose. Every sentence contributes.

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 (live scan, temporary results), the description is comprehensive. It explains what results include, limitations, and when to use constraints. Output schema exists but description still covers 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?

Schema covers 100% of parameters with descriptions. Description adds extra clarity for inbox_id (when to use vs. omit) and provides a realistic example for query. Adds moderate value beyond 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 explicitly states the tool searches for people by name or email fragment via live mailbox scan, distinguishing it clearly from tools like email_read or folder. It uses specific verbs and clarifies there is no stored contact list.

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?

Provides explicit guidance on when to omit vs. set inbox_id, warns about the live scan tradeoff (bounded window, not full history), and advises against carrying over inbox_id from unrelated turns. This helps correct tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses critical behavioral traits: IMAP draft_id changes on every update, signature embedding behavior, and send action transmitting stored body as-is to avoid signature doubling. This exceeds what annotations provide; the destructiveHint=false annotation contradicts the description's explicit 'delete permanently removes a draft' statement, making the description more transparent.

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 and front-loaded with the core purpose. It communicates multiple actions and key behaviors in a single paragraph without redundant information. Every sentence adds value for an agent.

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, the description does not explain what is returned by actions like 'list' (e.g., fields of draft objects). It covers behavioral caveats well but misses return value documentation, which is needed for agents to process results.

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 parameter descriptions. The tool description adds value by explaining the action enum and the behavior of draft_id (always use latest) and include_signature (skip for one-liners). This enhances understanding beyond the schema alone.

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 specifies the tool's purpose: managing draft messages with explicit actions (list, create, update, send, delete). It distinguishes from sibling tools like email_compose by focusing on draft lifecycle management, though it doesn't 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?

The description explains each action and provides a key caveat about IMAP draft_id changes, but it does not provide explicit guidance on when to use this tool versus alternatives like email_compose or email_read. The usage context is implied but not directly stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate the tool is not read-only or destructive. The description adds important behavioral context: signature appending behavior (including for replies/forwards), suppression via include_signature, and the interaction between body and html_body. No contradiction with annotations.

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 the key purpose front-loaded. Every sentence adds essential information without redundancy. Two sentences cover actions, signature behavior, and key options 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?

Despite 15 parameters and no output schema, the description sufficiently covers the core behavior, including nuances like multipart/alternative for html_body, signature handling, and attachment limitations. It provides enough context for the agent to 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 coverage is 100%, so baseline is 3. The description adds value by explaining how action parameter determines which other arguments are used, the signature behavior for include_signature, and attachment forwarding. This clarifies parameter interplay beyond 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 tool composes and sends emails, and distinguishes three actions (send, reply, forward) with specific details about required parameters for each. It differentiates from sibling tools like draft by focusing on sending.

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 context on when to use each action (send, reply, forward) and mentions optional parameters. However, it doesn't explicitly exclude use cases or compare with alternatives like draft or inbox_list, limiting guidance on when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotation (destructiveHint=true), the description adds that deleted mail goes to Trash by default and can be recovered, with the option for irreversible deletion ('permanent: true'). It also specifies required scope ('delete:email'), providing valuable safety and authorization 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 concise (5 sentences) and front-loaded with the primary purpose. Every sentence adds value, though it could be slightly more structured (e.g., bullet points) for easier scanning.

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 complexity (20 parameters, no output schema), the description covers core behavior, auth, and recovery. It omits the return value format, but the high schema coverage compensates, making it mostly 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%, so the description's job is minimal. It adds no extra parameter-level meaning beyond the schema, meeting the baseline for a well-documented 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 'Delete messages' and enumerates three specific actions (delete, delete_batch, search_and_delete), making the tool's purpose unambiguous. It distinguishes itself from siblings like email_read and email_compose by focusing on 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?

The description gives explicit usage guidance for each action (e.g., 'delete' for one message_id, 'delete_batch' for several) and explains default vs. permanent deletion. However, it does not compare with sibling tools like email_organize or provide alternatives, which would raise the score to 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses behavioral traits such as the effect of each action (e.g., copy leaves the original), provider limitations (IMAP/Outlook/Fastmail only for copy, flagged not supported on Outlook/Graph), and the nature of the action (non-destructive as per destructiveHint: false). It adds valuable context beyond annotations, such as batch operations and scope requirements. No contradiction with annotations.

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, using a few well-structured sentences that front-load the main purpose. Every sentence adds essential information, such as actions, provider notes, and scope requirements, without redundancy. It is appropriately sized for the tool's complexity.

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 (21 parameters, 7 actions) and lack of output schema, the description covers the main behaviors, provider-specific constraints, and cross-references to sibling tools. It does not explain return values, but for a mutation tool this is acceptable. Overall, it is fairly complete and aids 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?

The input schema has 100% coverage with descriptions for all parameters. The description adds value by explaining how parameters interact (e.g., action determines which other arguments are used, message_ids vs message_id for single/batch operations) and providing context for the 'action' enum. This goes beyond the baseline of 3 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 clearly states the tool's purpose: 'Move, copy, flag or archive messages.' It lists specific actions (move, copy, flag, archive, search_and_move) and their effects, distinguishing it from the sibling tool email_delete by noting that deletion should use that tool. This provides a specific verb+resource combination with clear 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 guidance on when to use each action, including provider-specific notes (e.g., copy only works on IMAP/Outlook/Fastmail) and required scopes (manage:folders / send:email). It also explicitly points to email_delete for deletion. However, it does not fully address when not to use this tool (e.g., alternative tools for other operations like scheduling), but the context is sufficient for an agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds value by detailing state-changing parameters like mark_as_read (default false) and attachment size limits, providing transparency beyond annotations.

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 two sentences: the first states the core purpose, the second enumerates actions with brief explanations. No redundant information, every word earns its place, and it is 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 tool with 27 parameters and multiple actions, the description provides a solid overview. It explains return behavior for attachment (base64 data) and implies returns for other actions. It lacks explicit return descriptions for list/read/search, but the richness of the input schema compensates.

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 covers 100% of parameters with descriptions. The tool description complements by grouping parameters under actions (e.g., search uses structured filters) and explaining action-specific usage, adding 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 tool reads, lists, and searches email in an inbox, and enumerates five specific actions (list, read, read_batch, search, attachment). It distinguishes itself from sibling tools like email_compose and email_delete by focusing on read-only 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?

The description implies usage for reading/searching email via its action list, but does not explicitly state when to avoid this tool or mention alternatives. The context from sibling tool names makes it clear, but explicit guidance is missing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description claims the delete action is 'irreversible', implying destructive behavior. However, the annotations set destructiveHint=false, creating a direct contradiction. This undermines trust in 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 a single, well-structured sentence that front-loads the purpose and then enumerates actions. Every clause is informative and concise.

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 actions, permissions, and irreversibility. It lacks explicit return value descriptions for create/rename/delete, but without an output schema, this is acceptable. Overall, it provides sufficient context for most use cases.

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 description adds only marginal value by grouping parameters per action. It does not provide new semantics beyond the schema definitions.

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 manages mailbox folders/labels with four specific actions (list, create, rename, delete), distinguishing it from sibling tools like email_compose or contact_search.

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 clear usage context by listing each action's required parameters and permissions (e.g., 'list needs read:email; the rest need manage:folders'). However, it does not explicitly mention when not to use this tool or suggest alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds extra behavioral context, such as the optional provider filter, the default inclusion of capabilities, and the return structure (inbox UUID, email address, etc.). No contradictions with annotations.

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 paragraph that front-loads the purpose, then provides usage guidance, and finally details the return structure. It is moderately sized and every sentence adds value, though slightly verbose in listing all return fields.

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 low complexity, annotations covering read-only and idempotent behavior, and the presence of an output schema, the description sufficiently covers purpose, prerequisites, and return information. It could be improved by explicitly linking to output schema fields, but overall 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 coverage is 100%, with both parameters described in the schema. The description mentions the optional filter and include_capabilities but does not add significant new meaning beyond what the schema provides. 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 tool lists inboxes and details the returned fields (UUID, email, display name, etc.). It distinguishes from siblings by noting that this tool is the first call required to discover inbox_id for other tools, making its purpose specific and 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?

Explicitly instructs to call this tool first to discover inbox_id values needed by other tools, providing strong usage guidance. While it doesn't explicitly list when not to use it, the context makes it clear that other email tools depend on this one. No alternative tools are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations (readOnlyHint=false, destructiveHint=false) indicate mutability and non-destructiveness. The description adds the 'cancel' action, which implies a destructive operation, potentially conflicting with destructiveHint=false. However, canceling a scheduled send is arguably non-destructive. The description does not elaborate on side effects or constraints beyond what annotations provide.

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 concise sentences: first states the purpose, second details the action parameter with its three variants. No unnecessary words, front-loaded with 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?

The description covers the core actions but omits details like the 'list' action's support for limit/inbox filtering and the 'create' action's optional parameters (cc, bcc, attachments). Given the tool's complexity (15 parameters), the description is incomplete but adequate for basic 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?

Schema descriptions cover 100% of parameters, so baseline is 3. The description adds value by explaining how the 'action' parameter determines which other parameters are relevant (e.g., 'create' uses to/subject/body+send_at), providing a logical grouping that the schema alone does not offer.

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 'Schedule mail for later delivery' and enumerates the three actions (create, list, cancel), making the tool's purpose and operation explicit. It distinguishes from sibling tools like email_compose (immediate send) by focusing on scheduling.

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 (e.g., email_compose for immediate sending). It only describes the actions without comparative context, 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=false and destructiveHint=false, consistent with mutation on 'set'. The description discloses that 'set' marks the signature source as 'manual' and overrides auto-import. It does not detail error handling or rate limits, but for this simple tool, the behavioral coverage is 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 paragraph but is well-organized, starting with the core purpose and then detailing parameters. It is concise and informative without unnecessary repetition. Slightly more structural breaks could improve readability, but it remains effective.

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 there is no output schema, the description compensates by describing what 'get' returns (signature_html/text, enabled flag, reply_mode, source). It covers the main use cases for both actions. It does not discuss error codes or pagination, but for a simple read/write tool with limited parameters, it is sufficiently 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 coverage is 100%, yet the description adds significant value: it explains the auto-selection of inbox_id when only one inbox exists, the fallback behavior of listing inboxes if omitted, the meaning of leaving parameters unset or passing empty strings, and defaults for signature_reply_mode. This goes well beyond the schema definitions.

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 reads or sets the email signature, with two distinct actions 'get' and 'set'. It explains the resource (inbox's email signature) and context (appended server-side). This distinguishes it from sibling tools like email_compose or inbox_list, as it is the only tool dedicated to signature management.

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 when to use 'get' vs 'set', including required permissions (read:email vs send:email). It explains that setting overrides Gmail auto-import. While it does not explicitly exclude use cases, it gives sufficient context for correct invocation. A sister or alternative tool is not named, but the context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.