Skip to main content
Glama

Move Matching Email Messages

move_messages_matching
Destructive

Move messages in a folder that match sender addresses and/or an OData filter to a chosen destination, with dry-run preview and a move limit to prevent accidental bulk changes.

Instructions

Move every message in a folder that matches a sender list and/or an OData filter — the bulk step of an inbox clean-up. Pass senders (addresses from summarize_senders) and/or filter; a whole folder with no condition is refused. Destination deleteditems is how to bulk-delete: it is reversible from Deleted Items, and a hard delete is deliberately not offered.

SAFE BY DEFAULT: dry_run is true unless set to false. A dry run fetches the matching set and reports the count, date range, sender breakdown and newest subjects, moving nothing — read it before re-running with dry_run: false. A live run refuses to move more than limit messages (default 1000) so a mis-scoped filter cannot empty a folder; raise limit explicitly when the dry-run count is intended.

Moves go through Graph JSON batching (20 per round-trip, throttling retried), so thousands of messages take seconds, not minutes, and no message IDs pass through the caller.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "folder": "<folder>",
      "destination": "<destination>"
    },
    "name": "move_messages_matching"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoRefuse a live run that would move more than this many (default 1000, max 20000)
filterNoOData filter, e.g. "receivedDateTime lt 2025-01-01T00:00:00Z". Combined with senders using AND.
folderYesFolder to sweep: well-known name (inbox), display name, or ID. Required.
dry_runNoDefault true: report what would move and move nothing. Pass false to move.
mailboxNoEmail address of another mailbox to act on (delegated or shared), e.g. 'someone@example.com'. Omit for your own mailbox; required when this server signs in as an application. Only addresses this server is configured to allow will be accepted.
sendersNoSender addresses to match, exact and case-insensitive (max 20 per call)
destinationYesWhere matches go: well-known name (deleteditems, archive, junkemail), display name, or ID

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.3/5.0
Behavior4/5

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

Goes well beyond the destructiveHint/readOnlyHint annotations: dry_run defaults to true and describes exactly what the report contains, live runs are capped by limit (default 1000, max 20000) to prevent mis-scoped wipes, moves are reversible via Deleted Items, and batching is 20 per round-trip with throttling retries. The mailbox parameter notes server-side allowlist and app-auth requirements. Only the failure/partial-failure behavior of a batch is left unstated.

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-loaded with the action, then a SAFE BY DEFAULT paragraph, then a transport note — a logical progression where each sentence carries distinct operational information. The batching sentence ('thousands of messages take seconds, not minutes') leans slightly promotional, but the 20-per-round-trip and retry details justify it.

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?

For a 7-parameter destructive bulk mutation with no output schema, the description supplies the missing return semantics (count, date range, sender breakdown, newest subjects) and covers safety, limits, reversibility, auth, and performance. An agent has everything needed to call it safely on the first attempt.

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 on top: senders should come from summarize_senders, folder and destination accept well-known names/display names/IDs, and limit must be raised deliberately once the dry-run count is known. It reinforces rather than duplicates the schema's field-level text.

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

Purpose4/5

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

States a precise verb and resource with scope: 'Move every message in a folder that matches a sender list and/or an OData filter,' and frames itself as 'the bulk step of an inbox clean-up.' It implicitly separates itself from ID-based movers ('no message IDs pass through the caller') and from hard deletes, but never names the single-message or batch siblings it should be weighed against.

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?

Explicit about preconditions ('a whole folder with no condition is refused'), the intended workflow ('read it before re-running with dry_run: false'), and the alternative path for deletion ('Destination deleteditems is how to bulk-delete... a hard delete is deliberately not offered'). It also points to summarize_senders as the source of the sender list.

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