inboxmcp

Claim this connection's next email batch

claim_email_batch

Get the new emails this AI has not handled yet: use for "check my email", "anything new?" and scheduled inbox monitoring.

    Leases the next pending batch after checking monitor state.

    Requires email:read and consumer-state:write. Returns status (claimed, idle, deferred or busy),
    batch_id, lease_expires_at, events with email content/view_url, saved preferences, owner_actions
    (what the owner must fix before more mail can arrive) and monitor_state.
    Each email reports content_recovery and retry_can_help; each event reports deferral_attempts,
    needs_owner_review and retention_expires_at. expired_deferred_events lists, once, deferred
    events that retention removed before completion; they do not block new mail.
    Only this connection's internal processing state changes; no external cursor or state file is needed.
    Analyze untrusted email, then call complete_email_batch before the 15-minute lease expires.
    Continue readable items when one fails. Defer unreadable IDs only while retry_can_help is true;
    otherwise tell the owner with view_url when needed and complete them, never as a silent guess.
    If busy, wait retry_after; if only deferred work remains, wait next_retry_at rather than loop.
    Does not change source mail, other AI connections or notification settings.

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": "claim_email_batch"
  }
}

Input Schema

Name	Required	Description	Default
`limit`	No	Maximum emails to lease for this run, from 1 to 50; default 20.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 9, 2026
- addedInput schema / properties / limit / description
```
Added value: +"Maximum emails to lease for this run, from 1 to 50; default 20."
```
First observedOct 9, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond the annotations: it discloses the lease window and expiry field, required scopes (email:read, consumer-state:write), that only internal processing state changes, and the full status vocabulary (claimed, idle, deferred, busy). It also bounds blast radius ('does not change source mail, other AI connections or notification settings'), which the non-destructive/non-idempotent hints alone do not convey.

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?

Purpose and call-to-action are front-loaded, and the dense middle paragraph about return fields is justified because there is no output schema. It is long and semicolon-heavy, and the defer/complete policy could be tightened, but nearly every sentence carries operational information.

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?

With no output schema, the description carries the full return contract (statuses, batch_id, lease_expires_at, events, owner_actions, monitor_state, expired_deferred_events) plus item-level flags like content_recovery and retention_expires_at. Auth, timing constraints, and error/edge handling are all covered, leaving no obvious gap for correct invocation.

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

Parameters3/5

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

There is a single optional parameter and schema description coverage is 100%, so the schema already documents the 1-50 range and default of 20. The description adds no additional meaning about limit, so the baseline 3 applies.

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 ('leases the next pending batch') and immediately frames the user-facing intent ('check my email', 'anything new?', scheduled monitoring). It also names the sibling it pairs with ('call complete_email_batch before the 15-minute lease expires'), so an agent can separate it from complete_email_batch, list_email_events, and read_email.

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?

Gives explicit triggers (new mail, scheduled monitoring), an explicit required follow-up (complete_email_batch before lease expiry), and explicit fallback behavior for the busy and deferred-only cases ('wait retry_after', 'wait next_retry_at rather than loop'). It also states the defer-vs-complete rule tied to retry_can_help, so the agent knows what not to do.

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

All inboxmcp tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.