Skip to main content
Glama
adecubed

gigamail

by adecubed
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

delete_message

Destructive

Delete an email safely with human approval: the first call previews the message, a person approves it out of band, then a second call moves it to Deleted Items or marks it IMAP deleted.

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 = search).
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. 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."
  2. First observedv0.1.3

TDQS

A4.8/5.0
Behavior5/5

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

Goes far beyond the destructiveHint/openWorldHint annotations by disclosing the two-phase approval flow, out-of-band human approval mechanism, 15-minute expiry, deduplication of identical pending requests, the 20-requests/hour rate limit, audit logging, that the second call executes the originally approved arguments, and exactly what happens on execution (moved to Deleted Items / IMAP expunge, trash never emptied). This is exactly the kind of behavioral detail annotations cannot carry.

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

Conciseness4/5

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

Front-loads the verb and the critical two-phase constraint in the first clause, then sequences approval, expiry, rate limits, audit, and execution semantics. It is a dense paragraph, but nearly every clause is load-bearing; slightly compressed formatting would improve scannability.

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?

Although there is no output schema, the description states the return shape ({success}, status=approval_required, status=rate_limited) and covers the full lifecycle an agent must reason about for a destructive, approval-gated operation. Nothing needed to call it correctly is missing.

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 baseline is 3, but the description adds meaning beyond the schema: it clarifies that the second call executes the approved arguments rather than the ones passed the second time, and that the preview surfaces subject and sender. Remaining params (folder, account_id) are left to the schema.

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+resource ('Delete one message') and explicitly distinguishes itself from the sibling move_message, which is named as the reversible alternative. An agent can route between the two without opening either 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 says when to prefer move_message ('For reversible tidying prefer move_message, which is approved the same way but destroys nothing') and lays out the two-call approval sequence the agent must follow. No inference required.

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