Skip to main content
Glama

graph_get_mail_delta

Track changes in a mail folder by listing messages added, updated, read, or removed since a previous delta token; seed a token first, then pass it to sync only new changes.

Instructions

List the changes in a mail folder since a previous delta token.

Call it once without delta_link to seed a token, then pass the returned delta_token to receive only what changed since, including read-state changes and removals. Graph tracks one folder at a time and rejects $search on a delta query, so page through the folder you care about.

Args: folder: Mail folder name or ID (default "inbox"). delta_link: Opaque delta token from a previous call. Empty starts a new sync of the folder. top: Maximum number of messages per page (default 50). mailbox: Shared mailbox address or user ID to act on. Empty targets your own mailbox. Requires the delegated Mail.*.Shared permissions.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "graph_get_mail_delta"
  }
}

Input Schema

NameRequiredDescriptionDefault
topNo
folderNoinbox
mailboxNo
delta_linkNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.10.0

TDQS

A4.2/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does well: it discloses that results include read-state changes and removals, that tokens are per-folder, that $search is rejected, and that shared mailboxes require delegated Mail.*.Shared permissions. It omits token expiry/error behavior and any mention of throttling.

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?

The purpose is front-loaded, then the workflow, then a structured Args block that maps one-to-one onto the parameters. Slightly long, but the Args detail is justified given zero schema documentation; nothing is filler.

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

Completeness4/5

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

For a stateful sync tool with no annotations and no output schema, the description covers seeding, incremental paging, folder scoping, and permissions. It does not describe the returned payload (where delta_token appears, how removals are represented), which is the main remaining gap given the absent output schema.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must compensate, and it does for all four parameters: folder accepts a name or ID with an inbox default, delta_link is an opaque token where empty starts a new sync, top is a per-page cap, and mailbox targets a shared mailbox with an explicit permission requirement. This adds meaning well beyond the bare schema types and defaults.

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 specific verb and resource ('List the changes in a mail folder') plus the delta-sync mechanism, which clearly separates it from a plain listing tool. It never names a sibling such as graph_list_mail or graph_search_mail, so the differentiation is implied by the word 'delta' rather than stated.

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

Usage Guidelines4/5

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

Gives a concrete call sequence: seed once without delta_link, then pass the returned token to get only changes. It also states the constraint that Graph tracks one folder at a time and rejects $search on a delta query. It stops short of saying when to prefer this over graph_list_mail or graph_search_mail.

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