Skip to main content
Glama
adecubed

gigamail

by adecubed
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

delete_message

Destructive

Delete a single email message with mandatory human approval: first call previews, second call with approved request_id executes. Moves to trash; never empties it.

Instructions

Delete one message. TWO-PHASE, HUMAN-APPROVED: the first call (no request_id) executes nothing — it returns status=approval_required with a preview of exactly what would happen and a request_id. A human approves out of band (GigaMail console, CLI or Telegram, behind Windows Hello / Touch ID); the second call with that request_id executes the payload that was approved (the approved arguments, not the ones passed the second time). Requests expire (default 15 min); identical pending requests are deduplicated; more than 20 requests/hour per tool are refused (status=rate_limited). Every phase is written to the audit log. The preview shows the message's subject and sender. On execution the message is moved to the provider's Deleted Items / marked deleted and expunged (IMAP); GigaMail never empties the trash. Returns {success}. For reversible tidying prefer move_message, which is approved the same way but destroys nothing.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
folderNoFolder of the message (IMAP only; empty = inbox).
account_idNoAccount to operate on (integer id from list_accounts). Omit or null = the user's active account.
message_idYesMessage id exactly as returned by list_messages / list_unread / search_mail (opaque Graph id for Microsoft accounts, numeric IMAP UID for IMAP accounts). Ids are account-specific: never reuse one across accounts.
request_idNoOmit on the first call. On the first call the tool does NOT execute: it returns status=approval_required, a preview and a request_id. A human must approve that request_id out of band (GigaMail console, `gigamail approvals approve`, or Telegram — all behind Windows Hello / Touch ID). Then call again with the same request_id to execute. The agent cannot approve; repeating the call without approval just returns awaiting_approval.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.4.0
    • changedInput schema / properties / folder / description
      Previous value: -"Folder of the message (IMAP only; empty = search)."New value: +"Folder of the message (IMAP only; empty = inbox)."
  2. Changed4 schema fields changedv0.3.0
    • addedInput schema / properties / account_id / description
      Added value: +"Account to operate on (integer id from list_accounts). Omit or null = the user's active account."
    • addedInput schema / properties / folder / description
      Added value: +"Folder of the message (IMAP only; empty = search)."
    • addedInput schema / properties / message_id / description
      Added value: +"Message id exactly as returned by list_messages / list_unread / search_mail (opaque Graph id for Microsoft accounts, numeric IMAP UID for IMAP accounts). Ids are account-specific: never reuse one across accounts."
    • addedInput schema / properties / request_id / description
      Added value: +"Omit on the first call. On the first call the tool does NOT execute: it returns status=approval_required, a preview and a request_id. A human must approve that request_id out of band (GigaMail console, `gigamail approvals approve`, or Telegram — all behind Windows Hello / Touch ID). Then call again with the same request_id to execute. The agent cannot approve; repeating the call without approval just returns awaiting_approval."
  3. First observedv0.1.3

TDQS

A4.9/5.0
Behavior5/5

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

Goes far beyond the annotations (destructiveHint=true, idempotentHint=false): it discloses the two-phase human-approval flow, that the second call executes the *approved* arguments rather than the ones re-passed, request expiry (15 min), deduplication of identical pending requests, a 20/hour rate limit with status=rate_limited, audit logging, and the exact destruction semantics (moved to Deleted Items, expunged on IMAP, trash never emptied). This is exactly the behavioral context a destructive tool needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Long but dense and front-loaded: the destructive two-phase protocol leads, followed by operational limits, then execution semantics, then the sibling alternative. Every sentence carries distinct information with no repetition of the annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but the description names the return value ({success}) and the status codes an agent will encounter (approval_required, rate_limited, awaiting_approval). For a destructive, approval-gated tool this is complete enough to call and to handle responses correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains that request_id is omitted on the first call, what the first call returns, that approval happens out of band, and that the agent cannot self-approve. The schema already documents folder/account_id/message_id, so this is a modest but genuine increment.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Delete one message') and immediately differentiates itself from the closest sibling by naming move_message as the reversible alternative. An agent can tell exactly what this does and what it does not do without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: use this to delete, but 'For reversible tidying prefer move_message, which is approved the same way but destroys nothing.' It also spells out the two-call protocol and what happens if approval is withheld, leaving nothing to inference.

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

Deploy Server

Other Tools