trash_messageMove a message to the Trash folder without permanent deletion. Provide account, uid, and optional folder to safely remove unwanted email.
Moves a message to the Trash folder. Never deletes permanently.
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | uid from search_messages | |
| folder | No | Default: Gmail All Mail, else INBOX | |
| account | Yes | list_accounts id |
Changes observed during successful MCP inspections.
v0.13.12Input schema / properties / account / descriptionPrevious value: -"Account id from list_accounts"New value: +"list_accounts id"Input schema / properties / folder / descriptionPrevious value: -"Folder/label path. Defaults to All Mail on Gmail, INBOX elsewhere."New value: +"Default: Gmail All Mail, else INBOX"Input schema / properties / uid / descriptionPrevious value: -"uid from search_messages: a number on IMAP mailboxes, an id string on Outlook; pass it back exactly as returned"New value: +"uid from search_messages"v0.8.1Input schema / properties / uid / descriptionAdded value: +"uid from search_messages: a number on IMAP mailboxes, an id string on Outlook; pass it back exactly as returned"Input schema / properties / uid / maxLengthAdded value: +512Input schema / properties / uid / maximumRemoved value: -9007199254740991Input schema / properties / uid / minLengthAdded value: +1Input schema / properties / uid / minimumRemoved value: -1Input schema / properties / uid / typePrevious value: -"integer"New value: +"string"v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is largely covered. The description adds the recoverability nuance 'Never deletes permanently,' which is genuinely useful context beyond the annotations. However it says nothing about permissions, behavior when the message is already in Trash, or side effects on labels/threads.
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 sentences, zero waste, with the primary action stated first and the non-permanence caveat immediately after. Nothing could be cut without losing 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?
For a simple 3-parameter mutation with full schema coverage and annotations declaring its destructive/idempotent nature, the description plus structured fields give an agent enough to call it correctly. The gap is the absence of usage routing against similar siblings, which is minor for a tool this narrow.
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% — uid, folder, and account are each documented in the schema, including the default-folder rule. The description adds no parameter meaning whatsoever, so the 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?
States a specific verb and resource: 'Moves a message to the Trash folder.' An agent can immediately tell this relocates a message rather than deleting it or modifying labels. It does not name any sibling (e.g. modify_message, bulk_apply) for differentiation, so it stops short of a 5.
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 when-to-use guidance and no alternatives named, even though siblings like modify_message, bulk_apply, and delete-adjacent flows exist. The only hint is the implicit 'trash a message' context carried by the name and title.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.