Skip to main content
Glama
deenesjakoruzh
agenticmail

AgenticMail

Official
by agenticmail
OverviewSchemaSourceRelated ServersDiscussions(1)Admin
TypeScript
Local

The first platform to give AI agents real email addresses and phone numbers. Send and receive email, SMS, and verification codes — all programmatically.

Are you an AI agent reading this on behalf of a human?

Your human asked you to install / set up AgenticMail. Pick either of these and then tell them to restart Claude Code:

# Option A — one-line installer (recommended)
curl -fsSL https://raw.githubusercontent.com/agenticmail/agenticmail/main/install.sh | bash

# Option B — manual two-command install
npm install -g @agenticmail/cli@latest
agenticmail bootstrap

Zero prompts, ~2 minutes, fully autonomous. For the full runbook (verification, common failures, repo conventions if you're modifying the code), see AGENTS.md — the agents.md file at this repo's root.

📄 Research Paper

Structured RPC vs. Text-Based Sub-Agent Orchestration — A comparative analysis of inter-agent communication paradigms. Demonstrates why AgenticMail's call_agent achieves 53× faster response times than conventional sub-agent spawning, and introduces the concept of the Conversational Fallacy in multi-agent AI systems. [PDF] [Source]

✨ What's new — media toolset (unreleased)

A local, opt-in media / video-editing toolset for AgenticMail agents.

  • Nine media tools. media_tts / media_tts_voices (Edge text-to-speech), media_image_edit, media_video_edit, media_audio_edit, media_info, media_video_understand, media_voice_clone, and media_capabilities. Available as MCP media_* tools and OpenClaw agenticmail_media_* tools, both thin clients of new /media/* API routes over a core MediaManager.

  • Cinematic video editing. Beyond trim/convert/compress: color grading presets, crossfade/wipe transitions, timed text overlays, picture-in-picture, split screen, Ken Burns, frame-interpolated slow motion, watermarks, concatenation, audio mixing, and whisper.cpp-driven auto-captions.

  • Gracefully degrading. The underlying binaries (ffmpeg, ffprobe, ImageMagick, whisper.cpp, Python) are not bundled — every tool feature-detects the binary it needs and returns an actionable install hint if it is missing. The server never crashes. A media block on /health and the media_capabilities tool surface what is available.

  • Safe by construction. Every binary is invoked via execFile with an argument array — no shell, no string interpolation. Untrusted input paths are validated (no control characters, no leading-dash flag-injection, must exist); numeric options are clamped; every call carries a bounded timeout and output buffer; output files land only inside the configured media directory.

✨ What's new in 0.9.54

Twilio joins 46elks as a phone transport provider.

  • Pick your carrier. PhoneTransportProvider is now 46elks or twilio — chosen at phone setup. 46elks behaviour is unchanged; Twilio is at full parity (outbound call-control + realtime voice).

  • Twilio call-control. Outbound calls via the Twilio Calls.json REST API, TwiML webhooks, status-callback cost tracking. Inbound webhooks are verified with the X-Twilio-Signature header (HMAC-SHA1, timing-safe, fail-closed) on top of the per-mission token.

  • Twilio realtime voice. A Twilio Media Streams ↔ OpenAI Realtime bridge. RealtimeVoiceBridge was generalised behind a RealtimeTransportAdapter seam — one bridge serves both carriers, function-calling / barge-in / transcript logic written once. Twilio audio is G.711 µ-law @ 8 kHz and the OpenAI session uses audio/pcmu, so a Twilio call needs no transcoding. A <Connect><Stream> connects to /api/agenticmail/calls/twilio-stream.

1038 tests pass; full build green. The live Twilio ↔ OpenAI call path still needs an operator smoke-test before the npm publish.

✨ Earlier — 0.9.53

Realtime voice tools + a Telegram channel.

  • The voice agent can now use tools mid-call. The OpenAI Realtime session declares session.tools; RealtimeVoiceBridge dispatches the model's function calls through an injected ToolExecutor, returns function_call_output, and keeps the phone line warm during slow tools with a safety-net timeout + an in-flight call cap.

  • ask_operator — human-in-the-loop on a live call. The agent records an operator query on the mission, notifies the operator (channel-agnostic; default email), polls up to ~5 min, and resumes with the answer. If the caller hangs up while a query is pending, the mission is flagged for callback-on-disconnect — once the operator answers, it re-dials with a continuity task.

  • Lookup tools. web_search (keyless DuckDuckGo, results fenced as untrusted content), recall_memory (the agent's universal memory), get_datetime. Plus agent-key-scoped operator-query API endpoints.

  • Telegram channel. A user registers a Telegram bot token, links a chat, and can message their AgenticMail agent — and get replies — over Telegram. The inbound webhook authenticates with a constant-time secret-token compare; it also carries ask_operator notifications and approvals.

  • Security. web_search output is fenced as untrusted before it reaches the model; operator email replies are verified against operatorEmail; Telegram bot tokens are encrypted at rest and redacted from logs; new SQL is parameterized.

996 tests pass; full build green. The live OpenAI ⇄ 46elks call path and live Telegram delivery still need an operator smoke-test before the npm publish.

✨ Earlier — 0.9.52

Realtime voice + OpenClaw memory.

  • Realtime voice bridge. A phone mission can now hold a live conversation. RealtimeVoiceBridge (@agenticmail/core) wires an OpenAI Realtime (gpt-realtime) session to a 46elks realtime-media WebSocket: caller audio (PCM16 @ 24 kHz) is relayed to OpenAI, synthesised speech comes back as response.output_audio.delta and is relayed to 46elks, server-side VAD handles turn-taking, and caller barge-in fires a 46elks interrupt. 46elks streams a call to the new /api/agenticmail/calls/realtime WebSocket endpoint, which matches the connection to its mission by 46elks callid and runs the bridge. Set OPENAI_API_KEY (env or config.json) to enable it.

  • Memory in the voice session. Before the call starts, the agent's persistent memory is rendered with generateMemoryContext() and folded into the Realtime session instructions — the model is told to treat it as its own long-term knowledge, so the call is continuous with everything the agent has learned elsewhere.

  • OpenClaw memory tools. agenticmail_memory, agenticmail_memory_reflect, agenticmail_memory_context, and agenticmail_memory_stats bring the universal per-agent memory to OpenClaw agents — 69 → 73 tools.

  • Bridge hardening. Per-frame audio size cap (an oversized frame is dropped, never forwarded), bounded pre-connect buffer, fail-closed connection auth (timing-safe token compare; no unknown-mission-vs-wrong-token oracle), and a terminal-state guard so a late event can't resurrect a finished mission.

The end-to-end voice path needs a live OPENAI_API_KEY and a provisioned 46elks websocket number — the bridge logic, memory injection, and the WebSocket upgrade/auth glue are unit-tested with mocked sockets, but the live call must be smoke-tested by the operator.

✨ Earlier — 0.9.51

The universal memory release. Every agent now has a persistent, evolving memory — categorised, confidence-decaying, BM25F-searchable knowledge that survives across every conversation, the way a human employee learns on the job.

  • AgentMemoryManager (@agenticmail/core) — CRUD, text recall, 9 memory categories, importance levels, confidence that decays for unaccessed entries, access tracking, pruning, and generateMemoryContext() which ranks + renders memory as a markdown block for prompt injection. Backed by a zero-dependency BM25F search index and an agent_memory table. Ported from the AgenticMail Enterprise memory engine, org-stripped — memory is personal to each agent.

  • Memory API — /memory (set / list / search / get / delete), /memory/reflect, /memory/context, /memory/stats. Every endpoint is scoped to the authenticated agent; an agent can only ever read or write its own memory.

  • MCP tools — memory, memory_reflect, memory_context, memory_stats so any MCP client can give its agent durable memory.

  • Agent-deletion cleanup — deleting an agent purges its agent_memory rows; no orphaned memory is left behind.

✨ Earlier — 0.9.1

The visibility release — closes every "what just happened?" gap from 0.9.0.

  • Lone wakes fire immediately. 0.9.0's debounce window blocked even single replies for 30 s, making the dispatcher look dead. Leading-edge fire + trailing-edge coalesce now: first event for a (agent, thread) spawns instantly; bursts within the window collapse into one trailing wake.

  • Dispatcher process heartbeat. check_activity now shows dispatcher: { state: 'alive' | 'unhealthy' | 'missing', uptimeMs, channels, coalesceQueueSize, ... }. The host can finally answer "is the dispatcher up?" in one query.

  • Skipped-wake ring buffer. Every filter decision (thread-closed, allowlist-excluded, wake-on-cc, budget-exhausted) is posted with a reason; check_activity surfaces the last 100. No more "did my mail land? did it skip?" guessing.

  • Per-agent wake_on_cc: false flag. Coder agents can register a preference: never wake when only on Cc, regardless of sender. PATCH /accounts/:id/wake-on-cc.

  • Display-name regex fix in deriveDefaultWakeList. Senders using "Vesper <vesper@localhost>" form no longer fall through to "no allowlist → wake everyone".

  • Web UI shows To / Cc / Bcc as separate labeled rows in the message view (previously lumped under one to: line).

  • docs/wake-patterns.md documents every wake shape + 5 recommended patterns.

✨ Earlier — 0.9.0

The wake-context release. Multi-agent thread cost goes from linear-in-thread-length to roughly flat.

  • Layered wake-context system. Every wake used to re-read the entire thread from scratch (12 messages × ~1 KB = 12 KB of token spend just to rehydrate, before any reasoning). Now the dispatcher prepends two blocks to every wake prompt: Layer 1 — ThreadCache (envelopes + previews of the last 10 messages, shared across CC'd agents) and Layer 2 — AgentMemory (a markdown file each agent writes at end-of-wake describing its own commitments and last actions). Agents read the new event + these two blocks and decide; they don't read_email prior history. New MCP tools save_thread_memory and get_thread_id.

  • wake default flipped from "everyone CC'd" → "To: only". Mirrors the email convention: To is for action, CC is for awareness. CC'd local agents still receive the mail in their inbox but don't get a Claude turn unless explicitly named in wake. Opt back into the old behaviour with wake: 'all'.

  • Wake coalescing. Within 30 s for the same (agent, thread), multiple wake events collapse into ONE Claude turn. A burst of 4 quick replies becomes one Claude wake that sees all four in a coalesced batch prompt. Wake-budget charges once. Configurable via wakeCoalesceMs.

Together these eliminate the "wake-thrash" failure mode where an agent fired 4 near-identical status reports because a designer sent 4 replies in 2 minutes.

✨ Earlier — 0.8.31

  • Compact-and-continue — workers can now run across multiple SDK turns. On a context-overflow error the dispatcher synthesises a breadcrumb checkpoint from the captured log, builds a "resuming after context reset" continuation prompt, and loops (capped at 4 iterations).

  • Typed task contracts — call_agent / POST /tasks/assign accept an outputSchema (JSON Schema, draft-7 subset). submit_result validates against it; mismatches return 400 with the validator errors so the worker can retry with a corrected shape.

  • Delete + Move-to-Spam buttons in the message view; Compose auto-saves to Drafts every 2s.

  • All Mail folder hides itself on servers that don't have one (Stalwart, most non-Gmail). Select-all checkbox now wires through.

  • Logo background stripped — bow PNG is now RGBA with proper transparency.

✨ Earlier — 0.8.29

  • Star button wired — clicking the star toggles IMAP's \Flagged flag via the new POST /mail/messages/:uid/star endpoint. Backed by MailReceiver.setStarred in @agenticmail/core. Optimistic UI; revert on failure.

  • Gmail-compact list UX — single 36 px rows (was 64 px stacked), subject + preview on one truncated line separated by an em-dash, leading checkbox column, sticky list-toolbar with select-all + refresh + count. Same layout for every folder.

  • Compose button down to 48 px (Gmail's actual size); the giant pink pill is gone.

✨ Earlier — 0.8.27

  • Folder bug fix — Sent / Drafts / Spam / Trash were returning empty in the web UI because hard-coded folder names didn't match Stalwart's actual IMAP names (e.g. Sent Items not Sent). Now auto-discovered per agent and matched against every common server convention (Stalwart, Gmail, Outlook, macOS Mail).

  • Two-line preview on every list row — web UI uses /mail/digest?folder=… everywhere instead of /mail/inbox (no preview) + /mail/folders/:folder (no preview).

  • URL reflects current folder — hash router now uses #/folder/<id> (sent, drafts, spam, …). Back/forward works, URLs are shareable, refresh stays put.

  • Stop hook output rewritten — terser, audience-neutral, includes body preview. Drops the instruction-leakage from 0.8.25/26.

✨ Earlier — 0.8.25

  • Workers can now run for hours — dropped the 30-min hard timeout. Each worker writes a per-turn log at ~/.agenticmail/worker-logs/<id>.log, posts heartbeats every 30 s, and runs in its own isolated cwd so parallel agents don't clobber each other's output. New MCP tool tail_worker to read a running worker's log live; check_activity now shows last tool used, turn count, and a stale flag (no auto-eviction).

  • Autonomous-mode awareness — the mail hook now registers on the Stop event too. Long headless Claude Code runs (no user prompts firing for hours) finally see teammate replies — the hook returns decision: 'block' at turn boundaries when the bridge inbox has new mail, forcing Claude to continue with the new-mail summary in context. Closes the follow-up that 0.8.23 filed.

  • Fixed agenticmail-mail-hook: command not found errors — hook is now registered with an absolute path resolved at install time. Resilient to any $PATH configuration; old installs auto-heal on the next agenticmail claudecode run.

  • Web UI fixes — (m.flags ?? []).includes is not a function crash gone; sidebar folders (Sent / Drafts / Spam / Trash) now load their real IMAP mailboxes instead of all hitting /mail/inbox; Cmd+C no longer pops the compose modal; full mobile-responsive layout with an off-canvas sidebar.

  • Official logos — Claude starburst (from Wikipedia) and the AgenticMail @ mark from branding/ now ship bundled and render as the host avatar + topbar / favicon.

  • Selective wake — wake: ["alice", "bob"] on send_email / reply_email / forward_email / template_send / manage_drafts(send) tells the dispatcher to give a Claude turn only to named agents. The other CC'd recipients still receive the mail but stay asleep. Cuts token cost on large threads by ~10× when used.

  • Thread-close markers — [FINAL], [DONE], [CLOSED], or [WRAP] in a subject tells the dispatcher this thread is done; no more wakes on any reply.

  • check_activity MCP tool — see which agents the dispatcher has woken right now, how long they've been running, and a preview of recent completions. The answer to "did the agent I just emailed actually start working?"

  • Comprehensive markdown rendering in the shell's email viewer — bold, italic, headings, lists, task lists, tables, fenced code, links, images, HTML entities, depth-colored quote stripes (instead of literal >>>>).

  • LLM-tolerant tool inputs — batch_mark_read({ uids: "[1,2,3]" }) and other common stringification mistakes now just work; coerced before validation.

  • Wake-budget circuit breaker — caps per-(agent, thread) wakes at 10 per 24h to stop reply loops and storms.

  • Dedup guidance — wake prompts now tell agents to check their prior contributions before redoing work.

See CHANGELOG.md for the full release history.

AgenticMail is a self-hosted communication platform purpose-built for AI agents. It runs a local Stalwart mail server via Docker, integrates SMS/phone access via Google Voice or 46elks, exposes a REST API with 75+ endpoints, ships a lightweight Gmail-style web UI for human oversight, and works with any MCP-compatible AI client and OpenClaw via plugin. Each agent gets its own email address, phone number, inbox, and API key.

License: MIT Node.js

agenticmail MCP server

Table of Contents

Related MCP server: courier-mcp

Why 🎀 AgenticMail?

AI agents need to communicate with the real world. Email is the universal communication protocol — every person and business has an email address. AgenticMail bridges the gap between AI agents and email by providing:

  • Isolated mailboxes — each agent has its own email address, inbox, and credentials. Agents can't read each other's mail.

  • Internet email connectivity — two gateway modes to send/receive real email (Gmail relay or custom domain with DKIM/SPF/DMARC).

  • Security guardrails — outbound scanning prevents agents from leaking API keys, passwords, or PII. Blocked emails require human approval.

  • Agent collaboration — agents can email each other, assign tasks, and make synchronous RPC calls.

  • SMS / Phone number access — integrate Google Voice or 46elks for SMS receive/send, verification code extraction, and phone number access for AI agents.

  • Realtime voice calls — bridge a phone mission to an OpenAI Realtime (gpt-realtime) session so an agent can hold a live two-way conversation, with its persistent memory folded into the call.

  • Persistent agent memory — every agent has a categorised, confidence-decaying, searchable long-term memory that survives across conversations and is injected into prompts and voice sessions.

  • Smart orchestration — call_agent replaces basic sub-agent spawning with auto mode detection, dynamic timeouts, runtime tool discovery, and async execution for long-running tasks.

  • Tool integrations — 100 MCP tools for any AI client, 89 OpenClaw tools, and a 44-command interactive shell.

  • Self-updating — agenticmail update checks npm, verifies OpenClaw compatibility, and updates both packages automatically.

Features

Email Operations

  • Send email with text, HTML, attachments, CC/BCC, reply-to, and custom headers

  • Receive email via IMAP with real-time SSE event streaming (IMAP IDLE)

  • Reply and forward with proper In-Reply-To and References headers for threading

  • Search by sender, subject, body text, date range, read/unread status

  • Folders — create, list, move messages between folders

  • Batch operations — mark read/unread, delete, move multiple messages at once

  • Drafts — save, edit, and send draft emails

  • Templates — reusable email templates with variable substitution

  • Scheduled sending — queue emails for future delivery

  • Signatures — per-agent email signatures

  • Tags — label and categorize messages

  • Contacts — manage address book per agent

Multi-Agent

  • Account management — create, list, delete agents with unique email addresses

  • Agent-to-agent email — agents can email each other directly via @localhost

  • Task system — assign tasks to agents, claim, submit results, track status

  • RPC calls — synchronous agent-to-agent calls with timeout (long-poll + SSE notification)

  • Agent directory — discover other agents by name

You can watch the whole team work in one place with agenticmail shell:

agenticmail shell — Solène (QA) and Cassian (developer) coordinating on a build, all visible from the claudecode bridge inbox

That's a real multi-agent thread captured in the REPL — the host kicked off one email, Solène verified the file Cassian shipped to disk, and every step is sitting there as ordinary mail. No custom orchestration code. Type agenticmail shell any time you want to see what your agents have been up to.

Gateway (Internet Email)

  • Relay mode (beginner) — use your existing Gmail or Outlook as a relay. Emails appear as you+agentname@gmail.com. Setup takes 2 minutes.

  • Domain mode (advanced) — custom domain via Cloudflare. Agents send from agent@yourdomain.com with full DKIM signing, SPF, and DMARC records.

    • Automatic DNS configuration (MX, SPF, DKIM TXT, DMARC, tunnel CNAME)

    • Cloudflare Tunnel for secure inbound traffic without exposing ports

    • Cloudflare Email Worker for Email Routing (catch-all → worker → AgenticMail)

    • Optional Gmail SMTP outbound relay for residential IPs without PTR records

    • Domain purchase via Cloudflare Registrar

    • DNS backup before any modifications

    • Automatic @domain email alias for all existing agents

What setup-email actually exposes — read before connecting a relay

Heads-up for anyone running agenticmail setup-email (or telling Claude / Codex to do it for them). Once that command succeeds, your sub-agents are reachable from the public internet via Gmail / Outlook plus-addressing. This is the design — not a bug — but the implications surprise some operators:

  • Every sub-agent has a publicly addressable inbox the moment setup-email finishes. Anyone who knows your relay address can hit yourrelay+<agentname>@gmail.com and the corresponding agent's AgenticMail inbox receives the message. Plus-addresses are publicly guessable (+secretary, +kepler, …) — don't treat them as a secret.

  • External mail wakes the dispatcher the same way internal @localhost mail does. When a new-mail event lands on a watched inbox, the dispatcher runs dedup + thread-cache + wake-budget checks and spawns a Claude Code (or Codex) worker turn. Source doesn't matter — bob@gmail.com and secretary@localhost are indistinguishable from the dispatcher's point of view.

  • The host bridge takes a different path. Mail to yourrelay+claudecode@gmail.com or yourrelay+codex@gmail.com doesn't spawn a worker — it goes to handleBridgeMail, which uses the host SDK's resume option to wake your last session headlessly. If that fails (session expired, host CLI not running), it falls through to the bridge-escalation email at setup_operator_email. So external mail to the bridge can wake your CLI / forward to your phone.

  • Watchout — spam wakes Claude / Codex turns. A scraper that finds astrumsphere+secretary@gmail.com in a leaked address book can drive worker turns at your expense. Throttles available, ordered from least invasive:

    1. Let the wake-budget guard in dispatcher.handleEvent rate-limit naturally (default cap per minute per agent).

    2. Add inbound spam rules at the relay layer so spam gets filtered before the SSE event publishes (built-in spam filter + tags can do this; see the Security section below).

    3. For agents that should be internal-only, set metadata.host to a value no dispatcher matches, or stop the relay's IMAP poller from publishing on that inbox.

Security

  • Outbound guard — scans every outgoing email for sensitive data patterns:

    • API keys and tokens (AWS, OpenAI, Stripe, GitHub, etc.)

    • Passwords and credentials

    • Private keys (SSH, PGP, RSA)

    • PII patterns (SSN, credit card numbers)

    • Internal URLs and configuration data

    • Blocked emails are held for human-only approval (agents cannot self-approve)

  • Spam filter — rule-based scoring engine for inbound email:

    • Categories: phishing, scam, malware, commercial spam, social engineering, lottery scam

    • Configurable threshold (default: 40)

    • Skips internal agent-to-agent emails

    • Runs on both relay inbound and SSE event streams

  • Human-only approval flow — when an agent's email is blocked:

    • The agent is informed the email was blocked and told to notify their owner

    • The owner receives a notification email with full blocked email content, warnings, and pending ID

    • Only the master key holder can approve or reject (POST /mail/pending/:id/approve)

    • Agents can list and view their own pending emails but cannot approve or reject them

    • System prompt guidelines instruct agents to inform their owner and wait, never attempt to bypass

  • DKIM/SPF/DMARC — automatic DNS setup in domain mode for email authentication

  • Rate limiting — configurable per-endpoint rate limits

SMS / Phone Number Access

  • Provider selection — choose Google Voice legacy forwarding or 46elks direct SMS API/webhooks

  • 46elks integration — send SMS through the provider API and receive inbound SMS through a secret-protected webhook

  • Google Voice integration — give agents a real phone number via Google Voice

  • Direct Voice web reading (primary, instant) — reads SMS directly from voice.google.com via browser

  • Email forwarding (fallback) — Google Voice forwards SMS to email, agent auto-detects and records them during relay polling

  • Separate Gmail polling — for users whose GV Gmail differs from relay email, runs a dedicated IMAP poll

  • Verification codes — automatic extraction of OTP/verification codes from SMS (4-8 digit, alphanumeric, Google G-codes)

  • Send SMS — direct provider API send when configured, or Google Voice web automation instructions for legacy configs

  • Smart setup wizard — validates Gmail/GV email matching, warns about mismatches, collects separate credentials when needed

Realtime Voice Calls

  • Live two-way conversation — RealtimeVoiceBridge bridges a phone mission to an OpenAI Realtime (gpt-realtime) session so an agent can actually talk on the call, not just place it

  • Two carriers — 46elks or Twilio — pick the provider at phone setup; RealtimeVoiceBridge is generalised behind a RealtimeTransportAdapter so both run through one bridge. 46elks streams to /api/agenticmail/calls/realtime (PCM16 @ 24 kHz); Twilio Media Streams connects a <Connect><Stream> to /api/agenticmail/calls/twilio-stream (G.711 µ-law @ 8 kHz — OpenAI audio/pcmu, no transcoding). Server-side VAD for turn-taking, caller barge-in relayed to the carrier.

  • Memory in the call — the agent's persistent memory is rendered and folded into the Realtime session instructions, so the model speaks with full continuity, as if it had always known those things

  • Mission-tracked — the bridge resolves the connection to its phone mission by 46elks callid, authenticates the connection token, and persists the conversation transcript to the mission

  • Hardened — per-frame audio size cap, bounded pre-connect buffer, fail-closed connection auth, terminal-state guard

  • Opt-in — set OPENAI_API_KEY to enable; without it, phone missions still place and track calls (call-control only)

  • Tools on the call — the Realtime session can call functions mid-call: ask_operator (human-in-the-loop — pause, ask the operator, resume, or call back on disconnect), web_search, recall_memory, get_datetime

Telegram Channel

  • Chat with your agents over Telegram — register a Telegram bot token, link a chat, and message your AgenticMail agent (and get replies) from Telegram

  • Inbound webhook — authenticated with a constant-time X-Telegram-Bot-Api-Secret-Token compare; uniform 403 on mismatch

  • Operator channel — carries ask_operator notifications and approvals, so a phone agent can reach you on Telegram mid-call

  • Secrets protected — bot tokens encrypted at rest, redacted from every log line and error

Media Toolset

  • Nine local media tools — media_tts, media_tts_voices, media_image_edit, media_video_edit, media_audio_edit, media_info, media_video_understand, media_voice_clone, plus media_capabilities

  • Text-to-speech — synthesise speech with Edge TTS (twelve voice presets); returns OGG/Opus, ready to send as a voice note

  • Image editing — resize, crop, rotate, convert, compress, text overlay, flip, blur, sharpen, grayscale (ImageMagick)

  • Video editing — basic (trim, GIF, compress, resize, add/remove audio, speed) and cinematic (color grading, transitions, captions, picture-in-picture, split screen, Ken Burns, slow motion, watermark, concatenate, auto-caption) — all via ffmpeg

  • Audio editing — trim, convert, merge, volume, speed, extract-from-video, reverse, fade

  • Video understanding — extract frames + transcribe audio (whisper.cpp) into a structured timeline an agent can read before editing

  • Voice cloning — reference-voice speech synthesis via F5-TTS (you supply the reference sample + transcript)

  • Opt-in / gracefully degrading — the underlying binaries (ffmpeg, ffprobe, ImageMagick, whisper.cpp, Python) are not bundled; every tool feature-detects the binary it needs and returns a clear, actionable install hint when one is absent — the server never crashes. Call media_capabilities (or read the /health media block) to see what is available

  • Safe by construction — every binary is invoked via execFile with an argument array (never a shell); untrusted input paths are validated (no control characters, no leading-dash flag-injection, must exist) and output files land only inside the configured media directory

Persistent Agent Memory

  • Long-term, evolving knowledge — each agent has a categorised memory (knowledge, preference, correction, skill, reflection, …) that survives across every conversation

  • Confidence + decay — entries carry a confidence score that decays for unaccessed knowledge; critical entries never decay; low-confidence and expired entries are pruned

  • BM25F search — a zero-dependency full-text index ranks recall by relevance, importance, recency, and access count

  • Prompt + voice injection — generateMemoryContext() renders a ranked markdown block for injection into agent prompts and realtime voice sessions

  • Private per agent — every memory endpoint is scoped to the authenticated agent; deleting an agent purges its memory

  • Everywhere — /memory* REST endpoints, MCP tools (memory, memory_reflect, memory_context, memory_stats), and OpenClaw tools (agenticmail_memory*)

Smart Orchestration (call_agent)

  • Auto mode detection — reads task complexity, picks light/standard/full mode automatically

  • Dynamic timeouts — 60s for quick tasks, 5+ minutes for deep research, 1 hour for async

  • Runtime tool discovery — probes host config for available tools instead of static deny lists

  • Async execution — long-running tasks run independently, auto-compact context, email results when done

  • Structured RPC — sub-agents return JSON, not raw text

Integrations

  • MCP server — 90+ tools for any MCP-compatible AI client

  • OpenClaw plugin — 80+ tools with skill definition and system prompt guidelines

  • REST API — 75+ endpoints, OpenAPI-style, Bearer token auth

  • SSE events — real-time inbox notifications via Server-Sent Events

  • Interactive CLI — 44 shell commands with arrow key navigation, body previews, retry logic

  • Self-updating — agenticmail update or /update in shell, with OpenClaw compatibility check

Architecture

                  ┌──────────────────────────────────────────────────┐
                  │                    AgenticMail                    │
                  │                                                  │
 AI Client ─MCP─> │  @agenticmail/mcp   (100 tools, stdio transport)│
                  │       │                                          │
 OpenClaw ─────>  │  @agenticmail/openclaw  (89 tools, plugin)       │
                  │       │                                          │
 HTTP clients──>  │       ▼                                          │
                  │  @agenticmail/api     (Express, 75+ endpoints)   │
                  │    ├── Authentication  (master key + agent keys)  │
                  │    ├── Rate limiting   (per-endpoint)             │
                  │    ├── SSE streaming   (real-time inbox events)   │
                  │    └── Spam filter + Outbound guard               │
                  │       │                                          │
                  │       ▼                                          │
                  │  @agenticmail/core    (SDK layer)                 │
                  │    ├── AccountManager  (CRUD agents in Stalwart)  │
                  │    ├── MailSender      (SMTP, nodemailer)         │
                  │    ├── MailReceiver    (IMAP, imapflow)           │
                  │    ├── InboxWatcher    (IMAP IDLE → events)       │
                  │    ├── GatewayManager  (relay + domain routing)   │
                  │    │   ├── RelayGateway      (Gmail/Outlook)      │
                  │    │   ├── CloudflareClient   (DNS, tunnels, etc) │
                  │    │   ├── TunnelManager      (cloudflared)       │
                  │    │   ├── DNSConfigurator    (MX, SPF, DKIM)     │
                  │    │   └── DomainPurchaser    (Registrar API)     │
                  │    ├── StalwartAdmin   (mail server management)   │
                  │    ├── EmailSearchIndex (FTS5 full-text search)   │
                  │    └── Storage         (SQLite + migrations)      │
                  │       │                                          │
                  │       ▼                                          │
                  │  Stalwart Mail Server  (Docker container)         │
                  │    ├── SMTP (port 587) — submission               │
                  │    ├── SMTP (port 25)  — inbound delivery         │
                  │    ├── IMAP (port 143) — mailbox access           │
                  │    └── HTTP (port 8080) — admin API               │
                  └──────────────────────────────────────────────────┘
                          │                         │
            ┌─────────────┘                         └──────────────┐
            ▼                                                      ▼
     Relay Mode                                            Domain Mode
  ┌──────────────────┐                            ┌──────────────────────┐
  │  Gmail / Outlook  │                            │  Cloudflare          │
  │  IMAP polling     │                            │  ├── DNS zone        │
  │  SMTP relay       │                            │  ├── Tunnel          │
  │  Sub-addressing   │                            │  ├── Email Routing   │
  │  (+agent@gmail)   │                            │  ├── Email Worker    │
  └──────────────────┘                            │  └── Registrar       │
                                                   └──────────────────────┘

Data Flow

Sending email (relay mode):

  1. Agent calls POST /mail/send with recipient, subject, body

  2. API runs outbound guard scan — if sensitive data found, email is blocked and owner notified

  3. GatewayManager detects external recipient → routes to RelayGateway

  4. RelayGateway sends via Gmail SMTP as owner+agentname@gmail.com

  5. Reply-To set to agent's relay address so replies route back

Sending email (domain mode):

  1. Agent calls POST /mail/send

  2. Outbound guard scan runs

  3. GatewayManager rewrites agent@localhost → agent@yourdomain.com

  4. Email submitted to local Stalwart via SMTP (port 587)

  5. Stalwart signs with DKIM, resolves MX, delivers directly (or via Gmail relay)

Receiving email (relay mode):

  1. RelayGateway polls Gmail IMAP every 30 seconds for new messages

  2. New email detected → parsed → spam scored

  3. If not spam, delivered to agent's local Stalwart mailbox via SMTP

  4. X-AgenticMail-Relay: inbound header added for identification

  5. InboxWatcher (IMAP IDLE) fires SSE event to connected clients

Receiving email (domain mode):

  1. External sender sends to agent@yourdomain.com

  2. Cloudflare Email Routing catches all → routes to Email Worker

  3. Worker reads raw RFC822 message, base64-encodes, POSTs to /api/agenticmail/mail/inbound

  4. Inbound endpoint validates secret, parses email, delivers to agent's mailbox

  5. InboxWatcher fires SSE event

Quick Start

Prerequisites

  • Node.js 22 or later (we use the built-in node:sqlite module — zero native compilation, no node-gyp headaches)

  • brew (macOS) or apt (Linux) so the wizard can install Colima / Docker if you don't already have it

Two install paths

Path

When to use

Command

Autonomous ✨

Letting an AI agent (e.g. Claude Code) install AgenticMail on your behalf, or you just want zero questions

npm install -g @agenticmail/cli && agenticmail bootstrap

Interactive

You want to connect a Gmail relay or your own domain right away

npm install -g @agenticmail/cli && agenticmail setup

Autonomous install (recommended for most users)

# Option A — one-liner (does the npm install + bootstrap for you, plus a Node 22+ preflight)
curl -fsSL https://raw.githubusercontent.com/agenticmail/agenticmail/main/install.sh | bash

# Option B — equivalent, manually
npm install -g @agenticmail/cli
agenticmail bootstrap

Either path: zero prompts. The pipeline:

  1. agenticmail setup --yes — auto-installs Colima + Docker if missing, starts the Stalwart mail server, generates your master key, creates a default "secretary" agent. Skips external email/SMS setup (those need user-owned credentials; add them later if you want).

  2. agenticmail service install — registers a launchd plist (macOS) / systemd unit (Linux) so the API auto-starts on boot, and starts it now.

  3. Waits for GET /api/agenticmail/health to come up on the configured port (default http://127.0.0.1:3829).

  4. agenticmail claudecode — wires the Claude Code integration in if you have Claude Code installed (idempotent / no-op otherwise).

After this, you have a fully working local AgenticMail with internal multi-agent coordination over *@localhost. Add an external Gmail relay or your own domain anytime with agenticmail setup (interactive).

Interactive install

npm install -g @agenticmail/cli
agenticmail setup

The wizard walks you through everything: dependency checks, master key generation, mail-server start, optional Gmail relay or custom domain, optional SMS setup, optional realtime voice (OpenAI API key), optional phone calling (pick 46elks or Twilio and enter that carrier's credentials), optional Telegram channel (bot token + chat link), and optional OpenClaw integration. Every optional step is skippable and re-runnable any time. With --yes / --non-interactive all the optional steps are skipped with safe defaults.

The new optional steps in detail:

  • Realtime voice — paste an OpenAI API key to enable live spoken phone calls (the realtime voice bridge). Without it, phone missions still place and track call-control calls; only the spoken-conversation bridge is unavailable. The key is stored as openaiApiKey in ~/.agenticmail/config.json (file mode 0600).

  • Phone calling — pick your carrier (46elks or twilio), enter that carrier's credentials (46elks API username/password, or Twilio Account SID/Auth Token), a caller number, and a public HTTPS webhook base URL. The webhook secret is auto-generated if you don't supply one. Persisted to the agent's phone-transport config.

  • Telegram channel — paste a bot token from @BotFather and your chat id. The token is verified with Telegram before it's stored; the channel comes up in poll mode and agenticmail start auto-spawns a standalone bridge service that wakes the agent on inbound DMs with the full MCP toolset (memory, send_email, call_phone, …) available.

Want non-interactive setup? (env-piped, AI-assistant-friendly)

Same setup, no prompts — secrets ride in via env vars. Useful for Claude / Codex / scripted installs:

# Email
GMAIL_PASSWORD=… agenticmail setup-email <gmail-address>

# Twilio outbound calls (auto-opens a free Cloudflare quick-tunnel if you
# don't have a public HTTPS URL — no Cloudflare account required)
TWILIO_ACCOUNT_SID='<sid>' TWILIO_AUTH_TOKEN='<token>' \
AGENTICMAIL_PHONE_NUMBER='<E.164>' \
  agenticmail setup-phone --provider twilio

# Telegram (bridge auto-spawns on next `agenticmail start`)
TELEGRAM_BOT_TOKEN='<from @BotFather>' TELEGRAM_CHAT_ID='<your chat id>' \
  agenticmail setup-telegram

# Manual tunnel control (not usually needed — setup-phone opens one for you)
agenticmail tunnel start    # cloudflared quick-tunnel
agenticmail tunnel url      # prints the *.trycloudflare.com URL
agenticmail tunnel stop

Skip external email entirely?

Yes. AgenticMail works in local-only mode — agents email each other at *@localhost through the bundled Stalwart server with full RFC-822 routing, threading, attachments, and search. That's all the Claude Code multi-agent flow needs. The external Gmail/domain relay is optional and only matters when you want agents to send mail to the public internet.

What the wizard does for you

  • Checks Node, Colima/Docker, brew/apt

  • Generates a master API key (saved to ~/.agenticmail/config.json, file mode 0600)

  • Initialises the SQLite database (node:sqlite — Node 22+ built-in, no native compilation, no prebuilt binaries needed)

  • Starts Stalwart in a Docker container

  • Creates your first agent with its own email and API key

  • Optionally configures a gateway (relay or domain) for internet email

  • Optionally enables realtime voice (OpenAI API key), phone calling (46elks or Twilio), and the Telegram channel

Send your first email (programmatic)

import { AgenticMailClient } from '@agenticmail/cli';

const client = new AgenticMailClient({
  apiUrl: 'http://127.0.0.1:3829',
  apiKey: 'ak_your_agent_api_key',
});

// Send an email
await client.send({
  to: 'colleague@example.com',
  subject: 'Hello from my AI agent',
  text: 'This email was sent by an AI agent using AgenticMail.',
});

// Check inbox
const inbox = await client.listInbox(10);
for (const msg of inbox) {
  console.log(`${msg.from} — ${msg.subject}`);
}

// Read a specific email
const email = await client.readMessage(inbox[0].uid);
console.log(email.text);

Send your first email (CLI)

agenticmail> /send
To: someone@example.com
Subject: Test email
Body: Hello from the AgenticMail shell!

Email sent! Message ID: <abc123@localhost>

Send your first email (curl)

curl -X POST http://127.0.0.1:3829/api/agenticmail/mail/send \
  -H "Authorization: Bearer ak_your_agent_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "someone@example.com",
    "subject": "Hello",
    "text": "Sent via the AgenticMail API."
  }'

CLI Commands

AgenticMail includes a full CLI for managing your server. All commands are available via agenticmail <command> or npx @agenticmail/cli@latest <command>.

Core Commands

Command

Description

agenticmail

Start the server (runs setup first if not initialized). Opens the interactive shell after startup. This is the default command — just run agenticmail with no arguments.

agenticmail bootstrap

✨ Zero-question install. One-shot pipeline: setup + service install + claudecode wiring. Designed for AI agents (Claude Code, scripts, CI) to run on a user's behalf — no prompts, no decisions. Skips Gmail relay and SMS setup (which need user-owned credentials); add them later with agenticmail setup.

agenticmail setup

Run the setup wizard interactively. Walks you through system checks, account creation, service startup, email connection (Gmail/Outlook/custom domain), phone number (SMS) setup, realtime voice (OpenAI API key), phone calling (46elks or Twilio), the Telegram channel, and OpenClaw integration. Pass --yes (or -y, --non-interactive) to skip every prompt and use safe defaults. Safe to re-run — won't overwrite existing config.

agenticmail start

Start the server and open the interactive shell. Ensures Docker is running, Stalwart is up, and the API server is reachable. Automatically installs the auto-start service if not already set up.

agenticmail shell

👀 Drop into the interactive shell against an already-running server. Use this to monitor every agent's inbox, send mail on their behalf, watch the dispatcher event feed, or run any of the 44+ shell commands. Exits cleanly with /exit; the server keeps running. Best command to point a user at when they ask "what have my agents been doing?"

agenticmail web

🌐 Open the Gmail-style web UI in your browser. Two-column layout (sidebar with Compose + folders / content pane), 24×24 vector icons, hash router, real-time SSE updates, full markdown rendering, compose + reply with the wake parameter surfaced as a field. Same master key as the API. Available at http://127.0.0.1:3829/ whenever the API server is running.

agenticmail stop

Stop the server. Kills the background API server process. If auto-start is enabled, it will restart on next boot. Use agenticmail service uninstall to fully disable.

agenticmail status

Show what's running. Displays the status of Docker, Stalwart, the API server, email connection, and auto-start service.

Integration Commands

Command

Description

agenticmail openclaw

Set up AgenticMail for OpenClaw. Starts infrastructure, creates an agent, configures the OpenClaw plugin, enables agent auto-spawn via hooks, and restarts the OpenClaw gateway.

agenticmail claudecode

✨ Set up AgenticMail for Claude Code. Provisions a dedicated "claudecode" bridge agent, writes an MCP server entry to ~/.claude.json, generates a Claude Code subagent file per AgenticMail agent under ~/.claude/agents/, and starts the dispatcher daemon (PM2-managed) that auto-wakes agents on inbound mail or /tasks/rpc. No separate Anthropic key needed — workers ride on your existing Claude OAuth. Flags: --status, --remove, --purge-bridge. See @agenticmail/claudecode on npm for the full design.

Service Management (Auto-Start)

AgenticMail installs a system service so it automatically starts when your computer boots. On macOS this is a LaunchAgent; on Linux it's a systemd user service.

Command

Description

agenticmail service

Show auto-start status. Displays whether the service is installed and running.

agenticmail service install

Install the auto-start service. AgenticMail will start automatically on boot. The startup script waits up to 10 minutes for Docker to be ready, then checks that Stalwart is running (starts it if needed), then launches the API server.

agenticmail service uninstall

Remove the auto-start service. AgenticMail will no longer start on boot.

agenticmail service reinstall

Reinstall the service. Use this after config changes or updates to refresh the service file.

What happens on reboot:

  1. Your computer starts → Docker Desktop launches (its own auto-start)

  2. Stalwart mail server starts (restart: unless-stopped in Docker)

  3. AgenticMail startup script waits for Docker to be ready (up to 10 min)

  4. Script verifies Stalwart is running (auto-starts it if Docker restarted without it)

  5. API server starts and begins accepting requests

If the API server crashes, the system service automatically restarts it.

Maintenance Commands

Command

Description

agenticmail update

Update to the latest version. Checks npm for a new version, updates the CLI and OpenClaw plugin, and restarts the OpenClaw gateway if applicable.

agenticmail help

Show available commands.

Logs

Server logs are stored in ~/.agenticmail/logs/:

  • server.log — API server stdout

  • server.err.log — API server stderr

  • startup.log — Boot sequence log (Docker wait times, Stalwart checks)

Gateway Modes

AgenticMail supports two modes for sending/receiving real internet email:

Relay Mode (Beginner-Friendly)

Use your existing Gmail or Outlook account as a relay. No domain purchase needed. Setup takes under 2 minutes.

How it works:

  • Outbound: emails sent via your Gmail/Outlook SMTP as you+agentname@gmail.com

  • Inbound: AgenticMail polls your Gmail/Outlook IMAP for new messages addressed to you+agentname@gmail.com and delivers them to the agent's local mailbox

  • Gmail's + sub-addressing routes replies back to the right agent

Setup:

# In the interactive shell:
agenticmail> /relay

# Or via API:
curl -X POST http://127.0.0.1:3829/api/agenticmail/gateway/relay \
  -H "Authorization: Bearer mk_your_master_key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gmail",
    "email": "you@gmail.com",
    "password": "xxxx xxxx xxxx xxxx"
  }'

Requirements:

  • Gmail: App password (not your regular password)

  • Outlook: App password from Microsoft account security settings

Domain Mode (Advanced)

Full custom domain with Cloudflare. Agents send from agent@yourdomain.com with proper email authentication.

What gets configured automatically:

  • Cloudflare DNS zone creation

  • MX records pointing to Cloudflare Email Routing

  • SPF record (v=spf1 include:_spf.mx.cloudflare.net ~all)

  • DKIM key generation and TXT record

  • DMARC record (v=DMARC1; p=quarantine)

  • Cloudflare Tunnel (CNAME record, ingress rules)

  • Cloudflare Email Worker deployment (catches all inbound email)

  • Catch-all Email Routing rule → Worker → AgenticMail inbound endpoint

  • Stalwart hostname, DKIM signing, domain principal

  • @domain email aliases for all existing agents

  • Optional: Gmail SMTP outbound relay, domain purchase

Setup:

curl -X POST http://127.0.0.1:3829/api/agenticmail/gateway/domain \
  -H "Authorization: Bearer mk_your_master_key" \
  -H "Content-Type: application/json" \
  -d '{
    "cloudflareToken": "your_cf_api_token",
    "cloudflareAccountId": "your_cf_account_id",
    "domain": "yourdomain.com",
    "gmailRelay": {
      "email": "you@gmail.com",
      "appPassword": "xxxx xxxx xxxx xxxx"
    }
  }'

Cloudflare API token permissions needed:

  • Zone: DNS (Edit), Email Routing (Edit)

  • Account: Cloudflare Tunnel (Edit), Workers Scripts (Edit), Registrar (Edit — only if purchasing domains)

Packages

This is a TypeScript monorepo. Seven packages, each shipped to npm independently.

Package

Description

Install

@agenticmail/cli

CLI, setup wizard, interactive shell. Install this to get started.

npm i -g @agenticmail/cli

@agenticmail/core

Core SDK — accounts, SMTP/IMAP, gateway, spam filter, outbound guard, storage

npm i @agenticmail/core

@agenticmail/api

Express REST API server with 75+ endpoints

npm i @agenticmail/api

@agenticmail/mcp

MCP server with 100 tools for any MCP-compatible AI client

npm i -g @agenticmail/mcp

@agenticmail/claudecode

Anthropic Claude Code integration — registers MCP server + native subagents + lifecycle hooks + dispatcher daemon

npm i -g @agenticmail/claudecode

@agenticmail/codex

OpenAI Codex CLI integration — same architecture as @agenticmail/claudecode, adapted to Codex's TOML config and spawn_agent tool

npm i -g @agenticmail/codex

@agenticmail/openclaw

OpenClaw plugin with 89 tools and skill definition

openclaw plugin install agenticmail

Plugin folders (host marketplace manifests, separate from npm packages):

Folder

Host

What's inside

plugin/

Claude Code

.claude-plugin/plugin.json manifest + .mcp.json + skills. Ship target for Anthropic's plugin marketplace.

plugin-codex/

OpenAI Codex CLI

.codex-plugin/plugin.json manifest + hooks/hooks.json + mcp_servers.toml snippet + agent template. Ship target for Codex's plugin discovery (~/.codex/plugins/).

Dependency graph:

@agenticmail/cli ──────> @agenticmail/api ────> @agenticmail/core
@agenticmail/mcp       (standalone — HTTP calls to API)
@agenticmail/claudecode (peer-dep on @anthropic-ai/claude-agent-sdk)
@agenticmail/codex      (peer-dep on @openai/codex-sdk)
@agenticmail/openclaw   (standalone — HTTP calls to API)

API Overview

All endpoints are under /api/agenticmail. Authentication via Authorization: Bearer <key> header.

Two key types:

  • Master key (mk_...) — full admin access (create/delete agents, approve blocked emails, gateway config)

  • Agent key (ak_...) — scoped to one agent (read own inbox, send email, manage own drafts/contacts/etc.)

Key Endpoints

Method

Path

Auth

Description

Mail

POST

/mail/send

Agent

Send email (text, HTML, attachments)

GET

/mail/inbox

Agent

List inbox messages (paginated)

GET

/mail/digest

Agent

Inbox with body previews

GET

/mail/messages/:uid

Agent

Read full email with headers and attachments

POST

/mail/search

Agent

Search by from, subject, body, date

POST

/mail/messages/:uid/move

Agent

Move to folder

POST

/mail/messages/:uid/spam

Agent

Report as spam

GET

/mail/folders

Agent

List all folders

GET

/mail/pending

Both

List blocked outbound emails

POST

/mail/pending/:id/approve

Master

Approve blocked email

POST

/mail/pending/:id/reject

Master

Reject blocked email

Accounts

POST

/accounts

Master

Create new agent

GET

/accounts

Master

List all agents with metadata

GET

/accounts/me

Agent

Get own agent info

DELETE

/accounts/:id

Master

Delete agent (with email archival)

GET

/accounts/directory

Both

Agent discovery directory

Events

GET

/events

Agent

SSE stream — new email with route metadata, flags, expunge events

Gateway

GET

/gateway/status

Both

Current gateway mode and health

POST

/gateway/relay

Master

Configure relay mode

POST

/gateway/domain

Master

Configure domain mode

POST

/gateway/test

Both

Send a test email

Tasks

POST

/tasks/assign

Both

Assign task to another agent

POST

/tasks/rpc

Both

Synchronous agent-to-agent RPC (long-poll)

GET

/tasks/pending

Agent

List tasks assigned to me

POST

/tasks/:id/claim

Agent

Claim a pending task

POST

/tasks/:id/result

Agent

Submit task result

Plus endpoints for drafts, contacts, tags, rules, signatures, templates, scheduled emails, spam management, batch operations, domains, and agent deletion/cleanup.

See the API package README for complete endpoint documentation.

MCP Integration

The MCP server exposes 80+ tools to any MCP-compatible AI client via stdio transport.

Setup

Add to your MCP client configuration (e.g., .mcp.json or project settings):

{
  "mcpServers": {
    "agenticmail": {
      "command": "npx",
      "args": ["agenticmail-mcp"],
      "env": {
        "AGENTICMAIL_API_URL": "http://127.0.0.1:3829",
        "AGENTICMAIL_API_KEY": "ak_your_agent_key"
      }
    }
  }
}

Desktop Clients

For desktop AI applications, add the same configuration to your app's MCP config file (check your app's documentation for the file location).

What your AI can do

Once connected, your AI can:

  • "Check my inbox" → list_inbox

  • "Send an email to john@example.com about the project update" → send_email

  • "Reply to that last email saying thanks" → reply_email

  • "Search for emails from Sarah about the budget" → search_emails

  • "Create a draft response to the client" → manage_drafts

  • "What tasks are assigned to me?" → check_tasks

  • "Ask the research agent to look up competitor pricing" → call_agent

See the MCP package README for the full tool list.

Host Integrations

AgenticMail is host-agnostic at the protocol level (it's just SMTP/IMAP/HTTP/MCP under the hood), but each agentic CLI host expects its config + hooks + subagent definitions in a slightly different shape. We ship one host integration package per supported host. Each one:

  1. Registers the AgenticMail MCP server in the host's config so the model can see all 100 tools.

  2. Surfaces every AgenticMail account as a native sub-agent the model can dispatch to.

  3. Wires up the host's lifecycle hooks (SessionStart, UserPromptSubmit, Stop) so the agent gets a fresh-mail digest and capabilities preamble at the right moments.

  4. Runs a long-lived dispatcher daemon that watches every account's inbox via SSE and spawns a one-shot model turn whenever new mail or a task arrives — so agents wake on each other's replies automatically without polling.

Currently shipping

Host

Package

Plugin folder

Status

Anthropic Claude Code

@agenticmail/claudecode

plugin/

Shipping (0.2.x)

OpenAI Codex CLI

@agenticmail/codex

plugin-codex/

Shipping (0.1.x)

Both integrations share the same dispatcher architecture (per-agent serialization, wake-coalesce, wake-budget, restart recovery, capabilities preamble). The host-specific bits are: config-file format (JSON vs TOML), subagent definition syntax (markdown+frontmatter vs TOML heredoc), and the SDK we drive workers through (@anthropic-ai/claude-agent-sdk vs @openai/codex-sdk).

Picking the right install path

You want…

Run

One-line setup for Claude Code

npm install -g @agenticmail/cli && agenticmail claudecode

One-line setup for Codex

npm install -g @agenticmail/codex && agenticmail-codex install

Install both side-by-side

Run both — they don't conflict. Each writes to its own host's config; the AgenticMail accounts are shared.

Marketplace install (Anthropic plugin store)

Drop plugin/ into your Claude Code plugin directory and run /agenticmail-install.

Marketplace install (Codex ~/.codex/plugins/)

Copy plugin-codex/ to ~/.codex/plugins/agenticmail/.

Programmatic (your own provisioning script)

import { install } from '@agenticmail/claudecode' or '@agenticmail/codex' — same shape, different host.

Cross-host coordination

The mail layer is the lingua franca. An agent running under Claude Code can email an agent running under Codex (or vice versa) using the exact same send_email({ to, cc, wake }) MCP tool — the message lands in the target's inbox, the target's host-specific dispatcher picks it up, spawns the right kind of turn (Claude or Codex), and the agent replies-all to the thread. From the sender's perspective there's no API difference between "my teammate runs under the same host as me" and "my teammate runs under a different host." That's the whole point of routing through email instead of host-native peer messaging.

Roadmap

Host

Status

Notes

xAI Grok Build CLI

Researched — see wiki

Blocked on getting a SuperGrok Heavy seat to validate the closed-beta config-file paths against the community CLI proxy. ~80% architectural overlap.

Nous Research Hermes Agent

Researched — see wiki

Python-native plugin (pip install hermes-agent-agenticmail). ~75% architectural overlap with claudecode/codex.

OpenClaw Integration

Already have OpenClaw? Two steps:

# Step 1 — Install AgenticMail globally and run the setup wizard
npm install -g @agenticmail/cli && agenticmail setup
# Step 2 — Connect AgenticMail to your OpenClaw instance
agenticmail openclaw

That's it. The global install gives you the agenticmail command. The openclaw command will start the mail server, create an agent, and merge the plugin config into your openclaw.json automatically. Your OpenClaw agent now has its own email address.

Manual Configuration

If you prefer to configure manually, add to ~/.openclaw/openclaw.json:

{
  "plugins": {
    "agenticmail": {
      "enabled": true,
      "config": {
        "apiUrl": "http://127.0.0.1:3829",
        "apiKey": "ak_your_agent_key",
        "masterKey": "mk_your_master_key"
      }
    }
  }
}

The plugin survives OpenClaw updates — plugin configuration lives in user config (~/.openclaw/openclaw.json), not in the OpenClaw source directory.

Chat with Your AI Agent

Use /chat in the AgenticMail shell to talk directly to your OpenClaw agent in real-time:

╭───────────────────────────────────────────────╮
│ ❯ what's the weather in NYC?                  │
╰───────────────────────────────────────────────╯
                                          You 👤
                                  ╭──────────────╮
                                  │ what's the   │
                                  │ weather in   │
                                  │ NYC?         │
                                  ╰──────────────╯
🎀 Fola
╭──────────────────────────────────────╮
│ Currently 42°F and cloudy in NYC.    │
╰──────────────────────────────────────╯

  • WebSocket connection to OpenClaw gateway with Ed25519 device auth

  • Bubble-style chat UI with markdown rendering

  • Animated thinking indicator with elapsed timer

  • Multi-line input (Enter sends, \ + Enter for new lines)

Smart Sub-Agent Spawning

The call_agent tool intelligently spawns sub-agents:

  • Auto mode detection — light (simple tasks), standard (web research), full (multi-agent coordination)

  • Dynamic timeouts — 60s / 180s / 300s based on complexity

  • Dynamic tool discovery — probes OpenClaw config at runtime instead of static deny lists

  • Async mode — call_agent(async=true) for long-running tasks. The caller polls /tasks/assigned for completion; the assigned agent emails the result back to the caller when it has email capability enabled. In a localhost-only / no-relay setup the result still lands in the caller's local mailbox, so check /mail/inbox if you don't see an SMTP delivery.

  • Web search fallback — uses DuckDuckGo when Brave API isn't configured

See the OpenClaw package README for the full tool list.

Interactive Shell

The CLI includes a full-featured interactive shell with 44 commands:

agenticmail> /inbox

  ★ 1  john@example.com          Project Update           2m ago
    2  sarah@example.com         Re: Budget Review        1h ago
    3  notifications@github.com  [repo] New issue #42     3h ago

  ─────────────────────────────────────────────────
  Page 1/3 ─ [←] prev [→] next [v] toggle previews [Esc] back

  Use ↑↓ arrow keys to select, Enter to read inline

Key features:

  • Arrow key navigation with cursor selection

  • Body preview toggle (press v)

  • Inline email reading (press Enter)

  • Unread markers (★)

  • 3-retry input validation on all prompts

  • Paginated views with ←/→ navigation

Command Reference

Email:       /inbox /send /read /reply /forward /search /delete /save
             /thread /unread /archive /trash
Organize:    /folders /contacts /drafts /signature /templates /schedule /tag
Agents:      /agents /switch /deleteagent /deletions
Security:    /spam /rules /pending
Gateway:     /relay /digest /setup /status /openclaw
System:      /help /clear /exit

Security

Outbound Guard

Every outgoing email is scanned before sending. The guard detects:

Category

Examples

API keys

sk-..., AKIA..., ghp_..., sk_live_...

Credentials

password: ..., secret: ..., token: ...

Private keys

-----BEGIN RSA PRIVATE KEY-----

PII

Social security numbers, credit card patterns

Internal data

Localhost URLs, internal IPs, config file contents

When sensitive data is detected:

  1. Email is blocked and saved to the pending_outbound table

  2. Agent receives a response explaining what was blocked and why, with instructions to inform their owner

  3. Owner (master key holder) is notified via email with the full blocked email content, security warnings, recipient, subject, and pending ID

  4. Owner approves or rejects via the master key API (POST /mail/pending/:id/approve or /reject) or by replying to the notification email

  5. Agents cannot approve or reject their own blocked emails — the approve/reject endpoints require the master key

  6. Agents can only list and view their pending emails to check approval status

  7. MCP and OpenClaw tools enforce this by rejecting approve/reject actions with a message directing agents to inform their owner

  8. System prompt guidelines (OpenClaw) instruct agents to never attempt self-approval or rewrite emails to bypass detection

Spam Filter

Inbound emails are scored against rule-based patterns:

Category

Score Range

Examples

Phishing

10-30

Fake login pages, urgency language, spoofed senders

Scam

15-25

Nigerian prince, lottery winner, inheritance schemes

Malware

20-30

Suspicious attachments, executable links

Commercial

5-15

Unsolicited marketing, unsubscribe-heavy emails

Social engineering

10-20

Impersonation, authority pressure

  • Emails scoring >= 40 (configurable) are moved to Spam folder

  • Emails scoring 20-39 get a warning flag

  • Internal agent-to-agent emails skip spam filtering entirely

  • Relay-rewritten emails (@localhost from, external replyTo) are always treated as external

Authentication

  • Master key — full admin access, required for agent creation/deletion, gateway config, email approval

  • Agent API keys — scoped per-agent, can only access own inbox and send from own address

  • Inbound webhook secret — authenticates Cloudflare Email Worker requests to the inbound endpoint

Configuration

Environment Variables

# === Required ===
AGENTICMAIL_MASTER_KEY=mk_your_key          # Master API key (generate: openssl rand -hex 32)

# === Stalwart Mail Server ===
STALWART_ADMIN_USER=admin                   # Stalwart admin username
STALWART_ADMIN_PASSWORD=changeme            # Stalwart admin password
STALWART_URL=http://localhost:8080          # Stalwart HTTP admin URL

# === SMTP/IMAP (local Stalwart) ===
SMTP_HOST=localhost                         # SMTP host
SMTP_PORT=587                               # SMTP submission port
IMAP_HOST=localhost                         # IMAP host
IMAP_PORT=143                               # IMAP port

# === Optional ===
AGENTICMAIL_API_PORT=3829                   # API server port (default: 3829 — chosen to
                                            # avoid 3000/3100/3200/3300/4000/5000/8000/8080
                                            # which are all common dev-tool defaults)
AGENTICMAIL_API_HOST=127.0.0.1              # API bind host (default: 127.0.0.1; loopback only)
AGENTICMAIL_DATA_DIR=~/.agenticmail         # Data directory for SQLite DB and config

# === Realtime Voice (optional) ===
OPENAI_API_KEY=sk-...                       # Enables the realtime voice bridge — bridges a
                                            # phone mission to an OpenAI Realtime session.
                                            # Without it, calls are call-control only.

# === Gateway: Relay Mode ===
RELAY_PROVIDER=gmail                        # gmail or outlook
RELAY_EMAIL=you@gmail.com                   # Your email address
RELAY_PASSWORD=xxxx xxxx xxxx xxxx          # App password

# === Gateway: Domain Mode ===
CLOUDFLARE_API_TOKEN=your_token             # Cloudflare API token
CLOUDFLARE_ACCOUNT_ID=your_account_id       # Cloudflare account ID
AGENTICMAIL_DOMAIN=yourdomain.com           # Your domain
AGENTICMAIL_INBOUND_SECRET=your_secret      # Shared secret for Email Worker

# === Gmail SMTP Relay (domain mode outbound) ===
GMAIL_RELAY_EMAIL=you@gmail.com             # Gmail address for outbound relay
GMAIL_RELAY_APP_PASSWORD=xxxx xxxx xxxx     # Gmail app password

# === Debug ===
# AGENTICMAIL_DEBUG=1                       # Enable verbose per-message logging

Docker Compose

# docker-compose.yml (included in repo)
services:
  stalwart:
    image: stalwartlabs/stalwart:latest
    container_name: agenticmail-stalwart
    ports:
      - "8080:8080"   # HTTP Admin + JMAP
      - "587:587"     # SMTP Submission
      - "143:143"     # IMAP
      - "25:25"       # SMTP Inbound
    volumes:
      - stalwart-data:/opt/stalwart
      - ~/.agenticmail/stalwart.toml:/opt/stalwart/etc/stalwart.toml:ro
    restart: unless-stopped

SQLite Database

AgenticMail stores all state in a SQLite database at ~/.agenticmail/agenticmail.db. As of @agenticmail/core@0.7.x we use Node's built-in node:sqlite module (stable since Node 22) instead of better-sqlite3. The migration removed all native compilation from the install path — no node-gyp, no prebuilt-binary version-mismatch issues, no Python prerequisites. The on-disk database format is unchanged (it's still SQLite 3), so existing ~/.agenticmail/agenticmail.db files continue to work without migration.

Tables:

  • agents — agent accounts (name, email, API key, metadata)

  • gateway_config — relay or domain mode configuration

  • pending_outbound — blocked emails awaiting approval

  • delivered_messages — deduplication tracking for inbound relay

  • spam_log — spam scoring history

  • agent_tasks — inter-agent task assignments

  • email_rules — per-agent email filtering rules

  • contacts, drafts, signatures, templates, scheduled_emails, tags

Development

Setup

git clone https://github.com/agenticmail/agenticmail.git
cd agenticmail
npm install
docker compose up -d
npm run build
npm test

Project Structure

agenticmail/
├── agenticmail/           # CLI facade package (npm: agenticmail)
│   └── src/
│       ├── cli.ts         # CLI entry point (setup, start, status)
│       ├── shell.ts       # Interactive REPL (44 commands)
│       └── index.ts       # Re-exports from @agenticmail/core
├── packages/
│   ├── core/              # @agenticmail/core
│   │   └── src/
│   │       ├── accounts/  # Agent CRUD, roles, deletion
│   │       ├── mail/      # Sender, receiver, parser, spam filter, outbound guard
│   │       ├── inbox/     # IMAP IDLE watcher
│   │       ├── gateway/   # Relay, Cloudflare, DNS, tunnel, domain purchase
│   │       ├── stalwart/  # Stalwart admin API client
│   │       ├── storage/   # SQLite database, migrations, search index
│   │       ├── domain/    # Domain management
│   │       └── setup/     # Dependency checker, installer
│   ├── api/               # @agenticmail/api
│   │   └── src/
│   │       ├── app.ts     # Express app factory
│   │       ├── routes/    # 8 route modules (mail, accounts, events, etc.)
│   │       └── middleware/ # Auth, rate limiting, error handling
│   ├── mcp/               # @agenticmail/mcp
│   │   └── src/
│   │       ├── index.ts   # MCP server entry (stdio transport)
│   │       ├── tools.ts   # 80+ tool definitions and handlers
│   │       └── resources.ts
│   └── openclaw/          # @agenticmail/openclaw
│       ├── index.ts       # Plugin entry, system prompt
│       ├── src/tools.ts   # 89 tool definitions and handlers
│       └── skill/         # SKILL.md, reference docs, scripts
├── docker-compose.yml     # Stalwart mail server
├── .env.example           # Environment variable template
└── package.json           # Workspace root

Build Commands

# Build all packages
npm run build

# Build a single package
cd packages/core && npx tsup src/index.ts --format esm --dts --clean

# Run all tests
npm test

# Run tests for a specific package
cd packages/core && npx vitest run

Publish to npm

Publish in dependency order:

cd packages/core && npm publish
cd packages/api && npm publish
cd packages/mcp && npm publish
cd packages/openclaw && npm publish
cd agenticmail && npm publish

All scoped packages have "publishConfig": { "access": "public" } configured.

See CONTRIBUTING.md for development guidelines.

Telemetry

AgenticMail collects anonymous usage statistics to help improve the product. We track:

  • Tool call counts (which tools are popular)

  • Package version and OS platform

  • Anonymous install ID (random UUID, no personal data)

We never collect API keys, email content, addresses, or any personal information.

Opt out by setting the environment variable:

export AGENTICMAIL_TELEMETRY=0
# or
export DO_NOT_TRACK=1

Telemetry is also automatically disabled in CI environments.

Troubleshooting

OpenClaw plugin ID mismatch warning

plugin id mismatch (manifest uses "agenticmail", entry hints "openclaw")

This is harmless. OpenClaw infers the plugin ID from the npm package name (@agenticmail/openclaw) but the manifest declares "id": "agenticmail". The plugin loads and works correctly.

OpenClaw plugin path not found

If OpenClaw reports the plugin path not found, update plugins.load.paths in ~/.openclaw/openclaw.json to point to the correct location:

npm prefix -g
# Plugin is at: <prefix>/lib/node_modules/@agenticmail/openclaw

agenticmail: command not found

Use npx agenticmail for one-off usage, or install globally with npm install -g @agenticmail/cli.

License

MIT - Ope Olatunji (@ope-olatunji)

Available Tools

101 tools
batch_deleteB

Delete multiple emails by UIDs

ParametersJSON Schema
NameRequiredDescriptionDefault
uidsYesArray of UIDs to delete
folderNoFolder (default: INBOX)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

B3.4/5.0
Behavior2/5

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

No annotations are provided, and the description omits critical behavioral details such as whether deletion is irreversible, authentication requirements, or side effects. The description merely states the action without context.

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 description is a single efficient sentence with no waste. It is concise but could potentially be more informative while remaining succinct.

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

Completeness3/5

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

For a simple batch deletion tool, the description is adequate but lacks completeness regarding return values (no output schema) or irreversible effects. It covers the basic action but not the full context.

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?

Schema coverage is 100%, and the description adds little meaning beyond the schema parameter descriptions. Baseline 3 is appropriate as the schema already documents all parameters.

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?

The description 'Delete multiple emails by UIDs' is specific with verb 'delete' and resource 'emails', and clearly distinguishes from siblings like delete_email (single) and batch_move.

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

Usage Guidelines3/5

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

The description implies usage for bulk deletion by UIDs but provides no explicit guidance on when to use this tool versus alternatives like batch_mark_read or delete_email.

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

batch_mark_readC

Mark multiple emails as read

ParametersJSON Schema
NameRequiredDescriptionDefault
uidsYesArray of UIDs to mark as read
folderNoFolder (default: INBOX)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

C2.8/5.0
Behavior1/5

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

With no annotations provided, the description carries full burden for behavioral disclosure. However, it only states the basic action, without mentioning side effects, idempotency, authorization needs, rate limits, or return values, which is insufficient for a mutation tool.

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

Conciseness3/5

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

The description is a single sentence, which is concise but omits important details such as usage context or side effects. It front-loads the purpose but lacks completeness, making it merely adequate.

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

Completeness2/5

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

Given the absence of annotations and output schema, the description should provide more context about the tool's behavior, such as what happens after marking, prerequisites, or return value. The current description is too sparse for an agent to fully understand the tool's implications.

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?

Schema coverage is 100% with descriptions for all three parameters (uids, folder, _account). The description adds no parameter-specific information beyond what the schema provides, so baseline score of 3 is appropriate.

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?

The description 'Mark multiple emails as read' clearly specifies the action (mark as read) and the resource (multiple emails), distinguishing it from siblings like batch_mark_unread (different action) and mark_read (likely single email).

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives (e.g., batch_mark_unread, mark_read, batch_read). No exclusions or context are given, leaving the agent to infer usage solely from the name.

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

batch_mark_unreadB

Mark multiple emails as unread

ParametersJSON Schema
NameRequiredDescriptionDefault
uidsYesArray of UIDs to mark as unread
folderNoFolder (default: INBOX)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

B3.4/5.0
Behavior2/5

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

No annotations provided; the description lacks behavioral details such as error handling, idempotency, authentication requirements, or side effects. It only states the basic action.

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?

Single sentence, no unnecessary words, effectively communicates the core purpose.

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

Completeness2/5

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

No output schema, and the description doesn't cover return values, side effects, or guidance on optional parameters like folder and _account.

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?

Schema coverage is 100%, so baseline is 3. The description adds no extra information beyond 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?

The description clearly states the action (Mark), resource (multiple emails), and state (as unread), distinguishing it from siblings like batch_mark_read and mark_unread.

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

Usage Guidelines3/5

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

The description implies batch operation but does not explicitly state when to use this tool versus alternatives like mark_unread (single) or batch_mark_read.

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

batch_moveB

Move multiple emails to another folder

ParametersJSON Schema
NameRequiredDescriptionDefault
uidsYesArray of UIDs to move
fromNoSource folder (default: INBOX)
toYesDestination folder (e.g., Trash, Archive)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

B3.2/5.0
Behavior2/5

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

With no annotations, the description must disclose behavioral traits, but it only states 'move'. It does not explain whether it copies or moves, side effects on source folder, or error handling for invalid UIDs.

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?

The description is a single, front-loaded sentence with no wasted words, efficiently conveying the core purpose.

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

Completeness2/5

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

The tool performs a bulk operation with 4 parameters and no output schema or annotations. The description is too brief; it omits return behavior, confirmation of success, and handling of partial failures.

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?

Schema coverage is 100%, so baseline is 3. The description adds no extra parameter meaning beyond what the schema already provides, such as the difference between 'from' and 'to' or the role of '_account'.

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?

The description 'Move multiple emails to another folder' clearly identifies the action (move), the resource (emails), and the scope (multiple), distinguishing it from siblings like single-email move or batch delete.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives like move_email for single emails or batch_delete. The description lacks context for selection.

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

batch_readB

Read multiple emails at once by UIDs. Returns full parsed content for each message in a single call.

ParametersJSON Schema
NameRequiredDescriptionDefault
uidsYesArray of UIDs to read
folderNoFolder (default: INBOX)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

B3.3/5.0
Behavior2/5

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

No annotations are provided, so the description carries full burden. It states it returns content but omits safety (read-only), rate limits, or error handling for invalid UIDs. Only core behavior is disclosed.

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?

Single sentence, very concise and front-loaded. However, it could be slightly restructured to include usage hints without losing brevity.

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

Completeness2/5

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

Given no annotations or output schema, the description is too minimal. It does not explain return structure, behavior on partial failures, or ordering. A batch read tool should provide more operational details.

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?

Schema coverage is 100%, so baseline is 3. The description adds 'at once' and 'full parsed content' context, but does not elaborate on parameters like folder or _account beyond schema descriptions.

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?

The description clearly states the tool reads multiple emails by UIDs and returns full parsed content. It distinguishes itself from siblings like read_email (single) and other batch operations (delete, mark).

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

Usage Guidelines3/5

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

The description implies use when you have a list of UIDs and need content, but it does not explicitly state when to use alternatives (e.g., read_email for single) or mention limitations (e.g., max UIDs).

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

broadcast_emailA

Send the SAME email to N agents as N SEPARATE, ISOLATED emails — no CC, no shared thread. Each recipient sees ONLY their own address on the To: line and reads the message as a private 1:1 from you. Use this when you need to fan-out an announcement, hand the same task to several workers in parallel, or poll multiple agents for independent answers without letting them see each other's replies. Not a replacement for send_email + CC — use CC when the team should see each other and collaborate in one thread; use broadcast_email when the conversations are independent. Each per-recipient email gets its own Message-ID and thread, so replies come back to you privately (and wait_for_email can filter on from: to demultiplex). WAKE SEMANTICS: by default every local @localhost recipient gets a wake (since each is the sole To: of its own delivery). Pass wake: [] to fan-out silently (no wakes), or wake: ["alice","bob"] to wake only specific recipients while still delivering to all. Outbound guard scans every per-recipient send individually; if ANY send is blocked, the response reports per-recipient status so you know what got through.

ParametersJSON Schema
NameRequiredDescriptionDefault
toYesList of recipient addresses. Accepts an array of strings (preferred) or a single comma-separated string. Each address gets its OWN email — there is no CC, no shared thread, no way for recipients to see each other.
subjectYesSubject line shared by every per-recipient delivery.
textNoPlain text body shared by every per-recipient delivery.
htmlNoHTML body shared by every per-recipient delivery (optional).
wakeNoOptional wake-control. Accepts: (1) an array of agent names — `["alice","bob"]` — to wake exactly those recipients (others still receive the mail but stay asleep); (2) the string `"all"` to wake every recipient (this is the default for broadcasts); (3) an empty array `[]` to deliver to everyone silently with no wakes; (4) omit entirely to use the default (wake every local recipient).
attachmentsNoFile attachments. Same set is attached to every per-recipient delivery.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.9/5.0
Behavior5/5

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

Discloses that each recipient gets own email with unique Message-ID, private replies, wake semantics (default wakes local recipients, can control via wake parameter), and per-recipient outbound guard scanning. No annotations provided, but description fully covers behavioral traits.

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?

Well-structured: starts with core concept, then use cases, contrast with alternative, technical details, wake semantics, and error handling. No redundant sentences, front-loaded with essential 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?

Covers purpose, usage, parameter details, behavioral nuances, error reporting, and integration with wait_for_email. No output schema but description sufficiently explains the tool's behavior and expected outcomes. Complete for a complex tool with 7 parameters.

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%, baseline 3. Description adds value by explaining the isolation, wake parameter behaviors, and outbound guard reporting. Provides context beyond parameter types, such as how to array is processed and wake options.

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?

Clearly states it sends the same email to multiple recipients as separate, isolated emails, each appearing as a private 1:1. Distinguishes from send_email with CC by emphasizing privacy and thread isolation.

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 describes when to use (fan-out announcement, parallel tasks, independent polls) and when not to use (not a replacement for send_email+CC). References sibling tool send_email for collaborative threads.

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

call_agentA

Synchronous RPC to delegate work to another AgenticMail agent. Pipeline: the task is queued in AgenticMail, the target agent processes it AS THEMSELVES (under their real identity, mailbox, persona, and audit trail), and the structured result returns into your call. THIS IS HOW MULTI-AGENT COORDINATION IS SUPPOSED TO WORK from any MCP host. Do not, instead, spawn one of your host's native sub-agents and tell it to "act as " — that produces output under your identity, never touches the target's inbox, and skips their persona. Pass outputSchema to require a structured deliverable shape: the API validates the worker's submit_result against the schema and rejects mismatches with validator errors, so the worker can retry with a correct shape rather than returning free-form prose. Times out after the specified duration (default 180s, max 300s).

ParametersJSON Schema
NameRequiredDescriptionDefault
targetYesName of the agent to call
taskYesTask description
payloadNoAdditional data
timeoutNoMax seconds to wait (default: 180, max: 300)
outputSchemaNoOptional JSON Schema (draft-7 subset: type, required, properties, items, enum, additionalProperties, minLength/maxLength, minimum/maximum) describing the shape submit_result must conform to. The worker sees the schema in the wake prompt and the API validates on submission.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.6/5.0
Behavior4/5

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

With no annotations, the description must disclose behavioral traits. It does so by explaining that the target agent acts as themselves (real identity, mailbox, persona, audit trail), timeout behavior (default 180s, max 300s), and validation via outputSchema. While it omits rate limits or authentication specifics, the provided context is sufficient for safe invocation.

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 description is moderately lengthy but efficiently packed with essential information. It is front-loaded with the primary purpose and uses clear structure. Minor redundancy exists but each sentence contributes meaningfully.

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?

Given the tool's complexity (delegation, multi-agent) and the absence of an output schema, the description covers key aspects: execution model, identity handling, timeout, and output schema validation. It lacks explicit error handling or return format details, but the provided context is complete for effective use.

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?

The input schema already has 100% description coverage for all parameters. The description adds significant value by elaborating on outputSchema (exact JSON Schema subset) and the _account override. This enriches understanding beyond the schema alone.

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?

The description clearly states the tool's core function: 'Synchronous RPC to delegate work to another AgenticMail agent.' It uses specific verbs and resources, and distinguishes itself from improper alternatives like spawning native sub-agents. This provides clear purpose and differentiation from siblings.

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 explains when to use (for multi-agent coordination) and what not to do ('Do not, instead, spawn one of your host's native sub-agents...'). Also covers timeout and outputSchema usage. This gives comprehensive usage boundaries and alternatives.

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

call_answer_queryA

Inject an answer to a pending ask_operator query on a live phone call. The voice agent's next poll picks it up within ~3 seconds and relays the answer verbatim to the other party on the line. Use when the operator has provided info the call needs (DOB / account # / address / yes-or-no decision) — this beats redialing by a factor of 30× in wall-clock time and preserves the original call's context. If the mission was already terminated and the query auto-closed, this returns alreadyAnswered=true and is a no-op. When the call had already dropped, the answer arms a callback-on-disconnect that the scheduler dials a few seconds later with the answer baked into the continuation task.

ParametersJSON Schema
NameRequiredDescriptionDefault
mission_idYesPhone mission id (oq_ ids are bound to one mission; you can get this from call_open_queries).
query_idYesOperator-query id, e.g. "oq_abc-123…". From call_open_queries.
answerYesThe literal answer to relay back to the call (e.g. "11/26/1998", "Yes go ahead", "Approved up to $200"). The voice agent reads this verbatim to the other party.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A5/5.0
Behavior5/5

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

No annotations provided, so description carries full burden. It explains verbatim relay of answer, ~3 second polling delay, and behaviors in edge cases (alreadyAnswered, callback-on-disconnect). No contradictions.

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?

One well-structured paragraph that front-loads the main action. Every sentence adds value with no redundancy or waste.

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?

Despite no output schema, the description covers return behaviors (alreadyAnswered, callback). It explains edge cases and the mechanism (poll, callback). Complete for the tool's complexity.

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 coverage is 100%, and description adds context for each parameter: mission_id type, query_id format with example, answer verbatim relay, and _account override purpose. This adds meaning beyond 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?

The description clearly states the action: 'Inject an answer to a pending ask_operator query on a live phone call.' It specifies the verb (answer/inject) and the resource (operator query on a call), and distinguishes it from siblings like call_open_queries.

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 use ('when the operator has provided info the call needs') and compares to alternative ('beats redialing by a factor of 30×'). Also covers edge cases: terminated mission returns alreadyAnswered=true, dropped call arms callback.

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

call_cancelA

Cancel a tracked phone mission in AgenticMail. Provider-side hangup is not guaranteed in this call-control slice.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesPhone mission id
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.8/5.0
Behavior3/5

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

No annotations are provided, so the description must disclose behavioral traits. It mentions that provider-side hangup is not guaranteed, which is a key caveat. However, it does not describe the outcome of a successful cancellation, idempotency, or any side effects beyond the hangup note.

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?

The description is two sentences long, directly conveying the action and a key caveat. No unnecessary words or repetition. It is front-loaded with the primary purpose.

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?

Given the tool has 2 parameters, no output schema, and no annotations, the description covers the core action and a notable behavioral nuance. However, it does not explain the term 'tracked phone mission' or specify whether the cancellation is reversible. Despite these minor gaps, it is largely complete for a simple cancellation tool.

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?

Schema description coverage is 100% (both parameters have descriptions). The tool description does not add additional meaning beyond the schema; it does not explain the 'Phone mission id' further or the _account override beyond what the schema provides. Baseline score of 3 is appropriate.

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?

The description clearly states the tool cancels a tracked phone mission in AgenticMail, using a specific verb and resource. It distinguishes from siblings like call_phone (make a call) and call_status (get status) by focusing on cancellation.

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

Usage Guidelines3/5

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

The description does not explicitly state when to or not to use this tool, nor does it compare to alternatives. The note about provider-side hangup is a behavioral warning but not a usage guideline. For a simple cancellation, implicit usage is clear but no exclusions or alternatives are provided.

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

call_open_queriesA

List PENDING ask_operator queries on a phone mission (or all of an agent's missions when id is omitted). Use this BEFORE assuming a verification-style message from the operator is a fresh chat question — if there's an open query, the operator is most likely answering it. Pair with call_answer_query to inject the answer.

ParametersJSON Schema
NameRequiredDescriptionDefault
idNoPhone mission id. Omit to scan all of your agent's missions for open queries.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.2/5.0
Behavior3/5

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

No annotations are provided, so the description must fully disclose behavioral traits. It describes a list operation, implying read-only, but does not explicitly state idempotence, authentication needs beyond the _account parameter, or any other side effects. The term 'PENDING' clarifies state but not safety.

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?

Two sentences: first states the core function, second provides usage context. No filler, tightly written, and front-loaded with the most critical information.

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?

Despite no output schema or annotations, the description adequately covers purpose and usage context. It lacks details on return format or pagination, but for a simple list tool, the agent likely has enough to use it correctly.

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?

Schema coverage is 100% with both parameters well described. The description repeats the schema's note about omitting the id to scan all missions, adding no new information beyond what the schema already provides. Therefore, it meets the baseline but does not exceed it.

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?

Clearly states the tool lists pending ask_operator queries on a phone mission, with scope variation when id is omitted. Differentiates from sibling tools by referencing call_answer_query and contextualizing when to use it.

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 tells the agent to use this tool before assuming a verification-style message is a fresh question, and to pair it with call_answer_query to inject the answer. Provides clear sequential guidance.

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

call_phoneA

Start a tracked outbound phone mission. This is call-control only unless the configured transport reports realtime_media; risky decisions must be encoded in policy and may require the operator.

POLICY SCHEMA — every field below is REQUIRED and the literal values shown are the ONLY accepted values (anything else returns unsafe-confirm-policy / invalid-policy). Do not guess synonyms ("abort", "never_ever", true) — use the literals exactly.

Minimal valid policy (copy-paste, then adjust the cost / duration / regions to taste): { "policyVersion": 1, "regionAllowlist": ["WORLD"], "maxCallDurationSeconds": 600, "maxCostPerMission": 2.0, "maxAttempts": 1, "transcriptEnabled": true, "recordingEnabled": false, "confirmPolicy": { "paymentDetails": "never", "contractCommitment": "never", "costOverLimit": "needs_operator", "sensitivePersonalData": "needs_operator", "unclearAlternative": "needs_operator" }, "alternativePolicy": { "maxTimeShiftMinutes": 30 } }

Field requirements (the validator is strict — use these EXACT names and types):

  • policyVersion: the literal number 1 (NOT a string like "2025-01"). Required.

  • maxCallDurationSeconds: positive integer (NOT "maxDurationSeconds"). Server caps it.

  • maxCostPerMission: non-negative number, plain decimal (NOT "USD:2.00", NOT "maxCostUsd"). Server caps it.

  • maxAttempts: positive integer. Server caps it.

  • transcriptEnabled / recordingEnabled: boolean.

confirmPolicy field values are FIXED enums:

  • paymentDetails / contractCommitment: always "never" (the agent must never agree to pay or commit; recovering from a mistake costs the operator real money).

  • costOverLimit / sensitivePersonalData / unclearAlternative: always "needs_operator" (route the decision back through ask_operator). regionAllowlist values: "AT" | "DE" | "EU" | "WORLD". Use "WORLD" for any US/global destination; the transport's supportedRegions must intersect this set or the call is blocked as transport-region-unsupported.

ParametersJSON Schema
NameRequiredDescriptionDefault
toYesTarget phone number in E.164 format (e.g. +15555550100)
taskYesConcrete call objective, e.g. "reserve a table for two at 19:30"
policyYesPhone mission policy — see tool description for the minimal valid shape. All fields required.
voiceRuntimeRefNoOptional external voice runtime/session reference for future realtime integration
dryRunNoWhen true, store the mission without calling the provider
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

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 fully discloses behavioral traits: call-control only, operator needed for risky decisions, strict policy validation. It lacks details on return values or error handling, but given the complexity, transparency is high.

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 description is lengthy but well-structured with clear sections. It front-loads the purpose and policy schema, providing necessary detail without redundancy. Minor verbosity is justified by complexity.

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

Completeness3/5

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

The description covers the policy comprehensively but does not explain return values or what happens after the mission starts (e.g., status polling). Given the complexity, more info on result handling would improve completeness.

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%, baseline 3. The description adds significant meaning beyond schema by explaining the exact literals, confirmPolicy semantics, and field restrictions, making it easier to construct a valid policy.

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?

The description clearly states 'Start a tracked outbound phone mission,' specifying it's call-control only. It distinguishes from sibling tools like call_agent and call_status by its unique focus on initiating outbound calls with a policy.

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?

The description provides extensive context on when to use the tool, including the required policy schema and literal values. However, it does not explicitly state when not to use it or directly compare with siblings like call_agent for alternatives.

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

call_statusA

Get one phone mission by id, or list recent phone missions when id is omitted.

ParametersJSON Schema
NameRequiredDescriptionDefault
idNoPhone mission id
statusNoOptional status filter when listing missions
limitNoMax missions when listing (default: 20, max: 100)
offsetNoSkip missions when listing
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4/5.0
Behavior3/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the basic functionality without detailing aspects like return format, authentication requirements (e.g., _account parameter), rate limits, or pagination behavior. The description is minimal but not misleading.

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?

The description is a single, well-structured sentence that front-loads the core function and efficiently covers both modes of operation (get by ID and list recent). No unnecessary words or redundancy.

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?

Given the absence of an output schema and the relative simplicity of a list/get tool, the description is mostly complete. It explains the two modes and implies the use of limit/offset. A minor gap is the lack of explicit mention that listing returns 'recent' missions, which is already implied. The description is adequate for the tool's complexity.

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?

The input schema has 100% description coverage, so parameters like id, status, limit, offset, and _account are already documented. The description adds no extra meaning beyond implying that 'id' is for single fetch and omission triggers listing. This meets the baseline for high coverage.

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?

The description clearly states two distinct actions: getting a single phone mission by ID or listing recent missions when ID is omitted. The verb+resource combination is specific and distinguishes this tool from sibling tools like call_agent, call_phone, and call_transcript, which deal with different aspects of phone functionality.

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?

The description provides clear context on when to use this tool (for fetching one mission by ID or listing recent missions). It does not explicitly state when not to use it or mention alternative tools, but the purpose is well-defined, making guidance adequate.

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

call_transcriptC

Read the transcript entries recorded for a phone mission.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesPhone mission id
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations, the description bears full responsibility for behavioral context. It indicates a read operation but does not disclose what is returned, potential side effects, or access requirements. This is insufficient for a tool that reads data.

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?

Single sentence with no waste, efficiently stating the tool's purpose. However, it could be slightly more informative without sacrificing conciseness.

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

Completeness2/5

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

Missing output schema, and description does not clarify the format or structure of returned transcript entries. No information on when to expect results (e.g., after call completion) or error handling.

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?

Schema coverage is 100%, with clear descriptions for both parameters. The description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate.

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?

The description clearly states the tool reads transcript entries for a phone mission, using a specific verb and resource. It distinguishes from siblings like call_status and call_agent by focusing on transcript reading. However, could be more precise by specifying it returns entries for a given mission ID.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives like call_status or call_agent. The description simply states what it does without context for appropriate use cases or prerequisites.

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

check_activityA

Check which agents are currently being woken by the dispatcher. Use this when you sent mail to a teammate and want to know if they have actually started working, or to audit the live multi-agent state. Returns active workers with the agent name, what triggered the wake (mail UID + subject, or task id), how long they have been running, the most recent tool they invoked, how many tool calls they have made, a stale flag (true if the dispatcher has not heartbeated in 90s+), and a preview of recently-finished work. Workers may run for hours — there is no auto-eviction; staleness is just a hint. Requires master key.

ParametersJSON Schema
NameRequiredDescriptionDefault
agentNoFilter to a specific agent by name (case-insensitive). Omit to see every active and recently-finished worker.
includeRecentNoInclude workers that finished in the last ~2 minutes (default: true). Set false to see only currently-running workers.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.4/5.0
Behavior4/5

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

No annotations provided, so description carries full burden. It discloses return fields, staleness behavior (90s+), no auto-eviction, and master key requirement. Sufficiently transparent.

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?

Four sentences, front-loaded purpose, minimal redundancy. Could slightly tighten, but overall efficient and well-structured.

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 description fully explains return fields, staleness, and behavior. Covers all necessary context for using the tool.

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%, but description adds value: case-insensitive filtering for agent, meaning of stale flag, and details for _account authentication. Adds meaning beyond 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?

The description clearly states the tool checks which agents are being woken by the dispatcher, with specific use cases (after sending mail or auditing multi-agent state). It distinguishes from siblings like check_messages or check_tasks by focusing on agent activity.

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?

Explicit when to use: when you sent mail to a teammate to see if they started working, or to audit live multi-agent state. Does not mention when not to use or alternatives, but implied context is clear.

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

check_gateway_statusA

Check the current email gateway status — relay mode, domain mode, or not configured

ParametersJSON Schema
NameRequiredDescriptionDefault
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.8/5.0
Behavior3/5

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

Without annotations, the description carries full burden. It indicates a read-only 'check' operation and hints at possible return values, but does not disclose error conditions, side effects, or what 'not configured' implies. Reasonable but not thorough.

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?

The description is a single, focused sentence that conveys the essential information without any redundant words. It is well-structured for quick understanding.

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 simple status-check tool with one optional parameter and no output schema, the description adequately covers the purpose and possible returns. It could briefly explain why this check might be necessary, but it is largely complete.

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?

The input schema already describes the only parameter (_account) with 100% coverage. The description adds no additional meaning or usage context for the parameter, so it contributes no extra value beyond 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?

The description clearly states the tool checks email gateway status and enumerates possible states (relay mode, domain mode, or not configured). It uses a specific verb and resource, and no sibling tool duplicates this purpose.

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

Usage Guidelines3/5

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

The description implies usage for checking gateway status but provides no guidance on when to use it over alternatives or when not to use it. There are no explicit conditions or exclusions, leaving the agent to infer context.

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

check_healthB

Check 🎀 AgenticMail server health status

ParametersJSON Schema
NameRequiredDescriptionDefault
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

B3.1/5.0
Behavior3/5

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

Without annotations, the description carries the burden. The verb 'check' implies a read-only operation, but no explicit statement about non-destructiveness or safety. It is adequate but not explicit.

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 description is a single focused sentence with no filler. It is concise, though could benefit from additional context without becoming verbose.

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

Completeness2/5

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

For a health check tool, the description lacks output format details (e.g., status fields, uptime). With no output schema, the agent cannot infer return structure. Essential context is missing.

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?

Schema coverage is 100%, and the description adds no extra meaning beyond the schema's parameter description. The parameter is already well-documented in the schema, so baseline score of 3 is appropriate.

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?

The description clearly states the tool checks 'AgenticMail server health status', which is specific. However, it does not distinguish from similar sibling tools like 'check_gateway_status' or 'check_activity', so a small deduction applies.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives. The description does not indicate scenarios or exclusions, leaving the agent without context for appropriate invocation.

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

check_messagesA

Check for new unread messages from other agents or external senders. Returns a summary of pending communications. Use this to stay aware of requests and coordinate with other agents.

ParametersJSON Schema
NameRequiredDescriptionDefault
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.7/5.0
Behavior3/5

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

No annotations provided, so description must cover behavior. It states it returns a summary of pending communications but does not disclose side effects (e.g., whether messages are marked as read) or authentication details beyond the schema.

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?

Two concise sentences, front-loaded with the key action and outcome. No redundant information.

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

Completeness3/5

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

Description covers purpose and usage but lacks output format or return structure. With no output schema, the description should at least indicate what the summary contains (e.g., message count, sender list). Adequate but not fully complete.

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?

Schema coverage is 100% with one parameter fully described. The description adds no additional parameter information, so baseline score of 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?

The description clearly states the verb 'Check' and the resource 'new unread messages' from agents or external senders. It distinguishes itself from sibling tools like send_email or read_email by focusing on unread message retrieval.

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

Usage Guidelines3/5

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

The description provides a usage hint 'Use this to stay aware of requests and coordinate with other agents' but lacks explicit guidance on when not to use it or alternatives such as list_inbox or check_activity.

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

check_tasksA

Check for pending tasks assigned to you (or a specific agent) or tasks you assigned to others

ParametersJSON Schema
NameRequiredDescriptionDefault
directionNoincoming (assigned to me) or outgoing (I assigned)
assigneeNoCheck tasks for a specific agent by name (only for incoming direction)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4/5.0
Behavior3/5

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

No annotations provided. Description discloses filtering capabilities but does not specify if it's read-only, authentication needs (though _account param hints), or other behavioral traits. Adequate but minimal.

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?

Single sentence, clear and to the point, no extraneous information.

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?

Adequately covers the tool's purpose and parameters. Lacks description of return format, but for a simple list tool, it's sufficient given no output schema.

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?

Schema coverage is 100%, so parameters are documented. Description adds context by explaining the meaning of direction and ability to check for a specific agent, but does not add significant new detail beyond 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?

Description clearly states the tool checks pending tasks with two directions: assigned to you or assigned by you. It distinguishes from siblings like claim_task and check_activity.

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?

Description indicates usage for viewing tasks by direction and optional assignee, but does not explicitly state when not to use or mention alternatives. Context from siblings helps but is not explicit.

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

claim_taskB

Claim a pending task assigned to you

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesTask ID to claim
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

B3.1/5.0
Behavior2/5

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

No annotations provided, so description carries full burden. It does not disclose side effects, permissions needed, or success/failure behavior. A claim action may have implications (e.g., prevents others from claiming), but not mentioned.

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?

One concise sentence that efficiently conveys the main purpose. No unnecessary words, but could benefit from a bit more context without losing conciseness.

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

Completeness2/5

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

Given the simplicity (2 params, no output schema), the description is too brief. It does not explain what happens after claiming, error conditions, or if the task must be in a specific state. More details would improve completeness.

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?

Schema coverage is 100% with good descriptions for both parameters. The description adds no additional meaning beyond the schema, meeting the baseline of 3.

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?

The description clearly states the action (claim) and the resource (pending task assigned to you). It distinguishes from siblings like check_tasks by specifying the action of claiming a pending task.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives like check_tasks or batch operations. Missing context about prerequisites (e.g., task must be pending and assigned to you).

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

cleanup_agentsB

List or remove inactive non-persistent agent accounts (requires master API key)

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYesAction to perform
hoursNoInactivity threshold in hours (default: 24)
dryRunNoPreview without deleting (for cleanup)
agentIdNoAgent ID (for set_persistent)
persistentNoSet persistent flag (for set_persistent)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

B3.4/5.0
Behavior3/5

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

With no annotations provided, the description carries the burden of disclosing behavioral traits. It mentions the 'cleanup' action and the 'dryRun' parameter for preview, which hints at destructive behavior. However, it does not detail what happens during cleanup (e.g., irreversible deletion, dependencies), lack reversibility info, or mention rate limits. It adds some value beyond the schema but is not thorough.

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 description is a single sentence with no wasted words. It front-loades the core action and resource, with the authentication requirement appended in parentheses. It is concise and efficient, though it could benefit from slightly more structure.

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

Completeness3/5

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

Given the tool has 6 parameters and no output schema, the description covers the basic action and requirement but does not explain what defines 'inactive' or 'non-persistent', nor what response to expect. The schema explains parameters, but the description lacks completeness regarding the tool's behavior and results. Adequate but with gaps.

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?

Schema description coverage is 100%, so the input schema already documents all parameters adequately. The description adds no extra meaning beyond the schema; it only reiterates the tool's overall purpose. Baseline score of 3 is appropriate since the schema does the heavy lifting.

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?

The description clearly states the verb (List or remove) and the resource (inactive non-persistent agent accounts), and distinguishes from siblings like delete_agent or list_agents by specifying the scope (inactive, non-persistent). It also notes the authentication requirement (requires master API key), making the purpose unambiguous.

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

Usage Guidelines2/5

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

The description does not provide explicit guidance on when to use this tool versus alternatives like delete_agent or list_agents. It mentions an authentication requirement but no context on when not to use it or which situations call for sibling tools. The usage is implied but not clearly delineated.

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

create_accountA

Create a new AgenticMail agent (email account + identity + API key + persona derived from role/metadata). Requires master API key. After creation: address them at <name>@localhost, delegate work via call_agent({ target: "<name>", task: ... }), or hand off via send_email / message_agent. The new agent acts as themselves — you never need to (and must not) roleplay them inside your host's native sub-agent tool.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesAgent name (will be used as email local part)
domainNoEmail domain (default: localhost)
roleNoAgent role (default: secretary)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations provided, the description discloses key behavioral traits: requires master API key, creates an independent agent that acts as itself, and includes a prohibition on roleplaying. It does not detail side effects like overwriting existing accounts, but for a creation tool this is sufficient.

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?

Three sentences, front-loaded with the core action, then usage guidelines, then behavioral constraint. Every sentence adds value without redundancy.

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?

Covers creation process and post-creation workflow adequately. No output schema exists, but the description does not specify return values. However, for a creation tool, the side effect (agent created) is the primary outcome, and the instructions on how to use the new agent compensate for the lack of return value documentation.

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?

Schema coverage is 100%, so the parameters are already well-described. The description adds no extra meaning beyond what the schema provides, earning the baseline score.

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?

The description clearly states 'Create a new AgenticMail agent' with specific details (email account, identity, API key, persona). It distinguishes itself from sibling tools like list_agents or delete_agent by focusing solely on creation.

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 mentions requirement of master API key and provides post-creation usage instructions (address as <name>@localhost, delegate via call_agent, handoff via send_email/message_agent). Also warns against roleplaying inside host's native sub-agent tool, providing clear when-not-to-use guidance.

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

create_folderB

Create a new mail folder for organizing emails

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesFolder name (e.g., Projects, Clients, Newsletters)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

B3.2/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden. It states 'Create' which implies mutation, but does not disclose what happens on success, error cases, or if the folder already exists.

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 description is concise at 8 words, front-loaded with the action. It could benefit from slight expansion for context, but maintains efficiency.

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

Completeness3/5

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

For a simple creation tool with no output schema, the description is adequate but lacks details on success feedback, error handling, or naming constraints. It meets minimum viability.

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?

Schema description coverage is 100%, so the parameter meanings are clear from the schema. The description adds no extra value beyond the schema's parameter descriptions. Baseline of 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?

The description clearly states the verb 'Create' and resource 'mail folder' with the purpose of organizing emails. It distinguishes from sibling tools like list_folder and list_folders, which are for listing.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool vs alternatives, no prerequisites, and no context about when not to use it. It lacks any usage instructions.

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

delete_agentA

Delete an agent account. Archives all emails and generates a deletion report before removing the account permanently. Returns the deletion summary. Requires master API key.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesName of the agent to delete
reasonNoReason for deletion (optional)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4/5.0
Behavior4/5

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

With no annotations, the description provides good behavioral details: archives emails, generates a deletion report, removes permanently, and returns a summary. However, it does not mention reversibility or potential side effects beyond what's stated.

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?

The description is three sentences, front-loaded with the action, and contains no unnecessary information. Every sentence adds value.

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 deletion tool with no output schema, the description covers the process, return value, and authentication requirement. The mention of 'deletion report' is helpful, though more detail on the report's content could be added.

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?

Schema description coverage is 100%, so the schema fully documents parameters. The description does not add additional meaning beyond what's in the schema, meeting the baseline for high coverage.

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?

The description clearly states the tool deletes an agent account, distinguishes from siblings like batch_delete (for emails) and cleanup_agents (potentially different scope), and outlines key actions (archiving, report generation).

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

Usage Guidelines3/5

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

The description mentions 'Requires master API key' indicating a prerequisite, but does not explicitly state when to use this tool over alternatives or provide exclusions. Usage context is implied but not fully explicit.

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

delete_emailA

Delete an email by its UID

ParametersJSON Schema
NameRequiredDescriptionDefault
uidYesThe UID of the email to delete
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.5/5.0
Behavior2/5

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

No annotations are provided, so the description bears full burden. It only states the action 'delete' without disclosing whether deletion is permanent or reversible, required permissions, or any side effects. This is insufficient for a mutation tool.

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?

The description is a single, clear sentence with no extraneous words. It is perfectly concise and front-loaded.

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

Completeness3/5

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

Given the simple input and no output schema, the description provides the basic action but lacks behavioral completeness. Missing details on deletion semantics (hard/soft), undo capability, or expected side effects. Adequate but not thorough.

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?

Schema coverage is 100%, so description adds no insight beyond what the schema already provides for 'uid' and '_account'. Baseline of 3 is appropriate as the schema itself is descriptive.

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?

The description clearly states the verb 'delete', resource 'email', and means 'by its UID'. It succinctly identifies the tool's specific function, differentiating from sibling tools like batch_delete.

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

Usage Guidelines3/5

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

The description implies usage for single email deletion but provides no explicit guidance on when to use this tool versus alternatives like batch_delete or move_email. No when-not-to-use or contextual hints are given.

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

deletion_reportsA

List past agent deletion reports or retrieve a specific report by ID. Shows archived email summaries from deleted agents. Requires master API key.

ParametersJSON Schema
NameRequiredDescriptionDefault
idNoDeletion report ID (omit to list all reports)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.9/5.0
Behavior3/5

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

With no annotations, the description carries the full burden. It discloses the output content ('archived email summaries') and the auth requirement, but omits details on potential side effects, rate limits, or pagination. It does not contradict annotations (none provided).

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?

The description is two sentences, front-loaded with the core action, and contains no extraneous information.

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

Completeness3/5

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

Given the lack of output schema, the description should elaborate on the report structure. It mentions 'archived email summaries' but not the format or fields. It adequately explains the core functionality but lacks depth for full contextual understanding.

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?

Schema coverage is 100%, so the schema already describes both parameters. The description adds no extra meaning beyond what's in the schema, resulting in a baseline score of 3.

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?

The description clearly states the tool's purpose: 'List past agent deletion reports or retrieve a specific report by ID.' It distinguishes itself from sibling tools like 'delete_agent' by focusing on reading archived reports rather than performing deletions.

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?

The description includes a crucial prerequisite: 'Requires master API key.' This guides the agent on when the tool can be used. However, it does not explicitly contrast it with alternative tools or state when not to use it.

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

forward_emailA

Forward an email to another recipient. Outbound guard applies — HIGH severity content is held for review. Pass wake to limit which local recipients get a host turn from the dispatcher when this forward lands.

ParametersJSON Schema
NameRequiredDescriptionDefault
uidYesUID of the email to forward
toYesRecipient to forward to
textNoAdditional message (optional)
wakeNoOptional. Names of the agents who should get a host turn when the forward lands. Pass `[]` to deliver silently. Omit to wake everyone CC'd.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.8/5.0
Behavior3/5

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

No annotations are provided, so the description carries full burden. It discloses the outbound guard behavior and the wake parameter's effect, which adds value beyond the schema. However, it does not explain what 'held for review' means operationally (e.g., blocks or delays), and the 'host turn from the dispatcher' jargon is unclear. More detail on side effects (e.g., original email status) is missing.

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?

The description consists of two concise, front-loaded sentences. The first states the primary action, and the second adds critical behavioral context. Every sentence provides value with no fluff.

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

Completeness2/5

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

Given no output schema and no annotations, the description should cover return behavior and side effects. It fails to indicate what happens after successful forwarding (e.g., confirmation, error handling). It also omits explanation of the '_account' parameter in the description, relying solely on the schema. The complexity of 5 parameters with 2 required and a wake mechanism warrants more thorough context.

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?

Schema coverage is 100% with detailed parameter descriptions. The description adds minimal semantics beyond the schema, only slightly elaborating on the 'wake' parameter's purpose. It does not mention the '_account' override parameter or provide additional format or constraint details.

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?

The description clearly states the verb 'forward' and the resource 'email to another recipient.' It distinguishes from sibling tools like send_email (compose new) and reply_email (reply in thread) by its specific action of forwarding an existing email.

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?

The description mentions the outbound guard that holds HIGH severity content for review, providing context on when forwarding might be restricted. It also explains the 'wake' parameter's effect on agent host turns. However, it does not explicitly state when to use this tool over alternatives like move_email or send_email.

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

get_thread_idA

Resolve the stable thread id for a message UID. Use this BEFORE calling save_thread_memory or when you want to inspect the cache for a thread. Pass the UID of any message on the thread (root or reply) — the API normalises the subject, resolves the canonical root sender, and returns the same id every time. folder defaults to INBOX.

ParametersJSON Schema
NameRequiredDescriptionDefault
uidYesMessage UID.
folderNoIMAP folder where the UID lives. Defaults to INBOX.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations, the description carries full burden. It explains that the API normalizes the subject, resolves the canonical root sender, and returns the same id every time, which adds behavioral context. It also notes the default folder. However, it does not disclose error scenarios or rate limits.

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?

The description is three sentences: purpose, usage guideline, and behavior/default. It is front-loaded with the core action, and every sentence adds value without redundancy.

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?

Given the tool's simplicity (3 params, none complex), the description covers essential context: stable id resolution, input constraints, default folder, and id stability. Missing details like return type or error behavior are minor given the tool's straightforward nature.

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 schema already describes each parameter. The description adds value by clarifying that the uid can be from any message on the thread (root or reply), which is not explicit in the schema. This extra nuance improves understanding beyond the schema alone.

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?

The description uses the specific verb 'resolve' and identifies the resource as 'stable thread id', clearly stating what the tool does. It distinguishes from siblings by advising to use it before 'save_thread_memory' and for inspecting the cache.

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?

The description explicitly states when to use the tool ('BEFORE calling save_thread_memory' and 'when you want to inspect the cache'), providing clear context. However, it lacks explicit 'when not to use' guidance or direct naming of alternatives beyond 'save_thread_memory'.

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

import_relay_emailA

Import an email from the connected Gmail/Outlook account into the agent's local inbox. This downloads the full message with all headers (Message-ID, In-Reply-To, References) so you can continue the thread using reply_email. Use search_emails with searchRelay=true first to find the relay UID.

ParametersJSON Schema
NameRequiredDescriptionDefault
uidYesThe relay UID of the email to import (from search_emails relay results)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.3/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. It discloses that the tool downloads the full message with headers and imports it into the agent's local inbox, providing sufficient behavioral context. It could mention authentication or permissions, but overall good.

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?

The description is two sentences, front-loaded with the purpose, and every sentence adds value. No unnecessary words or repetition.

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?

Given the simplicity of the tool (2 params, no output schema), the description covers input, process, and next steps completely. It is self-contained and provides all necessary context for correct usage.

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?

Schema coverage is 100% with descriptions for both parameters. The description adds useful context for uid (where to get it from search_emails) and briefly mentions _account, but the schema already explains these adequately.

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?

The description clearly states the tool imports an email from a connected Gmail/Outlook account into the local inbox, specifies the verb and resource, and distinguishes from siblings like search_emails and reply_email by indicating the workflow.

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?

The description explicitly advises using search_emails with searchRelay=true first to obtain the relay UID, and suggests using reply_email after import. This provides clear context on when to use the tool, though it does not explicitly state when not to use it.

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

inbox_digestA

Get a compact inbox digest with subject, sender, date, flags and text preview for each message. More efficient than listing then reading individually.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax messages (default: 20, max: 50)
offsetNoSkip messages (default: 0)
folderNoFolder (default: INBOX)
previewLengthNoPreview text length (default: 200, max: 500)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4/5.0
Behavior3/5

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

No annotations provided; description indicates a read operation returning digest fields, but does not discuss side effects, rate limits, or authorization. Adequate but minimal disclosure.

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?

Two efficient sentences that convey purpose and benefit without unnecessary words. Front-loaded with action and output.

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?

Given no output schema, description lists returned fields (subject, sender, etc.), providing sufficient context for agent to understand result. Lacks pagination/sorting details but adequate for a digest tool.

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?

All 5 parameters have descriptions in the schema (100% coverage). The description adds no additional meaning beyond what the schema already provides.

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?

Clearly states the tool retrieves a compact inbox digest with specific fields (subject, sender, date, flags, preview). Distinguishes from siblings by emphasizing efficiency vs. listing then reading individually.

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?

Provides context: 'More efficient than listing then reading individually.' This implies when to use, but does not explicitly name alternatives or exclusions.

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

invokeA

Call ANY AgenticMail tool by name with structured args — including tools not in your pre-loaded tool list. Use after request_tools to discover the right tool. Pass _account either at the top level OR inside args; either works. Example: invoke({ tool: "manage_signatures", args: { action: "create", name: "default", body: "—\nFola" }, _account: "Fola" }).

ParametersJSON Schema
NameRequiredDescriptionDefault
toolYesThe AgenticMail tool name to call (e.g. "manage_signatures", "sms_send"). See request_tools for the full catalogue.
argsNoArguments for the target tool. Same shape you would pass if calling the tool directly.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.2/5.0
Behavior3/5

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

No annotations are provided, so the description bears full responsibility. It explains the dynamic calling and parameter flexibility but omits details about error handling, auth requirements beyond account override, or side effects. Adequate but not comprehensive.

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?

Three sentences plus an example. Every sentence adds essential information with no waste. Front-loaded with the core purpose, then usage hints.

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?

Given the complexity of a generic invocation tool with dynamic tool discovery, the description covers the usage flow, parameter flexibility, and provides an example. No output schema exists, which is acceptable as the return depends on the called tool. Minor gap: no mention of potential failures or limits.

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% for 3 parameters. The description adds value by explaining `_account` can be top-level or inside args, and provides an example. This enhances understanding beyond 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?

The description clearly states it can call any AgenticMail tool by name with structured args, including tools not in the pre-loaded list. It distinguishes from sibling tools that are specific operations, serving as a generic invocation mechanism.

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?

It explicitly advises using after `request_tools` to discover the right tool, and explains the flexible placement of `_account`. While it doesn't specify when not to use, the guidance is clear and actionable.

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

list_agentsA

List all AI agents in the system with their email addresses and roles. Use this to discover which agents you can call via call_agent (sync RPC) or email via send_email / message_agent (async). DO NOT spawn one of your host's native sub-agents and roleplay AS these agents — each one is a real identity with its own mailbox; just address them through AgenticMail and let them work as themselves.

ParametersJSON Schema
NameRequiredDescriptionDefault
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.1/5.0
Behavior3/5

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

No annotations provided. Description is concise but does not disclose behavioral traits like whether it lists only active agents, pagination, or auth implications. Adequate but lacks depth.

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?

Two sentences plus a useful note on roleplaying. Information is front-loaded and every sentence adds value, though the roleplaying note could be a separate caution.

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?

Given the simple list operation and no output schema, the description mentions returned fields (email, roles). It is mostly complete for the tool's purpose, though pagination or limits are not covered.

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?

The only parameter '_account' has full schema description coverage (100%). The tool description adds no extra meaning beyond the schema, earning the baseline score.

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 'List all AI agents in the system with their email addresses and roles' – a specific verb+resource. Differentiates from siblings by mentioning call_agent, send_email, etc.

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 'Use this to discover which agents you can call...' and provides a negative guideline about not roleplaying. Clear when and when-not to use.

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

list_folderC

List messages in a specific folder

ParametersJSON Schema
NameRequiredDescriptionDefault
folderYesFolder path (e.g., INBOX, Trash, Sent)
limitNoMax messages (default: 20)
offsetNoSkip messages (default: 0)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations, the description carries the full burden of behavioral disclosure, but it only states 'List messages'. It does not reveal whether the operation is read-only, what data is returned (e.g., headers vs. full messages), pagination behavior, or ordering. Critical behavioral traits are omitted.

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 description is a single, front-loaded sentence with no wasted words. It is concise but perhaps too minimal. While it achieves brevity, it could incorporate more contextual details without becoming verbose.

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

Completeness2/5

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

Given the tool has 4 parameters, no output schema, and many sibling tools, the description is incomplete. It fails to explain return format, pagination, sorting, or the purpose of the _account parameter. The tool's role within the broader set of list/search tools is unclear.

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?

Schema description coverage is 100%, so the schema already documents all parameters, including folder, limit, offset, and _account. The description adds no additional semantic information beyond the schema. Per the rules, baseline 3 is appropriate.

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?

The description clearly states 'List messages in a specific folder', providing a specific verb and resource. However, it does not differentiate from sibling tools like list_inbox or search_emails, which also list messages. The tool's name and schema imply context, but explicit differentiation is missing.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives such as list_inbox, search_emails, or batch_read. There is no mention of prerequisites, restrictions, or when not to use it. The description lacks explicit usage context.

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

list_foldersB

List all mail folders/mailboxes

ParametersJSON Schema
NameRequiredDescriptionDefault
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

B3.2/5.0
Behavior3/5

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

The description implies a read-only operation, but lacks details about authentication requirements, whether system folders are included, or behavior with empty mailboxes. Without annotations, the description carries full burden but only provides minimal behavior.

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 description is a single clear sentence, appropriately concise. However, it could be slightly expanded to include return type or folder scope without losing conciseness.

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

Completeness3/5

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

For a simple list operation with one optional parameter, the description is mostly adequate. However, without an output schema, the return format could be mentioned for completeness.

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?

The input schema covers 100% of parameters with descriptions. The tool description does not add meaning beyond the schema, so baseline 3 applies.

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?

The description clearly states the tool lists all mail folders/mailboxes, indicating the verb 'List' and the resource. It is distinct from siblings like 'list_folder' (singular) and 'list_inbox' (inbox only), though not explicitly differentiating.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of use cases, prerequisites, or when not to use it.

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

list_inboxC

List recent emails in the agent's inbox

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of messages to return (default: 20)
offsetNoNumber of messages to skip (default: 0)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

C2.9/5.0
Behavior2/5

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

No annotations are provided, and the description does not disclose behavioral traits like read-only nature, authentication requirements beyond the _account parameter, or return format. The agent lacks information about side effects (e.g., marking as read) or pagination behavior.

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 description is a single sentence with no unnecessary words. It is appropriately brief, though slightly more detail (e.g., result format) could be added without harming conciseness.

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

Completeness2/5

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

Given the absence of an output schema and annotations, the description fails to explain return values, default ordering, or pagination semantics. For a list tool, this is insufficient for complete understanding.

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?

Schema description coverage is 100% with descriptions for all three parameters (limit, offset, _account). The description adds no additional meaning beyond what the schema already provides, landing at the baseline score.

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?

The description 'List recent emails in the agent's inbox' clearly states the action (list) and the resource (recent emails in the inbox), distinguishing it from siblings like 'search_emails' or 'list_folder'. However, 'recent' is not precisely defined.

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

Usage Guidelines2/5

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

No explicit guidance on when to use this tool versus alternatives such as 'inbox_digest', 'search_emails', or 'read_email'. The description does not mention when to prefer this tool over others.

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

manage_contactsC

List, add, or delete contacts

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYesAction to perform
emailNoContact email (for add)
nameNoContact name (for add)
idNoContact ID (for delete)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

C2.9/5.0
Behavior2/5

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

No annotations provided, so description must disclose behaviors. It only states actions without mentioning side effects, permanence, or auth requirements for add/delete operations.

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?

Extremely concise at six words, front-loaded with verbs. Every word is essential, no filler.

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

Completeness2/5

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

Lacks explanation of how actions relate to parameters (e.g., email/name for add, id for delete). No output schema described, leaving return format ambiguous for a tool with multiple behaviors.

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?

Schema description coverage is 100%, so baseline is 3. The description adds no extra meaning beyond what the schema already provides via parameter descriptions.

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?

The description clearly states the actions (list, add, delete) and resource (contacts). It distinguishes from sibling tools like manage_tags or manage_spam, though it could be more specific about scope (e.g., user's address book).

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives like manage_tags or batch operations. Does not provide prerequisites or exclusions.

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

manage_draftsA

List, create, update, send, or delete drafts. On send, you can pass wake to limit which local recipients get a host turn — same semantics as send_email.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYesAction to perform
idNoDraft ID (for update/send/delete)
toNoRecipient (for create/update)
subjectNoSubject (for create/update)
textNoBody text (for create/update)
wakeNoOptional, for action=send. Names of the agents who should get a host turn when the drafted mail lands. Pass `[]` to deliver silently. Omit to wake everyone CC'd.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4/5.0
Behavior3/5

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

No annotations are provided, so the description alone must disclose behavioral traits. It mentions actions (create/update/send/delete are mutations, list is read-only) and the wake parameter's effect, but lacks details on permissions, rate limits, or side effects beyond the actions listed.

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?

Two sentences: first lists all actions, second explains the key parameter behavior. No extra words; every sentence earns its place. Front-loaded with actions.

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 multi-action tool with 7 parameters and no output schema, the description covers the core functionality and special parameter behavior. It lacks details on return values or prerequisites, but the actions are clear and the wake explanation is helpful.

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. The description adds value by explaining the wake parameter's semantics with a cross-reference to send_email, which goes beyond the schema's basic description. Other parameters are not elaborated beyond 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?

The description clearly lists all five actions (list, create, update, send, delete) and specifies the resource (drafts). It distinguishes from siblings like send_email by focusing on draft management and referencing 'same semantics as send_email' for the wake parameter.

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

Usage Guidelines3/5

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

Provides a hint about when to use the wake parameter ('On send...') and cross-references send_email, but does not explicitly guide when to choose this tool over siblings like send_email or batch_delete for related tasks.

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

manage_pending_emailsA

Check the status of pending outbound emails blocked by the outbound guard. You can list all your pending emails or get details of a specific one. You CANNOT approve or reject — only the owner can do that.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYesAction to perform (list or get only — approve/reject require owner)
idNoPending email ID (required for get)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.2/5.0
Behavior4/5

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

No annotations are provided, so the description carries the burden. It states the tool is read-only for the agent (only owner can approve/reject) and limits actions to list and get. It does not disclose any further behavioral traits like rate limits or response structure, but the key limitation is clearly communicated.

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?

The description is two sentences: the first states the tool's purpose and actions, the second states what cannot be done. It is front-loaded, concise, and every sentence adds value without redundancy.

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 simple list/get tool with 3 parameters and no output schema, the description covers the core functionality and key limitation. It lacks details on output format, but the tool's purpose is clear. The niche is well-defined among many siblings.

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?

Schema coverage is 100% and schema descriptions already explain action enum, id, and _account. The description reinforces the limitation on approve/reject but adds no new parameter-level detail beyond what the schema provides. Baseline of 3 is appropriate.

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?

The description clearly states the tool checks pending outbound emails blocked by the outbound guard, and specifies the exact actions: list all or get details. It distinguishes itself from sibling tools like manage_drafts or manage_rules by targeting a specific email state.

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?

The description explains when to use the tool: to check status of pending emails. It explicitly states what cannot be done (approve/reject) and who can do that (owner), providing clear usage boundaries. However, it does not mention alternative tools for approval/rejection.

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

manage_rulesB

Manage server-side email rules that auto-process incoming messages (move, tag, mark read, delete).

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYesAction to perform
idNoRule ID (for delete)
nameNoRule name (for create)
priorityNoHigher priority rules match first (for create)
conditionsNoMatch conditions: { from_contains?, subject_contains?, subject_regex?, to_contains?, has_attachment? }
actionsNoActions on match: { move_to?, mark_read?, delete?, add_tags? }
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

B3.3/5.0
Behavior2/5

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

With no annotations, the description carries full burden but only states the tool's purpose. It omits behavioral details such as whether rules are applied immediately, permanent effects, or authentication requirements beyond the schema.

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?

Single sentence, completely front-loaded with no extraneous information. Every word earns its place.

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

Completeness3/5

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

Given the complexity (nested objects, 7 params, no output schema), the description is minimal. It does not explain return values or provide usage examples, but the schema fills critical gaps.

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?

Schema coverage is 100% and descriptions are already provided for all parameters. The tool description adds no additional meaning beyond what the schema offers.

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?

The description uses specific verbs 'Manage' and 'auto-process' with resource 'server-side email rules', and lists concrete actions (move, tag, mark read, delete). This clearly distinguishes it from sibling tools like batch_mark_read or batch_delete.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives. For example, it does not explain when to create a rule vs using batch operations directly, nor does it mention prerequisites like mailbox configuration.

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

manage_scheduledA

Manage scheduled emails: create a new scheduled email, list pending ones, or cancel one. Accepts flexible time formats for create: ISO 8601, relative ("in 30 minutes"), named ("tomorrow 8am"), day-based ("next monday 9am"), or human-friendly ("02-14-2026 3:30 PM EST").

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYesAction to perform (default: create)
toNoRecipient email (for create)
subjectNoEmail subject (for create)
textNoBody text (for create)
sendAtNoWhen to send (for create)
idNoScheduled email ID (for cancel)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.7/5.0
Behavior3/5

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

No annotations provided, so description must cover behavioral traits. It discloses flexible time formats for create, which is helpful. However, it lacks details on side effects (e.g., email delivery cancellation behavior, confirmation requirements).

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?

Two clear, front-loaded sentences. No redundant information; each sentence serves a purpose: stating the tool's function and detailing an important parameter behavior.

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?

Adequately covers actions and key parameter detail. Lacks return value information since no output schema is provided. However, for a CRUD-like tool, the description is reasonably complete given schema coverage.

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?

Input schema provides 100% coverage of 7 parameters. Description adds meaningful value beyond schema by explaining the flexible time formats for the 'sendAt' parameter, compensating for schema's lack of format details.

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?

Description clearly states the tool manages scheduled emails with three actions (create, list, cancel). It specifies the resource and actions but does not differentiate from similar sibling 'manage_pending_emails' which may overlap.

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

Usage Guidelines3/5

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

Provides context on actions but no explicit guidance on when to use this tool versus alternatives like 'manage_pending_emails' or 'send_email'. Usage is implied rather than directed.

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

manage_signaturesB

List, create, or delete email signatures

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYesAction to perform
idNoSignature ID (for delete)
nameNoSignature name (for create)
textNoSignature text content (for create)
isDefaultNoSet as default signature (for create)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

B3.1/5.0
Behavior2/5

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

With no annotations, the description fails to disclose behavioral traits such as whether create overwrites duplicates, delete is permanent, authentication requirements beyond schema, or rate limits. Only the basic actions are mentioned.

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 description is a single concise sentence that is front-loaded with the key purpose. It is efficient but could be more structured by explaining parameter dependency on action.

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

Completeness2/5

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

Given the tool has 6 parameters with conditional logic (action determines which parameters are needed), the description does not explain that create requires name/text, delete requires id. Also, no output schema or return value description is provided, leaving the outcome unclear.

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?

Schema description coverage is 100%, so each parameter is documented. However, the tool description adds no additional meaning beyond summarizing the actions. Baseline 3 is appropriate as the schema carries the burden.

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?

The description clearly states the tool's actions: 'List, create, or delete email signatures'. It specifies the verb and resource, and since there are no sibling tools for signatures, it is unambiguous.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It lists actions but does not explain the criteria for choosing 'list', 'create', or 'delete', nor does it compare to related tools like 'manage_templates' for templates.

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

manage_spamA

Manage spam: list spam folder, report a message as spam, mark as not-spam, or get the spam score of a message. Emails are auto-scored on arrival; high-scoring messages are moved to Spam automatically.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYesAction to perform
uidNoMessage UID (for report, not_spam, score)
folderNoSource folder (for report/score, default: INBOX)
limitNoMax messages to list (for list, default: 20)
offsetNoSkip messages (for list, default: 0)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.2/5.0
Behavior4/5

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

No annotations provided, so the description carries the full burden. It discloses that emails are auto-scored and moved to Spam automatically, and outlines the four actions. It does not detail side effects like moving messages, but the actions imply state changes.

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?

The description is two sentences, front-loaded with the purpose, and contains no unnecessary words. Every part is informative and efficient.

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?

Given the multi-action nature and lack of output schema, the description adequately covers the tool's capabilities and the auto-scoring behavior. It does not specify return formats for each action, which would improve completeness.

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?

The input schema describes all 6 parameters with clear descriptions (100% coverage). The description adds no extra meaning beyond the schema, so baseline 3 is appropriate.

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?

The description clearly states it manages spam with four specific actions (list, report, not_spam, score). It also provides context about auto-scoring, distinguishing it from generic folder listing tools.

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?

The description implies usage for spam-related actions but does not explicitly say when not to use it or list alternatives. However, the specific actions and auto-scoring context give clear guidance for when to invoke this tool over siblings like list_folder.

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

manage_tagsB

Create, list, delete tags, tag/untag messages, get messages by tag, or get all tags for a specific message.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYesAction to perform
nameNoTag name (for create)
colorNoTag color hex code (for create, e.g. #ff0000)
idNoTag ID (for delete, tag_message, untag_message, get_messages)
uidNoMessage UID (for tag_message, untag_message)
folderNoFolder the message is in (default: INBOX)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

B3.3/5.0
Behavior2/5

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

No annotations are provided, so the description bears full burden. It lists actions but does not disclose behavioral traits such as side effects (e.g., delete is destructive, tag_messages modifies state), authorization needs, or rate limits. The description adds minimal behavioral context beyond the enum.

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 description is a single sentence that front-loads the main purpose. It is efficient, listing all actions without excess. However, it could be more structured (e.g., grouping read vs write actions) without losing conciseness.

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

Completeness2/5

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

The tool has 7 parameters, 7 action enums, and no output schema. The description only covers the actions, omitting return values, error handling, or prerequisites. For a multi-action tool, this is insufficient for an agent to use it correctly without additional context.

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?

Schema coverage is 100%, achieving baseline 3. The description does not add meaning beyond what the schema provides (e.g., parameter names and descriptions like 'Tag name (for create)'). No additional constraints or usage examples are given.

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?

The description clearly enumerates all seven actions (create, list, delete, tag_message, untag_message, get_messages, get_message_tags) with specific verbs and resources. It distinguishes manage_tags from siblings as the only tag-specific tool.

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

Usage Guidelines3/5

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

The description implies usage through listing actions but provides no explicit guidance on when to use this tool versus alternatives, nor when not to use it. Given the sibling tools are numerous and non-tag, it is implicitly the right choice for tag operations, but no exclusions or context are given.

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

manage_templatesB

List, create, or delete email templates

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYesAction to perform
idNoTemplate ID (for delete)
nameNoTemplate name (for create)
subjectNoTemplate subject (for create)
textNoTemplate body text (for create)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

B3.1/5.0
Behavior2/5

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

With no annotations, the description carries full disclosure burden. It mentions 'delete' but does not indicate destructive side effects, required permissions, or authentication needs beyond the schema. No safety caveats are provided.

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 description is a single concise sentence that front-loads the core functionality. It wastes no words, though it could be slightly expanded to improve clarity without losing conciseness.

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

Completeness2/5

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

The tool performs multiple actions (create, list, delete) with conditional parameters and no output schema. The description does not explain return values, parameter dependencies per action, or behavior differences. This is insufficient for reliable agent 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?

Schema coverage is 100% with descriptions for all parameters. The description adds no additional meaning beyond the schema, such as clarifying conditional requirements (e.g., id needed for delete). Baseline 3 is appropriate given schema completeness.

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?

The description explicitly states 'List, create, or delete email templates', using specific verbs and resource. This clearly distinguishes from sibling tools like 'template_send' which sends templates, and other 'manage_*' tools that handle different resources.

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

Usage Guidelines2/5

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

The description lists supported actions but provides no guidance on when to use this tool over alternatives, nor does it explain prerequisites or appropriate contexts for each action. The agent is left to infer usage solely from the action enum.

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

mark_readC

Mark an email as read

ParametersJSON Schema
NameRequiredDescriptionDefault
uidYesUID of the email
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

C2.9/5.0
Behavior2/5

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

No annotations provided, and the description only states the action without disclosing behavioral traits like side effects, idempotency, or required permissions. For a state-modifying tool, this is insufficient.

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?

One short sentence that directly conveys the purpose. It is front-loaded and efficient, though arguably too minimal for deeper context.

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

Completeness3/5

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

For a simple tool with a single required parameter, the description is adequate. However, it lacks details about return values or behavior when the email is already read, which could be helpful.

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?

Schema coverage is 100%, and both parameters are described in the schema. The description adds no extra semantic value beyond what the schema already provides.

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?

The description clearly states the action ('mark an email as read') with a specific verb and resource. It is distinguishable from sibling tools like batch_mark_read or mark_unread.

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

Usage Guidelines2/5

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

No guidance on when to use this tool vs alternatives, such as batch_mark_read for multiple emails. The description only implies single-email usage via the uid parameter.

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

mark_unreadC

Mark an email as unread

ParametersJSON Schema
NameRequiredDescriptionDefault
uidYesUID of the email
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations, the description fails to disclose behavioral details beyond the obvious. It does not mention that the tool modifies email state, requires specific permissions, or handles the optional '_account' parameter for identity override.

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 description is extremely concise (one short sentence). While it is front-loaded and efficient, it could benefit from a bit more detail without becoming verbose.

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

Completeness2/5

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

The tool is simple but the description omits key context: it does not explain the return behavior, mention the optional parameter, or provide any completion guarantees. Given a large sibling set, the description is too sparse.

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?

Schema coverage is 100%, so the schema fully describes the parameters. The description adds no additional semantic context beyond the schema, which is acceptable but not improved upon.

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?

The description clearly states the action (mark as unread) and the resource (an email), which is sufficient. However, it does not explicitly differentiate from the sibling tool 'batch_mark_unread' by specifying it operates on a single email.

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

Usage Guidelines2/5

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

No usage context is provided. The description does not indicate when to use this tool versus alternatives like 'mark_read' or the batch version, leaving the agent without decision support.

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

media_audio_editB

Edit audio: trim, convert format, merge files, adjust volume, change speed, extract from video, reverse, fade in/out. Requires ffmpeg.

ParametersJSON Schema
NameRequiredDescriptionDefault
inputNoAbsolute path to the input audio (or video for extract). Not required for merge.
actionYesThe edit action.
startNoStart time (trim): "00:00:05" or "5".
endNoEnd time (trim): "00:00:15".
durationNoDuration (trim): "10".
formatNoOutput format: mp3, wav, ogg, flac, aac, m4a (convert/extract).
filesNoArray of file paths to merge (merge).
volumeNoVolume: "1.5" (150%), "0.5" (50%), or "10dB", "-5dB".
speedFactorNoSpeed: 0.5 = half, 2 = double (speed).
fadeTypeNoFade direction (fade).
fadeDurationNoFade duration in seconds (fade). Default: 3.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

B3.3/5.0
Behavior2/5

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

No annotations are provided, so the description must carry the full burden. It mentions a dependency (ffmpeg) but does not disclose whether the tool modifies input files or creates new ones, nor any side effects or permissions needed.

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 description is two sentences, front-loading the main purpose. It is concise, though could be slightly more structured (e.g., bullet points) for readability.

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

Completeness2/5

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

Given the complexity (12 params, 8 actions) and no output schema, the description is insufficient. It lacks information on return values, error handling, action-specific behavior, and whether input files are modified or copied.

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?

Schema coverage is 100% and the schema already describes each parameter. The description adds minimal extra meaning beyond the schema, such as the list of actions, but does not significantly augment parameter understanding.

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?

The description clearly states the tool edits audio and lists specific actions (trim, convert, merge, etc.). It distinguishes from siblings like media_video_edit by specifying audio.

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

Usage Guidelines3/5

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

The description implies usage for audio editing tasks but provides no explicit guidance on when to use alternatives or when not to use. It says 'Edit audio' which is clear but not prescriptive.

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

media_capabilitiesA

Report which media binaries (ffmpeg, ffprobe, ImageMagick, whisper.cpp, Python, edge-tts) are installed and available. Media tools are opt-in — call this first to see what operations are possible before attempting them.

ParametersJSON Schema
NameRequiredDescriptionDefault
refreshNoRe-probe the binaries instead of using the cached result (e.g. after installing one).
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.3/5.0
Behavior4/5

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

No annotations provided, so description carries full burden. It discloses the caching mechanism (implied by refresh parameter) and the opt-in nature of media tools. It doesn't detail rate limits or auth, but for a read-only capabilities check, this is adequate.

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?

Two sentences, no filler, front-loaded with the primary action. Every word serves a purpose.

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?

Given the tool's simplicity (no output schema, optional params), the description fully explains what it does and how it fits with sibling tools. It is complete for its purpose.

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?

Schema coverage is 100% (both parameters have descriptions). The description does not add meaning beyond the schema beyond context, which is appropriate for a simple tool.

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?

The description clearly states it reports which media binaries are installed, listing specific binaries (ffmpeg, ffprobe, etc.). It is distinct from sibling media operation tools like media_audio_edit or media_info, which are the operations to be checked.

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?

It explicitly says media tools are opt-in and to call this first before attempting operations. This provides clear when-to-use guidance but does not explicitly mention when not to use or alternatives, though the alternative is simply proceeding with a media operation.

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

media_image_editA

Edit an image: resize, crop, rotate, convert format, compress, overlay text, flip, blur, sharpen, grayscale. Requires ImageMagick.

ParametersJSON Schema
NameRequiredDescriptionDefault
inputYesAbsolute path to the input image.
actionYesThe edit action to perform.
widthNoTarget width in pixels (resize/crop).
heightNoTarget height in pixels (resize/crop).
angleNoRotation angle in degrees (rotate).
formatNoOutput format: png, jpg, webp, gif, bmp, tiff (convert).
qualityNoJPEG/WebP quality 1-100 (compress). Default: 80.
textNoText to overlay (text_overlay).
positionNoText position: north, south, center, northeast, etc. Default: south.
fontSizeNoFont size in points (text_overlay). Default: 36.
fontColorNoText colour (text_overlay). Default: white.
blurRadiusNoBlur radius (blur). Default: 5.
directionNoFlip direction. Default: horizontal.
offsetXNoCrop X offset from top-left. Default: 0.
offsetYNoCrop Y offset from top-left. Default: 0.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.8/5.0
Behavior3/5

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

With no annotations provided, the description carries the full burden. It lists operations but does not disclose side effects (e.g., whether the input file is overwritten or a new file is created), return value format, or authentication details (beyond the _account parameter in schema). The requirement for ImageMagick is a bonus trait.

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?

The description is a single sentence with a secondary requirement, totaling 17 words. It is front-loaded with the main verb and resource, and every word is informative with zero redundancy.

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

Completeness2/5

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

Given the complexity (16 parameters, no output schema, no annotations), the description is insufficient. It fails to explain what the tool returns or how the output is handled (e.g., saved to disk vs. returned as data). The agent lacks critical context 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?

Schema description coverage is 100%, so the description does not need to add meaning—it is baseline at 3. The description does not repeat parameter details, which is acceptable given the schema's richness.

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?

The description clearly states 'Edit an image' and lists ten specific actions (resize, crop, rotate, etc.), making the tool's purpose explicit. It distinguishes itself from sibling tools like media_info (which only retrieves info) and media_video_edit (which edits video).

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?

The description mentions a prerequisite ('Requires ImageMagick'), which guides when the tool can be used. However, it does not provide explicit when-not-to-use guidance or compare with alternatives, though no direct image editing alternatives exist among siblings.

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

media_infoA

Get metadata about any media file: duration, resolution, codec, bitrate, channels, etc. Requires ffprobe.

ParametersJSON Schema
NameRequiredDescriptionDefault
inputYesAbsolute path to the media file.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.8/5.0
Behavior3/5

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

No annotations provided, so description carries full burden. It mentions ffprobe dependency but does not disclose behavior on invalid files, output format, or side effects. Adequate but not rich.

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?

Single sentence, efficiently conveys purpose and requirement. No unnecessary words, front-loaded.

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?

No output schema, but description lists return values (duration, resolution, etc.). Mentions ffprobe requirement. Slightly lacking error handling info, but sufficient for the tool's simplicity.

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?

Schema coverage is 100% with descriptions for both parameters. The description adds no new meaning beyond what schema provides, so 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?

Description clearly states the tool gets metadata about media files, listing specific attributes (duration, resolution, codec, etc.). The name and description distinguish it from sibling tools like media_audio_edit or media_video_edit.

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

Usage Guidelines3/5

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

Prerequisite (ffprobe) is mentioned, but no explicit guidance on when to use vs. alternatives. Implicitly clear from context, but lacks when-not or alternatives.

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

media_ttsA

Convert text to speech using Edge TTS (free, local — requires the optional node-edge-tts package). Returns an audio file path (OGG/Opus when ffmpeg is available, else MP3).

ParametersJSON Schema
NameRequiredDescriptionDefault
textYesText to speak.
voiceNoPreset name (guy, jenny, aria, davis, tony, ana, brian, emma, ryan, sonia, william, natasha) or a full Edge voice id.
rateNoSpeaking rate, e.g. "+20%" or "-10%".
pitchNoPitch shift, e.g. "+5Hz" or "-10Hz".
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.2/5.0
Behavior4/5

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

Since no annotations are provided, the description fully bears the transparency burden. It discloses key behavioral traits: requires optional package, output is a file path, format depends on ffmpeg availability. This is valuable beyond the schema.

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?

The description is two sentences, front-loading the main action and dependency, then the output format. Every sentence adds necessary information with zero waste.

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?

Given 5 parameters and no output schema, the description covers the core behavior and output format. It could mention potential errors or dependency installation, but it is sufficient for an agent to use the tool correctly.

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?

Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning to the parameters beyond what the schema already provides (e.g., voice presets, rate/pitch format). It does not improve parameter understanding.

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?

The description clearly states 'Convert text to speech' which is a specific verb+resource combination. It distinguishes itself from sibling 'media_tts_voices' by focusing on conversion, and provides context about being free/local.

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?

The description implies usage for text-to-speech tasks and mentions it is free and local, which guides when to use it. However, it does not explicitly list alternatives or when not to use it, missing a clear exclusion.

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

media_tts_voicesB

List the available text-to-speech voice presets.

ParametersJSON Schema
NameRequiredDescriptionDefault
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

B3.3/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden. It states it lists presets, implying a read-only operation, but does not disclose any behavioral traits like whether the list is global or account-specific, or any rate limits. The description adds minimal value beyond the schema parameter for account override.

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?

A single sentence that is entirely functional with no unnecessary words. It is front-loaded and efficient.

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

Completeness3/5

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

For a simple list tool with no output schema, the description covers the basic purpose but lacks details on the return format (e.g., voice IDs or names) and any account context beyond the parameter. It minimally suffices but leaves some ambiguity.

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?

Schema coverage is 100% for the single parameter (_account), with a detailed description in the schema. The tool description does not add any additional meaning regarding parameters, so baseline 3 is appropriate.

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?

The description specifies the verb 'List' and the resource 'available text-to-speech voice presets', making the tool's function clear and distinct from sibling tools like media_tts (synthesis) and media_voice_clone (cloning).

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives, such as media_tts for synthesis or media_voice_clone for cloning. There is no context about prerequisites or when not to use it.

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

media_video_editB

Edit a video. Basic: trim, extract_frame, extract_frames, convert, gif, compress, resize, add_audio, remove_audio, speed. Cinematic: color_grade, transition, text_overlay, picture_in_picture, split_screen, ken_burns, slow_motion, watermark, concatenate, audio_mix, auto_caption. Requires ffmpeg (ImageMagick for text/captions, whisper.cpp for auto_caption).

ParametersJSON Schema
NameRequiredDescriptionDefault
inputNoAbsolute path to the input video (or image for ken_burns). Not required for concatenate.
actionYesThe edit action.
startNoStart time: "00:00:05" or "5".
endNoEnd time: "00:00:15" or "15".
durationNoDuration in seconds.
timestampNoTimestamp for single frame extraction.
intervalNoSeconds between extracted frames. Default: 1.
formatNoOutput format: mp4, webm, mov, avi, mkv.
widthNoTarget width.
heightNoTarget height.
fpsNoFrame rate.
crfNoQuality 0-51, lower is better. Default: 28.
audioPathNoPath to an audio file (add_audio, audio_mix).
speedFactorNoSpeed multiplier: 0.5 = half, 2 = double.
secondInputNoSecond video/image path (transition, picture_in_picture, split_screen).
transitionTypeNoTransition type: fade, wipeleft, slideright, circlecrop, etc. Default: fade.
transitionDurationNoTransition duration in seconds. Default: 1.
textNoText for text_overlay.
fontSizeNoFont size for text_overlay. Default: 72.
fontColorNoText colour. Default: white.
textPositionNoText position: center, top, bottom, top-left, top-right, bottom-left, bottom-right.
textBgNoText background colour with opacity, e.g. "black@0.5".
textStartNoWhen text appears (seconds). Default: 0.
textEndNoWhen text disappears (seconds).
overlayOpacityNoWatermark opacity 0.0-1.0. Default: 0.7.
overlayScaleNoWatermark scale 0.0-1.0. Default: 0.2.
watermarkPositionNoWatermark position: top-left, top-right, bottom-left, bottom-right, center.
watermarkPathNoPath to the watermark/logo image.
pipWidthNoPicture-in-picture overlay width. Default: 320.
pipPositionNoPiP position: top-left, top-right, bottom-left, bottom-right.
splitDirectionNoSplit-screen direction. Default: horizontal.
zoomDirectionNoKen Burns: zoom_in, zoom_out, pan_left, pan_right, pan_up, pan_down.
zoomDurationNoKen Burns output duration in seconds. Default: 5.
zoomFactorNoKen Burns zoom factor 1.0-3.0. Default: 1.5.
filesNoArray of file paths (concatenate).
bgVolumeNoBackground audio volume for audio_mix. Default: 0.3.
fgVolumeNoForeground audio volume for audio_mix. Default: 1.0.
colorPresetNoColour grade preset: warm, cool, vintage, cinematic, dramatic, bleach, noir, vivid, muted, golden_hour.
lutPathNoPath to a .cube LUT file for color_grade.
captionColorNoAuto-caption text colour. Default: white.
captionFontSizeNoAuto-caption font size. Default: auto-scaled.
whisperModelNoAbsolute path to a whisper.cpp model file (.bin) — required for auto_caption.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

B3.1/5.0
Behavior2/5

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

With no annotations, the description carries full burden. It reveals dependencies (ffmpeg, ImageMagick, whisper.cpp) but omits critical behavioral aspects: whether the operation is destructive (modifies original or creates new file), expected output, error handling, or performance impacts.

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 description is concise (3 sentences) and well-structured, front-loading the purpose and then enumerating actions by category. It avoids verbosity but could benefit from bullet points for better scanability.

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

Completeness2/5

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

Given the tool's complexity (43 parameters, no output schema), the description is incomplete. It does not explain return values, error states, or constraints (e.g., file size, format limitations). Important missing context limits the agent's ability to use the tool correctly.

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?

Schema coverage is 100% with all parameters described. The description adds no new semantic information beyond the schema's parameter descriptions; it merely groups actions. Baseline 3 is appropriate.

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?

The description clearly states the tool edits videos and lists many specific actions organized into basic and cinematic categories. The resource is unambiguously video, distinguishing it from sibling tools like media_image_edit and media_audio_edit.

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

Usage Guidelines2/5

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

The description mentions required external dependencies but provides no guidance on when to use this tool versus alternatives, such as media_info for metadata or media_video_understand for analysis. No when-to-use or when-not-to-use context is given.

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

media_video_understandA

Analyse a video before editing it. Extracts frames at intervals and (when a whisper model is supplied) transcribes the audio, returning a structured timeline of what is shown and said. Requires ffmpeg; transcription additionally needs whisper.cpp + a model file.

ParametersJSON Schema
NameRequiredDescriptionDefault
inputYesAbsolute path to the video file.
frameIntervalNoSeconds between extracted frames. Default: 3.
maxFramesNoMaximum number of frames to extract. Default: 30.
whisperModelNoAbsolute path to a whisper.cpp model file (.bin). When supplied, the audio is transcribed and merged into the timeline.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.8/5.0
Behavior3/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It notes dependencies and optional transcription but does not mention whether the tool is read-only, side effects (e.g., temporary files), or error handling if dependencies are missing. The description adequately indicates core behavior but lacks depth.

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?

The description is two sentences: the first explains purpose and action, the second lists requirements. It is front-loaded, concise, and contains no unnecessary words. Every sentence serves a purpose.

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?

Given the complexity of video analysis and optional transcription, the description covers the main points (what it does, prerequisites). However, it lacks details about the return format ('structured timeline' is vague) and does not explicitly state that the tool is read-only. With no output schema, a bit more clarity on output would improve completeness.

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?

Schema description coverage is 100%, so the schema already documents each parameter fully. The tool description adds context about frame extraction and transcription but does not add meaning beyond what the schema provides for individual parameters. Baseline 3 is appropriate.

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?

The description clearly states the tool's purpose: analyze a video before editing by extracting frames and optionally transcribing audio to produce a structured timeline. It distinguishes itself from sibling tools like media_video_edit or media_info by specifying its role as a pre-editing analysis step.

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

Usage Guidelines3/5

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

The description mentions prerequisites (ffmpeg, whisper.cpp) but does not explicitly state when to use this tool versus alternatives, such as media_info for metadata or media_video_edit for actual edits. The implied usage is for pre-editing analysis, but no when-not-to-use guidance is given.

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

media_voice_cloneA

Synthesise speech in a reference voice using F5-TTS. Requires a Python interpreter with the f5-tts and soundfile packages. You MUST supply a reference audio sample and its transcript — there is no built-in voice.

ParametersJSON Schema
NameRequiredDescriptionDefault
textYesText to speak in the cloned voice. Keep it short (~15 words) for best quality.
refAudioYesAbsolute path to the reference audio sample (required).
refTextYesTranscript of the reference audio (required).
pythonBinNoOptional absolute path to a Python interpreter with F5-TTS installed.
deviceNoCompute device for F5-TTS: cpu, cuda, mps. Default: cpu.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.8/5.0
Behavior3/5

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

No annotations provided, so description bears full burden. It discloses package dependencies and the need for reference inputs, but does not explain output behavior, error handling, or performance characteristics. More detail on return value or side effects would raise the score.

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?

Two sentences, no filler. Purpose and key requirement conveyed in first sentence, constraints in second. Front-loaded and efficient.

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

Completeness2/5

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

No output schema, so description must explain what happens after synthesis. It does not mention output file path, format, or how to retrieve the audio. Lacks completeness for a tool with potential side effects (file creation).

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?

Schema coverage is 100%, so baseline is 3. Description reinforces importance of refAudio and refText but adds minimal semantic value beyond the schema. It does not explain subtle constraints like text length or audio format.

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?

Description clearly states the tool synthesizes speech in a reference voice using F5-TTS, distinguishing it from other TTS tools by requiring a reference audio and transcript. It identifies the specific task and resource.

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?

Description explicitly states prerequisites (Python interpreter with f5-tts and soundfile packages) and mandatory inputs (reference audio and transcript). It implicitly differentiates from built-in TTS but does not name sibling tools like media_tts.

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

memoryA

Your persistent, long-term memory — knowledge that survives across every conversation, like a human employee learning on the job. Use set to remember something durable (a preference, a fact, a correction, a learned skill); search to recall by topic; list to browse; get to read one entry; delete to forget. Memory is private to you and persists forever unless it decays from disuse or you delete it. Store things you would want to still know weeks from now — not transient task state.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYesset | get | search | list | delete
contentNoset: the thing to remember (plain text).
titleNoset: a short title/label for the memory (optional — derived from content if omitted).
categoryNoset: memory category (default: context).
importanceNoset: how important this is (default: normal). critical entries never decay.
tagsNoset: optional tags.
queryNosearch: the topic to recall.
idNoget | delete: the memory entry id.
limitNosearch | list: max entries to return (default 50).
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.1/5.0
Behavior4/5

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

With no annotations, the description must fully disclose behavior. It explains privacy (private to user), persistence (forever unless decay or deletion), and decay mechanism (disuse, critical entries exempt). Missing details like size limits or query semantics marginally reduce clarity.

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 description starts with the core purpose, then lists actions, and concludes with persistence caveats. It is well-structured and not overly verbose, though the action list could be slightly more compact.

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?

Given tool complexity (10 parameters, 5 actions, no output schema), the description covers essential behavioural aspects and usage intent. It lacks details on search/list behaviour and output format, but remains sufficiently complete for agent selection.

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?

All 10 parameters have 100% schema coverage. The description adds brief action-specific context for parameters (e.g., 'set: the thing to remember') but does not significantly expand beyond the schema descriptions, meeting the baseline expectation.

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?

The description clearly identifies the tool as a persistent memory system, lists all supported actions (set, get, search, list, delete) with brief explanations, and distinguishes it from transient task state. This makes the purpose unmistakable even among many sibling tools.

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?

The description provides context for when to use each sub-action (e.g., 'set to remember something durable') and advises storing things for long-term recall, not transient state. However, it does not explicitly compare memory to sibling tools like memory_context or memory_stats, leaving some ambiguity.

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

memory_contextA

Get a ranked markdown digest of your most relevant persistent memory — what you would want loaded into your working context right now. Optionally pass a query to bias the digest toward a topic. This is the same memory block a voice/phone session injects so you act with full continuity.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryNoOptional topic to focus the digest on.
maxTokensNoApproximate size budget (default 1500).
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.2/5.0
Behavior4/5

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

No annotations are provided, so the description carries full burden. It clearly describes the tool as retrieving a digest (read operation) and mentions the optional query and default size budget, but could be more explicit about side effects or read-only nature.

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?

The description is extremely concise (two sentences) and front-loaded with the verb and resource. Every sentence adds value without redundancy.

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?

Given no output schema, the description adequately explains the return type ('ranked markdown digest') and the purpose for continuity. However, it lacks examples or details on the ranking mechanism, but is generally sufficient.

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?

Schema coverage is 100% with parameter descriptions, so baseline is 3. The description adds slight value for 'query' by explaining it biases the digest, but does not expand on 'maxTokens' or '_account' beyond 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?

The description clearly states the tool returns a 'ranked markdown digest of your most relevant persistent memory' with a specific verb ('Get') and resource. It distinguishes itself from sibling memory tools by mentioning it's the same block used for voice/phone sessions and provides continuity.

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?

The description implies when to use the tool (for loading relevant context) and mentions optional query biasing, but does not explicitly state when to avoid it or compare with alternatives like 'memory' or 'memory_reflect'.

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

memory_reflectA

Record a self-reflection into your persistent memory — an insight or lesson you want to carry forward (stored as a high-confidence reflection entry). Use this at the end of a task or conversation to capture what you learned.

ParametersJSON Schema
NameRequiredDescriptionDefault
contentYesThe reflection / insight to remember.
titleNoOptional short title.
importanceNoDefault: normal.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.9/5.0
Behavior3/5

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

No annotations are provided, so the description must fully disclose behavior. It states the entry is 'high-confidence' and stored in persistent memory, but does not detail side effects, overwrite behavior, or authentication requirements beyond what the schema implies. Some transparency is present but insufficient for a state-modifying tool.

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?

The description is two sentences, front-loaded with purpose and usage. Each sentence serves a clear role with no wasted words.

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

Completeness3/5

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

Given 4 parameters (1 required) and no output schema, the description covers the core purpose and usage but lacks return value information and authentication context (though _account parameter is in schema). It is adequate but not fully complete.

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?

Schema coverage is 100%, so baseline is 3. The description adds minimal value beyond schema: it mentions 'insight or lesson' but does not elaborate on parameter meanings or usage details.

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?

The description clearly states the tool's purpose: 'Record a self-reflection into your persistent memory... (stored as a high-confidence `reflection` entry)'. It distinguishes from sibling memory tools by specifying it stores a 'reflection' entry, implying it is a specific type of memory storage.

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?

The description explicitly says 'Use this at the end of a task or conversation to capture what you learned.' This provides clear usage context, though it does not outline when not to use it or suggest alternatives.

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

memory_statsA

Get aggregate statistics about your persistent memory — total entries, breakdown by category / importance / source, and average confidence.

ParametersJSON Schema
NameRequiredDescriptionDefault
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.8/5.0
Behavior4/5

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

No annotations are provided, so the description must fully disclose behavior. It indicates a read-only operation returning statistics, implying no side effects. While it could mention authentication requirements or performance characteristics, the core behavioral trait (aggregate read) is clear.

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?

The description is a single, well-structured sentence that front-loads the purpose and resource. There is no wasted text.

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?

Given the tool is a simple read operation with one optional parameter and no output schema, the description covers the necessary context: what it does and what it returns. It could elaborate on the meaning of 'category' or 'importance' but is adequate for an aggregate statistics tool.

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?

Schema description coverage is 100% (one optional parameter _account). The description does not mention or add meaning to the parameter beyond the schema. Baseline 3 is appropriate as the schema already documents the parameter.

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?

The description clearly states the verb ('Get aggregate statistics') and the resource ('persistent memory'), listing specific breakdowns (category, importance, source, average confidence). This differentiates it from sibling memory tools like memory, memory_context, and memory_reflect.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives or when not to use it. With several memory-related siblings, explicit usage context would be helpful, but it is absent.

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

message_agentA

Async fire-and-forget: deliver a message to another AI agent's inbox. They will process it on their own schedule (immediately if a dispatcher is attached, later otherwise) and may reply by email. Use this for non-blocking handoffs. Prefer call_agent when you need a structured reply back. Both flows let the target agent do the work AS THEMSELVES — never roleplay them inside your own host.

ParametersJSON Schema
NameRequiredDescriptionDefault
agentYesName of the recipient agent (e.g. "researcher", "writer")
subjectYesMessage subject — describe the purpose clearly
textYesMessage body
priorityNoPriority level (default: normal)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.7/5.0
Behavior5/5

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

No annotations are provided, so the description carries full burden. It discloses key behaviors: the target agent processes on its own schedule, may reply by email, and warns against roleplaying. This is thorough for an async messaging tool.

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?

The description is extremely concise: two sentences plus a short warning, no fluff. Front-loaded with the key concept 'Async fire-and-forget'. Every sentence earns its place.

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?

Given 5 parameters, no output schema, and no annotations, the description covers the tool's purpose, usage, async behavior, and important pitfalls (not roleplaying). It is complete for an AI agent to select and invoke correctly.

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?

Schema description coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond the schema; the only additional context is a note on `subject` ('describe the purpose clearly') and `_account` identity override. No deep parameter elaboration.

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?

The description clearly states the tool's purpose: 'Async fire-and-forget: deliver a message to another AI agent's inbox.' It uses a specific verb (deliver) and resource (message to inbox), and distinguishes it from the sibling `call_agent` by noting the difference in reply expectation.

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 guidance: 'Use this for non-blocking handoffs. Prefer `call_agent` when you need a structured reply back.' This provides both when to use and when not to use, with a clear alternative.

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

move_emailA

Move an email to another folder (e.g., Trash, Archive)

ParametersJSON Schema
NameRequiredDescriptionDefault
uidYesUID of the email to move
toYesDestination folder (e.g., Trash, Archive)
fromNoSource folder (default: INBOX)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.6/5.0
Behavior2/5

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

No annotations are provided, so the description must carry full burden. It mentions the action (move) but does not disclose behavioral traits such as whether the operation is reversible, whether it requires specific permissions, what happens if the destination doesn't exist, or whether it returns a confirmation.

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?

The description is a single sentence that front-loads the action and resource, with no extraneous information. Every word earns its place.

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?

Given the tool's low complexity (4 params, simple strings, no output schema), the description provides adequate context: purpose and example destinations. However, it could mention that moving to Trash effectively deletes the email (irreversible behavior) or that moving is typically reversible for Archive.

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?

Schema coverage is 100% with descriptions for all 4 parameters. The description adds no extra meaning beyond the schema; it only repeats examples (Trash, Archive) already present in parameter descriptions. Baseline 3 is appropriate.

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?

The description clearly states the action (move), the resource (email), and provides examples of destination folders (Trash, Archive). It distinguishes from siblings like batch_move (which handles multiple) and delete_email (which removes permanently).

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

Usage Guidelines3/5

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

The description implies usage (when you want to move an email to a folder like Trash or Archive) but does not explicitly state when to use this tool versus alternatives like batch_move for bulk operations or delete_email for permanent deletion. No when-not-to-use guidance is provided.

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

phone_capabilitiesB

Show the configured phone provider, caller number, supported regions, and whether realtime media is available.

ParametersJSON Schema
NameRequiredDescriptionDefault
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

B3.3/5.0
Behavior2/5

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

No annotations are provided, so the description carries full burden. It only lists what information is shown but does not disclose side effects (likely read-only), authentication requirements (the _account parameter implies identity override), error cases, or output format. For a query tool, it lacks behavioral details like whether it triggers any side effects.

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?

The description is a single sentence that lists four specific pieces of information. It is concise, front-loaded, and contains no unnecessary words.

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

Completeness3/5

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

The tool has no output schema and no annotations. The description lists what is shown but does not explain the return format, structure, or how to interpret results. For a simple read tool, it provides the core purpose but omits context about the response schema and potential limitations.

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?

Schema coverage is 100% (only one optional parameter '_account'). The description does not mention any parameters, so it adds no extra meaning beyond the schema. Baseline is 3 due to full schema coverage, and the description provides no additional context for the parameter.

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?

The description clearly states the tool shows specific phone configuration details: configured phone provider, caller number, supported regions, and realtime media availability. It uses a specific verb ('Show') and identifies the resource ('phone capabilities'), distinguishing it from sibling tools like phone_transport_setup (setup) and media_capabilities (different media).

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

Usage Guidelines2/5

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

There is no guidance on when to use this tool versus alternatives. Siblings like media_capabilities could be confused, but no differentiation is provided. No explicit context for when to use or when not to use.

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

phone_transport_setupA

Configure the phone call-control transport for this agent. This stores provider credentials and webhook settings; it does not start a call. Pick ONE provider — 46elks or twilio — and supply that provider's credentials. For 46elks pass username + password; for twilio pass accountSid + authToken (or the generic username + password — for twilio username is the account SID and password is the auth token).

ParametersJSON Schema
NameRequiredDescriptionDefault
providerNoPhone provider: "46elks" (default) or "twilio". Both support call-control missions and realtime voice.
phoneNumberYesOwned caller phone number in E.164 format, e.g. +43123456789
usernameNo46elks API username. For twilio this is the account SID — prefer the accountSid param for clarity.
passwordNo46elks API password. For twilio this is the auth token — prefer the authToken param for clarity.
accountSidNoTwilio only: the account SID (alias for username when provider is "twilio").
authTokenNoTwilio only: the account auth token (alias for password when provider is "twilio").
webhookBaseUrlYesPublic HTTPS base URL for AgenticMail phone webhooks
webhookSecretYesShared secret included on provider webhook URLs (at least 24 characters)
apiUrlNoOptional provider API base URL override (46elks or Twilio REST root)
capabilitiesNoTransport capabilities, e.g. ["call_control"] or ["call_control","realtime_media"]
supportedRegionsNoSupported region scopes: AT, DE, EU, WORLD
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.2/5.0
Behavior3/5

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

No annotations are provided, so the description must carry the burden. It explains stored data (credentials and webhook settings) and provider credential aliasing, but does not disclose idempotency, side effects of repeated calls, or security implications.

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?

Three concise sentences with no waste: first states purpose, second gives provider selection instruction, third explains credential details.

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?

Given 12 parameters and no output schema, the description covers the core purpose and credential usage adequately, though it omits explanation of webhook parameters and optional fields. Still sufficient for a setup tool.

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%, but the description adds meaningful context beyond the schema by explaining how username/password map to Twilio's accountSid/authToken and the generic fallback, aiding agent selection.

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?

The description clearly states the tool configures the phone call-control transport and explicitly says it does not start a call, differentiating it from call-related sibling tools like call_phone or call_cancel.

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?

Provides clear guidance on selecting one provider and which credentials to use, but does not mention when not to use this tool or specify alternatives among sibling tools.

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

purchase_domainA

Search for available domains via Cloudflare Registrar (requires master API key). NOTE: Cloudflare API only supports READ access — domains must be purchased manually at https://dash.cloudflare.com or from another registrar (then point nameservers to Cloudflare).

ParametersJSON Schema
NameRequiredDescriptionDefault
keywordsYesKeywords to search for (e.g., ["mybot", "aimail"])
tldNoPreferred TLD (default: checks .com, .net, .io, .dev)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.6/5.0
Behavior5/5

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

No annotations provided, so description carries full burden. It discloses that the tool is read-only, requires a master API key, and does not complete purchases. This prevents misuse and sets correct expectations.

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?

Two sentences with no wasted words. The main action is front-loaded, and the critical note follows immediately. Very efficient.

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 search tool with 3 parameters fully described in schema, no output schema, and no annotations, the description covers purpose, usage, and behavioral constraints well. It could mention the expected output format (e.g., list of available domains) for completeness, but it is still solid.

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?

Schema coverage is 100%, so baseline is 3. The description adds no additional parameter-specific context beyond what the schema provides. It does not explain the array format of keywords or the optional nature of tld and _account.

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?

The description clearly states the tool searches for domains via Cloudflare Registrar, not purchases them. It specifies the resource (domains) and the action (search), and distinguishes from the misleading name. Sibling tools are unrelated, so no confusion.

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 states when to use (search for available domains) and when not to use (do not use for actual purchase). Provides alternative: manual purchase at Cloudflare or another registrar. Also notes the requirement of a master API key.

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

read_emailA

Read the full content of a specific email by its UID

ParametersJSON Schema
NameRequiredDescriptionDefault
uidYesThe UID of the email to read
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.5/5.0
Behavior3/5

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

No annotations provided, so description must cover behavior. It states 'full content' but does not specify whether this includes attachments, headers, or whether it marks the email as read. For a read operation, it is adequate but not thorough.

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?

Single sentence with 12 words, front-loaded with the action and resource. Every word earns its place.

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

Completeness3/5

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

Tool is simple with 1 required param and no output schema. Description lacks details about return format, error handling, or side effects. Adequate but not fully complete for an agent relying solely on description.

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?

Schema coverage is 100% so baseline is 3. The description adds no extra meaning beyond the schema's parameter descriptions; it merely confirms the UID is used to identify the email.

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?

Description clearly states 'Read the full content of a specific email by its UID', using specific verb and resource. It distinguishes from sibling tools like batch_read (multiple emails) and list_inbox (listing emails).

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

Usage Guidelines2/5

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

No guidance on when to use this tool vs alternatives like batch_read or list_inbox. The description implies you need a UID but does not explain what to do if you don't have one or how to obtain it.

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

reply_emailA

Reply to an email. Fetches the original message, auto-fills To, Subject (Re:), In-Reply-To, and References, then sends with quoted body. For multi-agent thread coordination, pass replyAll: true — the original sender lands on To:, every other thread participant lands on Cc:. Wake routing is body-aware: if your reply addresses a specific CC'd agent ("Marlow —", "@kepler", "handing off to rivet", etc.), the dispatcher wakes them automatically. If your body has no such addressing, the original sender (on To:) wakes by default. Pass wake to override explicitly (e.g. wake: ["marlow"] to force-target one agent, or wake: [] to deliver silently). Outbound guard applies — HIGH severity content is held for review.

ParametersJSON Schema
NameRequiredDescriptionDefault
uidYesUID of the email to reply to
textYesYour reply text
htmlNoHTML reply (optional)
replyAllNoReply to all recipients (default: false)
wakeNoOptional. Names of the agents who should get a host turn from the dispatcher when this reply lands. CC'd agents NOT in this list still receive the email but stay asleep — saves significant tokens on large threads. Pass `[]` to deliver silently. Omit to wake everyone CC'd.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.6/5.0
Behavior5/5

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

No annotations provided, so description carries full burden. Discloses that it fetches original message, auto-fills fields, sends with quoted body, explains body-aware wake routing and override, and mentions outbound guard for HIGH severity content. Covers key behavioral traits comprehensively.

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 description is relatively verbose but front-loaded with the core purpose. Each sentence adds new information (auto-fill, replyAll, wake routing, outbound guard). Could be slightly more concise, but the density of useful detail warrants a 4.

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?

Given 6 parameters (2 required), no output schema, and no annotations, the description covers purpose, usage, behavior, and parameter semantics sufficiently. It explains the tool's complete behavior for a 1-1 conversation and multi-agent coordination, leaving no major gaps.

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% (all params described). The description adds significant value beyond schema by explaining the wake parameter's default behavior (wake everyone CC'd) and the body-aware routing nuance. Also clarifies the replyAll parameter's impact on To/Cc fields.

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?

The description clearly states 'Reply to an email' and details the auto-fill behavior (To, Subject, In-Reply-To, References, quoted body), which distinguishes it from sibling tools like send_email or forward_email. The verb 'reply' and resource 'email' are specific.

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?

Provides clear guidance on when to use replyAll and wake routing, including explicit instructions for multi-agent coordination. Does not explicitly mention when not to use the tool or compare with alternatives like forward_email, but the context of sibling tools is available and the description implies usage for replies.

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

request_toolsA

Discover AgenticMail tools that are NOT already in your loaded tool list. Returns a text catalogue grouped by set (mail_extras, sms, agent_coord, …) with each tool name and its schema summary. After calling this, use invoke to call any tool by name. Optional filters: query (substring match on tool name/description) or sets (return only the named sets).

ParametersJSON Schema
NameRequiredDescriptionDefault
queryNoCase-insensitive substring filter on tool name or description (e.g. "signature", "voice").
setsNoRestrict the output to these set names (e.g. ["sms", "mail_extras"]). See SET_DESCRIPTIONS for valid names.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.1/5.0
Behavior3/5

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

No annotations provided, so description carries full burden. It does not mention side effects, error conditions, or rate limits. It implies read-only behavior but doesn't confirm. Adequate but could be more explicit.

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?

Two sentences with no wasted words. First sentence states main purpose, second gives usage and filter info. Perfectly concise and front-loaded.

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

Completeness3/5

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

No output schema, but description doesn't describe the return format or detail the catalogue structure. Mentions sets and external SET_DESCRIPTIONS, leaving some gaps. Adequate but incomplete.

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%, and description adds context: explains query as case-insensitive substring, sets as filtering by set names, and _account for identity override. Adds value beyond 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?

Description clearly states it discovers tools not already loaded, returning a catalogue grouped by set. Verb 'discover' and resource 'tools' are specific, and it distinguishes from operational siblings like send_email or batch_delete.

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?

Provides context on when to use (after loading initial tools) and mentions using invoke afterward. Optional filters are explained. Lacks explicit when-not-to-use, but guidance is sufficient for a discovery tool.

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

resume_agentA

Reverse a previous stop_agent call. Clears the stopped flag so the dispatcher resumes waking this agent on incoming mail and task events. The agent's inbox is exactly as it was during the pause — any mail that arrived while stopped is still there and will be picked up on the next natural wake. Requires master API key.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesName of the agent to resume
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

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 discloses behavioral details: it reverses a stop, the inbox remains unchanged, and mail received during pause is preserved. It also mentions the authentication requirement.

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?

The description is concise, with three short sentences that front-load the action and provide necessary context without redundancy.

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?

Given no output schema and simple parameters, the description explains the effect on the agent's state and inbox. It does not cover potential errors or return values but is sufficient for a straightforward operation.

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?

Schema coverage is 100%, and the description adds no significant meaning beyond the schema. It restates the purpose of the 'name' parameter and does not enhance understanding of '_account'.

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?

The description clearly states it reverses a previous 'stop_agent' call, clears the 'stopped' flag, and resumes waking on events. It specifies the verb and resource, and distinguishes itself from the sibling tool 'stop_agent'.

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?

The description indicates the tool is used after 'stop_agent' and requires a master API key. It provides context for when to use it, but does not explicitly state when not to use or mention alternatives beyond 'stop_agent'.

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

save_thread_memoryA

Persist a one-paragraph memory of where THIS agent stands on the given thread. Called at the end of every wake — Claude Code reads it back into the next wake's prompt so the agent doesn't re-derive context from scratch by re-reading 10 prior messages. Pass threadId from get_thread_id. Fields are a snapshot: summary (where the thread stands), commitments (what you committed to), openQuestions (what you are blocked on), lastAction (what you just did), lastUid (newest UID you have digested). The file overwrites; you do not need to merge with the previous version — the dispatcher reads only the most recent write.

ParametersJSON Schema
NameRequiredDescriptionDefault
threadIdYesStable thread id from get_thread_id. Required.
summaryNoOne-paragraph narrative of where the thread stands.
commitmentsNoThings you have committed to doing on this thread.
openQuestionsNoThings you are waiting on / open questions.
lastActionNoThe last action you took on the thread (e.g. "replied UID 41 asking for raw counts").
lastUidNoNewest message UID you have digested into this memory.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.5/5.0
Behavior4/5

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

No annotations provided, so description carries full burden. Discloses that the file overwrites and does not need merging, and that the dispatcher reads only the most recent write. Mentions the overwrite behavior, which is key for a write operation. Could add more on idempotency or error states, but sufficient.

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?

Description is 3-4 sentences, front-loaded with purpose and usage context. Every sentence adds unique value; no wasted words. Highly efficient.

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?

Given 7 params (only 1 required) and no output schema, description covers the tool's role in the agent's lifecycle, when to call, field meanings, and overwrite behavior. No gaps for an agent to use it 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%, baseline 3. Description adds value by explaining each field's role in the snapshot ('summary (where the thread stands), commitments (what you committed to)...') and instructs to pass threadId from get_thread_id. This provides contextual meaning beyond the schema descriptions.

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?

Clearly states the tool persists a one-paragraph memory of the agent's state on a specific thread. Uses specific verb 'persist' and resource 'memory of where THIS agent stands on the given thread'. Distinguishes from sibling memory tools by being per-thread and called at end of every wake.

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?

Explicitly states when to use: 'Called at the end of every wake'. Also explains that it overwrites, so no merging needed. Doesn't explicitly contrast with alternatives like 'memory' or 'memory_context', but the context is clear enough for the agent to decide.

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

search_emailsA

Search emails by criteria (from, to, subject, text, date range). By default searches the local inbox only. Set searchRelay=true to also search the connected Gmail/Outlook account — results include relay UIDs that can be imported with import_relay_email.

ParametersJSON Schema
NameRequiredDescriptionDefault
fromNoFilter by sender address
toNoFilter by recipient address
subjectNoFilter by subject keyword
textNoSearch body text
sinceNoMessages since date (ISO 8601)
beforeNoMessages before date (ISO 8601)
seenNoFilter by read/unread status
searchRelayNoAlso search the connected Gmail/Outlook account (default: false). Use this to find past emails from the user's main inbox.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.1/5.0
Behavior3/5

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

No annotations are provided, so the description carries full burden. It discloses the default scope and relay option, but does not explicitly state that the operation is read-only (non-destructive). The behavior is implied as search, but explicit assurances are missing.

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?

The description is two sentences (30 words), front-loading the core purpose. Every sentence serves a distinct role: listing criteria and explaining default vs relay behavior. No redundant or extraneous information.

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

Completeness3/5

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

With 9 optional parameters and no output schema, the description omits details like result format (fields returned), pagination, and any limitations. While it provides sufficient usage guidance, an agent might need more context on the response structure to process results 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%, and the description adds value by explaining the searchRelay parameter's default and purpose, linking to import_relay_email. It also clarifies _account's role for identity override. This goes beyond the schema's individual descriptions.

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?

The description clearly states 'Search emails by criteria' and lists specific fields (from, to, subject, text, date range), making the tool's purpose unmistakable. It distinguishes itself from siblings like list_inbox by focusing on search with filters.

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?

The description explains default behavior (local inbox only) and when to use searchRelay for connected accounts, with a note about importing results via import_relay_email. It provides clear context for usage but does not explicitly contrast with alternative search or list tools.

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

send_emailA

Send an email from the agent's mailbox. The PRIMARY primitive for multi-agent coordination. Use to and cc as the email standard intends — to is the actor(s) the message is addressed to (one or two recipients in most cases); cc is everyone else on the thread for awareness. Lumping every participant on to is wrong and defeats the wake gating. WAKE SEMANTICS (0.9.0+): by default only local @localhost recipients on to: get a host wake; CC'd local agents receive the mail but don't wake — they see it on their next natural wake. To override: pass wake: ["alice","bob"] for specific agents regardless of To/CC, or wake: "all" for the pre-0.9.0 "wake every recipient" behaviour, or wake: [] to deliver silently. External emails are scanned for sensitive content; HIGH severity detections are BLOCKED for owner approval.

ParametersJSON Schema
NameRequiredDescriptionDefault
toYesPrimary actor — the agent(s) you want to act on this message. Usually one address; rarely two. **Everyone else on the thread goes on `cc`, NOT here.** Lumping all participants on `to` defeats the wake gating: every local @localhost recipient on `to` gets a host turn, so a 5-agent thread = 5 host turns per round. Comma-separated supported but use sparingly.
subjectYesEmail subject line
textNoPlain text body
htmlNoHTML body (optional)
ccNoCC recipients — the team. Comma-separated, e.g. "vesper@localhost, orion@localhost". CC'd local recipients receive the mail but DO NOT wake by default (0.9.0+). Put the actor on `to`; CC the rest for awareness.
wakeNoOptional wake-control. Accepts: (1) an array of agent names — `["alice","bob"]` — to wake exactly those agents (overrides default To-only behaviour); (2) the string `"all"` to wake every local recipient on To and CC (pre-0.9.0 behaviour); (3) an empty array `[]` to deliver silently with no wakes; (4) omit entirely to use the default — wake local recipients on `To:` only. CC'd recipients NOT in the wake list still receive the mail in their inbox and will see it when they next wake naturally.
inReplyToNoMessage-ID to reply to (optional)
referencesNoMessage-IDs for threading (optional)
attachmentsNoFile attachments
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.7/5.0
Behavior3/5

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

No annotations are provided, so the description carries the full burden. It discloses wake semantics, CC wake default, external email scanning, and HIGH severity blocking. However, it omits common behavioral aspects such as rate limits, authorization requirements, error handling, or confirmation of successful sending.

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 description is front-loaded with the primary purpose and then dives into critical wake semantics. Each paragraph adds value, but the overall length is justified by the complexity. Minor conciseness improvement possible by merging some details, but structure is effective.

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

Completeness3/5

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

Given 10 parameters, no output schema, and no annotations, the description covers usage guidelines and behavioral traits well. However, it lacks information about return values (e.g., success/error indicators) and error handling. Also, authorization model is mentioned only in the schema for `_account`, not in the description. These gaps reduce completeness.

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?

Although the input schema already describes all 10 parameters (100% coverage), the description adds significant value beyond the schema by explaining the coordination semantics of `to`, `cc`, and especially the `wake` parameter with examples. This enriches the agent's understanding of how to use these parameters correctly in context.

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?

The description clearly states 'Send an email from the agent's mailbox. The PRIMARY primitive for multi-agent coordination.' This provides a specific verb-resource pair and positions the tool among siblings as the primary coordination primitive. However, it does not explicitly differentiate from closely related siblings like broadcast_email or reply_email, so it loses some points.

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?

The description provides detailed guidelines on proper usage of `to` vs `cc`, including wake semantics and override options. It explicitly advises against lumping all participants on `to` to avoid excessive wake turns. However, it does not specify when not to use this tool versus alternatives like broadcast_email or message_agent, which would enhance decision-making.

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

send_test_emailB

Send a test email through the gateway to verify configuration (requires master API key)

ParametersJSON Schema
NameRequiredDescriptionDefault
toYesEmail address to send the test to
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

B3.3/5.0
Behavior2/5

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

With no annotations, the description only mentions the authentication requirement (master API key) but fails to disclose whether the email is actually sent, side effects, or what happens on failure.

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 description is a single concise sentence, front-loaded with the action and purpose, but could include more detail without being verbose.

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

Completeness2/5

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

Given no annotations and no output schema, the description should provide more context about success/failure behavior, but it only covers purpose and a prerequisite.

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?

Schema coverage is 100%, so baseline is 3. The description adds no parameter-specific information beyond what the schema already provides.

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?

The description clearly states the verb 'Send', the resource 'test email through the gateway', and the purpose 'to verify configuration', which distinguishes it from sibling like 'send_email'.

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

Usage Guidelines3/5

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

The description implies it is for testing, but does not explicitly specify when to use this tool versus alternatives like 'send_email', or mention any when-not scenarios.

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

setup_email_domainA

Set up a custom domain for real internet email via Cloudflare (requires master API key). ADVANCED: Requires Cloudflare account, API token, and a domain. Emails send from agent@yourdomain.com with full DKIM/SPF/DMARC. Optionally configures Gmail SMTP as outbound relay (recommended for residential IPs). After setup with gmailRelay, use setup_gmail_alias for each agent.

ParametersJSON Schema
NameRequiredDescriptionDefault
cloudflareTokenYesCloudflare API token (Zone>Zone>Read, Zone>DNS>Edit, Zone>Email Routing Rules>Edit, Account>Cloudflare Tunnel>Edit, Account>Workers Scripts>Edit; optional: Account>Registrar: Domains>Edit for domain purchase)
cloudflareAccountIdYesCloudflare account ID
domainNoDomain to use (if already owned)
purchaseNoPurchase a new domain (if domain not provided)
gmailRelayNoGmail SMTP relay for outbound delivery (recommended for residential IPs without PTR records)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

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 burden and delivers: it explains that master API key is required, domain setup includes DKIM/SPF/DMARC, and optionally configures Gmail SMTP relay. It mentions what happens after setup. Some nuance about error handling or side effects could be added, but overall it's solid.

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?

The description is two sentences with no wasted words. It front-loads the purpose and provides essential details in a compact format. Every sentence adds value.

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?

Given the complexity (6 parameters, nested objects, no output schema), the description adequately covers prerequisites, optional relay, and follow-up steps. It does not describe return values, but for a setup tool this is acceptable. Could mention what happens on success or failure.

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?

Schema coverage is 100%, so baseline is 3. The description adds overall context (e.g., email from agent@yourdomain.com, DKIM/SPF/DMARC) but does not significantly enhance understanding of individual parameters beyond what the schema already provides.

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?

The description clearly states the tool's purpose: 'Set up a custom domain for real internet email via Cloudflare.' It specifies the resource (custom domain) and verb (set up), distinguishing it from siblings like 'purchase_domain' and 'setup_gmail_alias'.

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?

The description gives prerequisites (Cloudflare account, API token, domain) and provides sequencing guidance ('After setup with gmailRelay, use setup_gmail_alias'). It does not explicitly state when not to use this tool, but the context is clear enough to differentiate from alternatives.

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

setup_email_relayA

Configure Gmail/Outlook relay for sending real internet email (requires master API key). BEGINNER-FRIENDLY: Just needs a Gmail/Outlook email + app password. Agents send as user+agentname@gmail.com. Automatically creates a default agent (secretary) unless skipped. Best for: quick setup, personal use, no domain needed.

ParametersJSON Schema
NameRequiredDescriptionDefault
providerYesEmail provider (gmail, outlook, or custom)
emailYesYour real email address (e.g., user@gmail.com)
passwordYesApp password (not your regular password)
smtpHostNoSMTP host (auto-filled for gmail/outlook)
smtpPortNoSMTP port (auto-filled for gmail/outlook)
imapHostNoIMAP host (auto-filled for gmail/outlook)
imapPortNoIMAP port (auto-filled for gmail/outlook)
agentNameNoName for the default agent (default: secretary). This becomes the email sub-address, e.g., user+secretary@gmail.com
agentRoleNoRole for the default agent (default: secretary)
skipDefaultAgentNoSkip creating the default agent (default: false)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.1/5.0
Behavior4/5

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

Covers prerequisites, auto-creation of default agent, and email addressing scheme. No annotations provided, so description carries full burden. Lacks details on failure modes or effects on existing relay config, but sufficient for safe use.

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?

Efficient paragraph with front-loaded main action. Could be slightly tighter, but no superfluous sentences.

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?

Covers setup steps, prerequisites, and auto-creation. However, no output schema and missing return value description; for a config tool, still fairly complete.

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?

Schema coverage is 100% with good descriptions. Description adds context like 'auto-filled for gmail/outlook' and explains agentName as sub-address, but does not significantly enhance understanding beyond 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?

Description explicitly states it configures email relay for Gmail/Outlook, and distinguishes from siblings like setup_email_domain by noting 'no domain needed' and 'personal use'. Verb 'configure' plus resource 'email relay' is specific.

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?

Provides clear context: requires master API key, beginner-friendly, best for quick personal use. Does not explicitly exclude cases like custom domain or mention alternatives, but usage is implied.

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

setup_gmail_aliasA

Get step-by-step instructions (with exact field values) to add an agent email as a Gmail "Send mail as" alias. Returns the Gmail settings URL and all field values. Required after domain mode setup with gmailRelay to show correct From address. The agent can automate this via browser tools or present instructions to the user.

ParametersJSON Schema
NameRequiredDescriptionDefault
agentEmailYesAgent email to add as alias (e.g., secretary@yourdomain.com)
agentDisplayNameNoDisplay name for the alias (defaults to agent name)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.5/5.0
Behavior5/5

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

With no annotations, the description fully bears the burden. It explicitly states the tool returns instructions and URL, not performing the action directly. It also explains the purpose and how the output can be used, providing complete behavioral transparency.

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?

The description is three sentences, each serving a distinct purpose: stating the main function, specifying prerequisite, and suggesting usage modes. No unnecessary words.

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?

The description covers what the tool does, what it returns, when it is needed, and how the output can be used. Given the absence of an output schema, it provides sufficient context for correct use.

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?

Schema coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond the schema; it confirms that the instructions include exact field values, but the schema already describes the parameters adequately.

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?

The description clearly states the tool provides step-by-step instructions to add an agent email as a Gmail alias. It distinguishes from sibling tools like setup_email_domain and setup_email_relay by noting it is required after domain mode setup.

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?

The description specifies the tool is used after domain mode setup with gmailRelay, and mentions that the output can be used for automation via browser tools or presented to the user. It does not explicitly list when not to use it, but the context is clear.

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

setup_guideA

Get a comparison of email setup modes (Relay vs Domain) AND the optional channels — realtime voice (OPENAI_API_KEY), phone call-control with a 46elks-vs-Twilio provider choice, and the Telegram channel — each with difficulty levels, requirements, pros/cons, and step-by-step instructions. Show this to users who want to set up real internet email, voice calls, phone, or Telegram.

ParametersJSON Schema
NameRequiredDescriptionDefault
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.6/5.0
Behavior2/5

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

No annotations are provided, and the description does not disclose any behavioral traits such as read-only nature, side effects, or authorization needs. It lacks transparency beyond stating the content returned.

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 description is two sentences, front-loaded with the main purpose. It is efficient and contains all necessary information without redundancy, though slightly verbose in listing channels.

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

Completeness3/5

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

The tool has no output schema, so the description should explain the return format. It does not specify whether the guide is returned as text, a structured object, or a URL. Given the simplicity (one optional param), it is mostly complete but missing output details.

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?

The input schema covers 100% of parameters with descriptions, so the description adds no extra meaning beyond the schema. Baseline score of 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?

The description clearly states the tool provides a comparison of email setup modes and optional channels with difficulty levels, requirements, pros/cons, and instructions. It distinguishes from sibling setup tools by being a guide rather than an action tool.

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?

The description explicitly says 'Show this to users who want to set up real internet email, voice calls, phone, or Telegram,' providing clear context for use. It does not explicitly exclude scenarios or name alternatives, but the purpose is clear enough.

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

setup_operator_emailA

Save the operator's notification email address for bridge-escalation alerts. When sub-agents mail a host bridge (e.g. wake: ["codex"]) AND no fresh host session is available for a headless resume, the dispatcher forwards a digest to this address so the operator gets a phone push (via Gmail / Apple Mail / whichever app handles their address). Master-key scoped. The host agent should call this during bootstrap after asking the operator: "what email should we alert you at when sub-agents need your attention?" — the answer is typically the operator's personal Gmail with mobile push enabled. Idempotent: re-running with a new address updates the config.

ParametersJSON Schema
NameRequiredDescriptionDefault
emailYesOperator notification email (e.g. you@example.com). Pass `null` or an empty string to clear an existing setting.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.5/5.0
Behavior5/5

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

With no annotations, the description fully discloses behavior: idempotent, master-key scoped, clears setting on null/empty, and updates config on re-run. It also explains the underlying dispatch flow.

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?

The description is a single, well-structured paragraph that front-loads the purpose and provides necessary details without fluff. Every sentence earns its place.

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?

Despite no output schema, the description covers what the tool does, when to use, and behavioral traits. It is complete for a configuration tool.

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?

Schema covers both parameters with 100% description. The description adds that passing null/empty clears the setting, which is useful but not extensive. Baseline 3 is appropriate.

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?

The description clearly states the tool saves the operator's notification email for bridge-escalation alerts, with a specific verb and resource. It distinguishes from siblings by focusing on operator notifications for headless resume scenarios.

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?

The description provides explicit guidance: call during bootstrap after asking the operator for their email. It also notes idempotency and update behavior. While it doesn't explicitly mention alternatives, the context is clear.

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

setup_paymentA

Get instructions for adding a payment method to Cloudflare (required before purchasing domains). Returns Option A (self-service link) and Option B (browser automation steps). Card details go directly to Cloudflare — never stored by 🎀 AgenticMail.

ParametersJSON Schema
NameRequiredDescriptionDefault
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.3/5.0
Behavior4/5

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

Discloses that card details go directly to Cloudflare and are never stored, a key behavioral trait. No annotations exist, so description handles transparency well; could mention any auth or side effects, but not expected for a read-only guide.

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?

Two sentences, no waste, front-loaded with key purpose and returns.

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 description explicitly states returns Option A and B, covering what an agent expects. No missing context for its simple task.

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?

Schema coverage is 100% for the single optional parameter, and description does not add meaning beyond schema. Baseline 3 is appropriate.

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?

Clearly states it provides instructions for adding a payment method to Cloudflare, required before purchasing domains. Distinguishes itself from sibling tool purchase_domain.

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?

Explicitly says required before purchasing domains, implying usage context. No explicit when-not or alternatives, but sufficient for this instructional tool.

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

skill_listA

List available phone-call skill playbooks, optionally filtered by category (e.g. "negotiation", "reservations", "debt-collection") or tag. Returns summaries (id, name, description, tags) — call skill_load with the id to get the full playbook.

ParametersJSON Schema
NameRequiredDescriptionDefault
categoryNoFilter by category. Valid: negotiation, customer-service, reservations, medical-admin, legal-admin, finance-admin, real-estate, travel, subscription, home-services, social, civic, employment, debt-collection, other.
tagNoFilter by a single tag (case-insensitive).
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations, describes return format (summaries) and no side effects. Could mention pagination or auth details beyond _account parameter.

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?

Two well-structured sentences, no fluff, each sentence adds key 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?

No output schema, but description explains return fields and next step. Sufficient for this simple list tool.

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 100%, description adds category examples and return shape, providing value beyond 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?

Clearly states it lists phone-call skill playbooks, optionally filtered, and distinguishes from sibling skill_load by directing to load full playbook.

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?

Describes optional filtering and next step (skill_load), but does not mention when to use alternatives like skill_search or when not to use.

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

skill_loadA

Load the FULL skill playbook by id. Returns the complete JSON document: principles, scripted phrases, tactic priority list, boundaries, success/failure signals, exit strategy. Use the response to ground your next turns on the call — the playbook should drive your phrasing, tactic order, and exit decisions.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesSkill id (lowercase-hyphenated, e.g. "negotiate-bill-reduction").
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.1/5.0
Behavior3/5

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

With no annotations provided, the description carries the burden. It describes the action and return value but omits behavioral details like rate limits, authentication requirements (beyond parameter hints), or side effects. It is not misleading but could be more thorough.

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?

Two sentences: first states purpose and output, second gives usage guidance. No filler words, perfectly efficient.

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 simple fetch operation, the description fully covers what the tool returns and how to use the data. No output schema exists, but the description compensates by listing the JSON fields. No missing information.

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?

Schema description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema's own parameter descriptions, but it does not detract either.

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?

The description clearly states the action ('Load') and the resource ('FULL skill playbook by id'), and details the returned JSON content. It distinguishes from sibling tools like skill_list and skill_search by implying this is for retrieving a complete playbook for a specific skill.

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?

The description provides clear context on when to use the tool: 'to ground your next turns on the call'. It does not explicitly state when not to use it or mention alternatives, but the context is sufficient.

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

sms_check_codeA

Check for recent verification/OTP codes received via SMS. Scans inbound SMS for common code patterns (6-digit, 4-digit, alphanumeric). Use this after requesting a verification code during sign-up flows.

ParametersJSON Schema
NameRequiredDescriptionDefault
minutesNoHow many minutes back to check (default: 10)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.9/5.0
Behavior3/5

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

No annotations provided. Description mentions scanning for code patterns but does not disclose potential side effects (e.g., whether messages are altered or marked read). Adequate but could be more explicit.

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?

Two sentences, front-loaded with action and patterns. No unnecessary words; every sentence adds value.

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

Completeness3/5

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

Missing return value description (e.g., what the tool outputs). No output schema, so description should explain what the agent gets back. Otherwise adequate for its simplicity.

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?

Schema coverage is 100% for both parameters. Description adds context about default minutes and account override, but the schema already describes them sufficiently.

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?

Describes specific action: checking for recent verification/OTP codes via SMS, scanning for common patterns (6-digit, 4-digit, alphanumeric). Clearly distinguishes from sibling tools like sms_messages.

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?

States to use after requesting a verification code during sign-up flows. Provides clear context but does not explicitly mention when not to use or alternatives.

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

sms_configA

Get the current SMS/phone number configuration for this agent. Shows whether SMS is enabled, the phone number, and forwarding email.

ParametersJSON Schema
NameRequiredDescriptionDefault
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.5/5.0
Behavior2/5

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

With no annotations, the description must disclose behaviors fully. It states the tool is a read operation ('Get') and lists returned fields, but does not mention side effects, authentication requirements beyond parameter hint, or rate limits. More detail could improve transparency.

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?

The description is a single concise sentence that front-loads the main purpose. Every word adds value, with no fluff.

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

Completeness3/5

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

The description adequately explains the return fields, but given there is no output schema, it could be more complete by mentioning potential errors or conditions like when SMS is not configured. Still, it covers the core information.

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?

Schema description coverage is 100% for the only parameter '_account', and the schema provides rich details. The tool description does not add extra meaning beyond the schema, so baseline score of 3 is appropriate.

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?

The description uses a specific verb 'Get' and identifies the resource as 'SMS/phone number configuration'. It clearly states what the tool does and distinguishes it from sibling tools like 'sms_messages' or 'sms_setup'.

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

Usage Guidelines3/5

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

The description implies usage for retrieving configuration but does not explicitly state when to use it versus alternatives or provide any exclusions. It lacks guidance on prerequisites or context.

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

sms_messagesA

List SMS messages (inbound and outbound). Use direction filter to see only received or sent messages.

ParametersJSON Schema
NameRequiredDescriptionDefault
directionNoFilter by direction
limitNoMax messages (default: 20)
offsetNoSkip messages (default: 0)
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.5/5.0
Behavior2/5

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

No annotations are provided, and the description does not disclose behavioral traits beyond listing. It does not explicitly state that the operation is read-only or mention any side effects.

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?

Two sentences, no unnecessary words, front-loaded with the main purpose. Very concise and well-structured.

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

Completeness3/5

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

Given the simplicity of the tool, the description is adequate but lacks details on response format, pagination, or default ordering. No output schema exists to compensate.

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?

With 100% schema coverage, the schema already documents all parameters. The description adds value only for the direction filter by explaining its use, but does not elaborate on limit, offset, or _account.

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?

The description clearly states it lists SMS messages, mentioning both inbound and outbound. It is a specific and distinct tool among siblings, with no confusion.

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

Usage Guidelines3/5

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

The description provides a hint on using the direction filter but does not specify when to use this tool versus other list tools or provide exclusion criteria.

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

sms_parse_emailA

Parse an SMS from a forwarded Google Voice email. Use this when you receive an email from Google Voice containing an SMS. Extracts the sender number, message body, and any verification codes.

ParametersJSON Schema
NameRequiredDescriptionDefault
emailBodyYesThe email body text to parse
emailFromNoThe email sender address
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.9/5.0
Behavior3/5

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

No annotations are provided, so the description bears the full burden. It discloses that the tool extracts sender number, message body, and verification codes, implying a read-only operation. However, it does not explain behavior on parse failures, required email format, or side effects. This is adequate but not comprehensive.

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?

The description is extremely concise—two sentences—with no superfluous information. Every sentence adds value: the first describes the action, the second provides usage context and outputs.

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

Completeness3/5

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

Given the tool's simplicity (3 parameters, no output schema, no annotations), the description is reasonably complete. It covers the tool's purpose, usage context, and extracted fields. However, it lacks details on the return format or error handling, which could be helpful for an agent to parse the result correctly.

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?

The input schema has 100% coverage with descriptions for all three parameters. The tool's description does not add significant extra meaning beyond these schema descriptions, so the baseline of 3 is appropriate. The description mentions 'forwarded Google Voice email' which hints at the expected email format but does not elaborate on parameter specifics.

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?

The description clearly states the tool's purpose: parsing an SMS from a forwarded Google Voice email. It specifies the source (Google Voice email) and the extracted data (sender number, message body, verification codes). The name 'sms_parse_email' is descriptive and distinguishes it from sibling tools like 'read_email' and 'sms_messages'.

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?

The description explicitly states when to use the tool: 'Use this when you receive an email from Google Voice containing an SMS.' This provides clear context, though it does not mention when not to use it or suggest alternatives. However, the specificity is sufficient for most use cases.

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

sms_read_voiceA

Get instructions and URL for reading SMS directly from Google Voice web (FASTEST method). Returns the voice.google.com URL and guidance for browser-based SMS reading. Primary method - much faster than email forwarding.

ParametersJSON Schema
NameRequiredDescriptionDefault
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.3/5.0
Behavior4/5

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

No annotations are provided, so the description carries full burden. It transparently states the returns: 'voice.google.com URL and guidance for browser-based SMS reading'. It also claims performance superiority ('much faster than email forwarding'), which clarifies behavior. No destructive actions are hinted, and no contradictions exist.

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?

Two concise sentences with no fluff. The key information (action, resource, speed advantage) is front-loaded. Every sentence adds value.

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 simple tool with one optional parameter and no output schema, the description fully explains what it does, what it returns, and why it should be used. There are no missing details.

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?

Schema description coverage is 100% (one parameter '_account' with a detailed description). The description does not add any additional meaning beyond what the schema already provides, earning the baseline score.

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?

The description clearly states the verb 'Get' and the resource 'instructions and URL for reading SMS directly from Google Voice web'. It explicitly differentiates from 'email forwarding' by calling it the 'FASTEST method', distinguishing it from siblings.

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?

The description provides a clear context for when to use this tool ('Primary method - much faster than email forwarding'), but does not explicitly mention when not to use it or list alternatives beyond email forwarding. Sibling tools like sms_send, sms_messages exist but are not referenced.

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

sms_recordA

Record an SMS message read from Google Voice web or any other source. Saves to SMS database and extracts verification codes. Use after reading a message from voice.google.com.

ParametersJSON Schema
NameRequiredDescriptionDefault
fromYesSender phone number
bodyYesSMS message text
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.5/5.0
Behavior3/5

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

With no annotations provided, the description carries full responsibility. It discloses the tool saves to a database and extracts verification codes, which is good but lacks details on idempotency, duplicate handling, or permissions.

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?

The description is concise, consisting of two sentences that front-load the core action. Every sentence adds value without unnecessary detail.

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

Completeness3/5

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

The description covers the primary purpose and usage context but omits details about return values, such as whether a record ID is returned, and does not explain the extraction behavior in depth. Given the absence of an output schema, more completeness would be beneficial.

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?

Schema coverage is 100% and the schema descriptions are clear. The tool description does not add extra meaning beyond the schema, so a baseline score of 3 is appropriate.

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?

The description clearly states the tool records an SMS message from Google Voice or other sources, saves it to a database, and extracts verification codes. The purpose is specific and actionable, but it does not explicitly differentiate from sibling tools like sms_read_voice.

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

Usage Guidelines3/5

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

The description advises to use the tool after reading a message from voice.google.com, providing a clear usage context. However, it does not specify when not to use it or mention any alternative tools.

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

sms_sendA

Send an SMS text message. Direct provider configs such as 46elks send through the provider API; Google Voice legacy configs return browser-send instructions.

ParametersJSON Schema
NameRequiredDescriptionDefault
toYesRecipient phone number
bodyYesText message body
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.9/5.0
Behavior3/5

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

With no annotations, the description must disclose behavioral traits. It mentions that for Google Voice configs it returns browser instructions rather than sending directly, which is a key behavior. However, it omits details on success/failure, authentication requirements beyond the _account parameter, or rate limits. Adequate but not comprehensive.

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?

The description is two sentences: the first defines the core purpose, the second clarifies provider-specific behavior. It is front-loaded and concise without wasted words.

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

Completeness3/5

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

The tool has no output schema, so the description should hint at return values. It partially does for Google Voice, but not for direct provider sends (presumably success/error). Also missing info on error handling, confirmation, or asynchronous behavior. Acceptable for a simple tool but could be more complete.

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?

The input schema has 100% coverage with descriptions for all three parameters. The tool description does not add additional parameter semantics beyond what the schema provides. Thus, baseline score of 3 is appropriate.

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?

The description clearly states the tool sends an SMS text message, distinguishing between direct provider configs (API send) and Google Voice legacy configs (browser instructions). This provides a specific verb+resource and differentiates from sibling tools like sms_config or sms_messages.

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?

The description gives context on when to use based on provider configuration type, but does not explicitly state when not to use or list alternative tools. It implies usage scenarios, which is clear but could be more directive.

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

sms_setupB

Configure SMS/phone number access. Supports Google Voice legacy forwarding and direct 46elks provider delivery/webhooks.

ParametersJSON Schema
NameRequiredDescriptionDefault
phoneNumberYesSMS phone number in E.164 format (e.g. +46701234567 or +12125551234)
providerNoSMS provider (default: google_voice)
forwardingEmailNoGoogle Voice only: email address Google Voice forwards SMS to (defaults to agent email)
forwardingPasswordNoGoogle Voice only: app password for a separate forwarding Gmail
usernameNo46elks only: API username
passwordNo46elks only: API password
webhookSecretNo46elks only: shared secret required on inbound SMS webhooks
apiUrlNo46elks only: optional API base URL override
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

B3.4/5.0
Behavior2/5

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

No annotations are present, so the description carries full burden. It mentions supporting two providers but does not disclose side effects, idempotency, authentication requirements, or whether configuration overwrites existing settings. The schema's _account parameter hints at identity override, but the description omits this.

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?

Two sentences are used: first states core purpose, second adds details on providers. No extraneous information, and the key action is front-loaded.

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

Completeness2/5

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

Given 9 parameters and no annotations or output schema, the description is overly brief. It lacks context on prerequisites, result of configuration, or how it integrates with sibling tools. For a setup tool, this is insufficient.

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?

With 100% schema description coverage, the baseline is 3. The description adds minimal value beyond the schema by mentioning provider names, but does not provide additional meaning for individual parameters.

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?

The description clearly states the tool configures SMS/phone number access, using a specific verb ('Configure') and specifying the resource ('SMS/phone number access'). It distinguishes from sibling SMS tools like sms_send and sms_messages by focusing on setup.

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

Usage Guidelines3/5

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

The description implies usage for initial SMS setup with specific providers, but lacks explicit guidance on when to use versus other SMS tools or alternatives. No direct exclusions are provided.

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

stop_agentA

HARD-stop an agent mid-task WITHOUT deleting it. Sets the agent's stopped flag and (0.9.29+) immediately ABORTS any in-flight worker for that agent — the running SDK call is killed via AbortController, any queued coalesced wakes are dropped, and any deferred rate-limit retries are cancelled. After the stop, the dispatcher refuses to wake the agent for any reason (allowlists, To/Cc, task events all silently no-op). Mail STILL lands in the mailbox, so the email-thread audit trail is preserved. Use this instead of delete_agent when you want to halt a churning sub-agent right now and keep the option to read the thread later or resume it. Resume with resume_agent. Requires master API key.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesName of the agent to stop
reasonNoOptional free-form reason (e.g. "task superseded", "user requested halt") — stored on the agent row for later audit.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.6/5.0
Behavior5/5

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

Despite no annotations, the description discloses extensive behavioral details: sets the `stopped` flag, aborts in-flight workers, drops queued wakes, cancels retries, and prevents future dispatches while preserving mail delivery. Version-specific behavior (0.9.29+) is noted, ensuring full transparency.

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 description is detailed but well-organized, with the key action and use-case in the first sentences. Every sentence provides valuable information, though length is slightly higher due to technical specifics. It is appropriately structured for a complex tool.

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?

Given no output schema and no annotations, the description fully covers the tool's behavior, prerequisites (master API key), side effects, and links to related tools (delete_agent, resume_agent). It is complete for an agent to understand and use correctly.

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?

Schema coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond what the input schema provides for the parameters (name, reason, _account). It focuses on the tool's behavior rather than parameter details.

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?

The description starts with 'HARD-stop an agent mid-task WITHOUT deleting it,' clearly stating the verb and resource. It distinguishes itself from the sibling 'delete_agent' by explaining the difference (preserves mail thread, allows resume), making the purpose unambiguous.

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 'Use this instead of delete_agent when you want to halt a churning sub-agent right now and keep the option to read the thread later or resume it.' Also mentions it requires a master API key, giving clear guidance on when and how to use the tool.

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

storageA

Full database management system for agents. 28 actions: DDL (create/alter/drop/clone/rename tables & columns), DML (insert/upsert/query/aggregate/update/delete/truncate), indexing (create/list/drop/reindex), import/export (JSON/CSV, conflict handling), raw SQL, maintenance (stats/vacuum/analyze/explain), archiving. WHERE supports operators: $gt, $gte, $lt, $lte, $ne, $like, $ilike, $in, $not_in, $is_null, $between. Works on SQLite, Postgres, MySQL, Turso.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYescreate_table, list_tables, describe_table, insert, upsert, query, aggregate, update, delete_rows, truncate, drop_table, clone_table, rename_table, rename_column, add_column, drop_column, create_index, list_indexes, drop_index, reindex, archive_table, unarchive_table, export, import, sql, stats, vacuum, analyze, explain
tableNoTable name
descriptionNoFor create_table: human-readable description
columnsNoFor create_table: [{name, type, required?, default?, unique?, primaryKey?, references?: {table, column, onDelete?}, check?}]
indexesNoFor create_table: [{columns, unique?, name?, where?}]
sharedNoFor create_table: shared across agents
timestampsNoFor create_table: auto-add created_at/updated_at (default: true)
rowsNoFor insert/upsert/import: row objects
whereNoFilter conditions with operator support
setNoFor update: {column: newValue}
orderByNoORDER BY clause
limitNoMax rows
offsetNoSkip rows
selectColumnsNoSpecific columns to select
distinctNoSELECT DISTINCT
groupByNoGROUP BY clause
havingNoHAVING clause
operationsNoFor aggregate: [{fn: count|sum|avg|min|max|count_distinct, column?, alias?}]
columnNoFor add_column: {name, type, ...}
columnNameNoFor drop_column
indexNameNoFor create/drop_index
indexColumnsNoFor create_index
indexUniqueNoFor create_index
indexWhereNoPartial index condition
newNameNoFor rename_table/rename_column/clone_table
oldNameNoFor rename_column
conflictColumnNoFor upsert/import
onConflictNoFor import: skip|replace|error
includeDataNoFor clone_table
formatNoFor export: json|csv
sqlNoFor sql/explain: raw SQL
paramsNoFor sql/explain: query params
includeSharedNoFor list_tables
includeArchivedNoFor list_tables
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.8/5.0
Behavior3/5

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

No annotations are provided, so the description must bear the full burden. It discloses the range of actions including destructive ones (drop_table, truncate), but does not detail side effects, data persistence guarantees, or authentication requirements beyond a brief mention in _account parameter. The multi-database support is mentioned, which adds transparency.

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 description is a single, well-organized paragraph that front-loads the core purpose and then systematically lists action categories and operators. It is dense but efficient, with no wasted words. A minor improvement could be bullet points for readability.

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

Completeness3/5

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

Given the tool's complexity (35 parameters, no output schema), the description covers actions, operators, and supported databases. However, it lacks explanation of return values, error handling, or usage examples. For an agent to effectively use this tool, more context on expected outputs and caveats would be helpful.

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%, but the description adds value beyond the schema by listing all 28 action values and documenting the WHERE operator set ($gt, $gte, etc.) and database compatibility. This compensates for the schema's lack of operator explanation and provides a high-level guide.

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?

The description clearly states 'Full database management system for agents' and enumerates 28 specific actions (DDL, DML, indexing, etc.), distinguishing it from sibling tools which are primarily email, messaging, and setup tools. The verb+resource combination is specific and unambiguous.

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

Usage Guidelines3/5

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

The description implies usage for database operations and lists supported databases, but it does not explicitly state when to use this tool versus alternatives like 'memory' or other data-related tools. No when-not-to-use guidance or prerequisite conditions are provided.

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

submit_resultA

Submit the result for a claimed task, marking it as completed

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesTask ID
resultNoTask result data
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.5/5.0
Behavior2/5

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

Without annotations, the description should disclose behavioral traits (e.g., idempotency, error handling, whether submission is irreversible). It only says 'marking it as completed', which is minimal.

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?

The description is a single concise sentence with no wasted words, effectively communicating the core purpose.

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

Completeness3/5

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

Given no output schema, the description lacks information about return values (e.g., success status) or whether the task state changes beyond 'completed'. Adequate but incomplete for a mutation tool.

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?

Schema coverage is 100%, so baseline is 3. The description adds no extra meaning beyond what the schema already provides for parameters 'id', 'result', and '_account'.

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?

The description clearly states the action ('Submit the result for a claimed task') and outcome ('marking it as completed'), distinguishing it from sibling tools like 'claim_task'.

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

Usage Guidelines3/5

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

No explicit guidance on when to use this tool versus alternatives or prerequisites (e.g., must have claimed the task first). Usage is implied but not clarified.

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

tail_workerA

Tail the log of a running (or recently-finished) dispatcher worker. Use this when check_activity shows a worker has been running a long time or is marked stale, and you want to see what it is actually doing — every tool call, tool result, and assistant chunk is logged as a one-liner. Returns the last N lines (default 80). The workerId comes from check_activity output. Requires master key.

ParametersJSON Schema
NameRequiredDescriptionDefault
workerIdYesWorker id from check_activity output.
linesNoHow many trailing log lines to return. Default 80, max 1000.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.9/5.0
Behavior5/5

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

Even without annotations, the description fully discloses behavior: it returns the last N lines (default 80), logs every call/result/chunk, and requires master key. No contradictions.

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?

Four sentences, each contributing meaning: purpose, when-to-use, what is logged, parameter defaults, and auth requirement. No redundant or filler content.

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?

Given no output schema and no annotations, the description covers all essential aspects: purpose, usage trigger, parameter details (with defaults and source), behavioral output (what is returned), and authentication requirement. No gaps.

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. The description adds useful context: 'Worker id from check_activity output' for workerId, and implicitly mentions default lines=80 and max=1000. It also adds authentication info for _account that is not in schema. However, the schema itself describes all parameters adequately, so the description provides moderate added value.

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?

The description starts with a clear verb 'Tail' and resource 'log of a running (or recently-finished) dispatcher worker'. It specifies the exact domain (dispatcher worker logs) and distinguishes itself from the sibling tool 'check_activity' which checks status, not logs.

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 tells when to use: 'Use this when check_activity shows a worker has been running a long time or is marked stale'. Also hints at alternative (check_activity) and explains where workerId comes from, guiding the agent on proper invocation flow.

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

telegram_configA

Get the current Telegram channel configuration for this agent — whether it is enabled, the bot username, linked chats, and transport mode. Credentials are redacted.

ParametersJSON Schema
NameRequiredDescriptionDefault
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.6/5.0
Behavior3/5

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

No annotations provided, so description carries burden. It discloses credential redaction, but doesn't mention authentication needs, error states, or rate limits. Adequate for a simple read operation.

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?

Two concise sentences with actionable verb and key details. No redundancy.

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?

Covers purpose and key behavioral aspect (redaction). Given no output schema, mentions response fields. Minor gap: no description of response structure beyond listed fields.

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?

Single parameter with 100% schema coverage; description does not add extra meaning beyond the schema. Baseline score of 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?

Description clearly states 'Get the current Telegram channel configuration' and lists specific fields (enabled, bot username, linked chats, transport mode). Differentiates from siblings like telegram_setup (setup) and telegram_send (send messages).

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

Usage Guidelines2/5

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

No guidance on when to use this tool vs alternatives or prerequisites. Implied usage is to retrieve current config, but lacks explicit context.

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

telegram_messagesA

List stored Telegram messages (inbound and outbound) for this agent, newest first.

ParametersJSON Schema
NameRequiredDescriptionDefault
directionNoFilter by direction.
chatIdNoFilter by chat id.
limitNoMax messages (default: 20, max: 100).
offsetNoSkip messages (default: 0).
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.9/5.0
Behavior4/5

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

With no annotations, the description discloses ordering, scope (for this agent), and directional filtering. However, it does not mention read-only nature, authentication requirements (only hinted via _account parameter), rate limits, or pagination behavior beyond parameter descriptions.

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?

The description is a single, front-loaded sentence of 12 words. Every word is functional, and the verb 'List' immediately conveys the action.

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

Completeness3/5

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

The tool has 5 parameters, no output schema, and no annotations. The description does not explain return format, error scenarios, or the structure of individual messages, leaving gaps for an agent to infer.

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?

Schema coverage is 100%, so baseline is 3. The description adds the ordering detail ('newest first') but otherwise does not enrich parameter meaning beyond what the schema already provides.

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?

The description clearly states the tool lists stored Telegram messages for the agent, specifying direction (inbound/outbound) and ordering (newest first). This is a specific verb-resource combination that distinguishes it from sibling tools like telegram_send or telegram_config.

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

Usage Guidelines3/5

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

The description implies the tool is for reading past messages but provides no explicit guidance on when to use it versus alternatives (e.g., check_messages, telegram_poll). No exclusion criteria or comparative context is given.

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

telegram_pollA

Pull and process new Telegram updates (poll-mode transport). Call this on a schedule when the channel is in poll mode to ingest new inbound messages and answer ask_operator questions sent from the operator chat.

ParametersJSON Schema
NameRequiredDescriptionDefault
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.9/5.0
Behavior3/5

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

No annotations provided, so description carries full burden. It mentions processing and answering questions, but doesn't detail side effects, rate limits, or authentication beyond schema. Adequate but not fully transparent.

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?

Two focused sentences with no wasted words. Front-loaded with purpose, then usage context.

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

Completeness3/5

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

Covers purpose and usage adequately, but with no output schema, description fails to specify return value or confirmation of action. A gap for a polling tool that likely returns updates or status.

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?

Only one parameter (_account) with 100% schema coverage; description adds no extra meaning beyond the schema's description. Baseline 3 as per rubric.

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?

Description clearly states the tool pulls and processes Telegram updates via poll-mode transport, distinguishing it from sibling tools like telegram_send or telegram_config. Verb+resource+mode is specific.

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?

Explicitly says to call on a schedule when channel is in poll mode. Provides context for ingestion and answering questions, but lacks explicit when-not-to-use or alternatives.

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

telegram_sendA

Send a Telegram message from this agent's bot to a chat. Requires the Telegram channel to be configured (telegram_setup) and enabled.

ParametersJSON Schema
NameRequiredDescriptionDefault
chatIdYesTarget Telegram chat id.
textYesMessage text to send.
replyToMessageIdNoOptional Telegram message id to reply to.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.5/5.0
Behavior2/5

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

With no annotations, the description must fully disclose behavioral traits. It indicates a write operation (sending) and a prerequisite, but lacks details on idempotency, rate limits, error handling, or chat membership requirements.

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?

The description is only two concise sentences, each adding essential information: the action and the prerequisite. No wasted words.

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

Completeness3/5

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

Given no output schema, the description should hint at the return value or confirm success/failure. It does not, and also misses guidance on how to obtain chatId. However, the core action and requirement are covered.

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?

Schema description coverage is 100%, so the baseline is 3. The description does not add any extra parameter semantics beyond what the schema already provides.

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?

The description clearly states the action ('Send a Telegram message') and the resource/context ('from this agent's bot to a chat'), making the purpose immediately obvious.

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

Usage Guidelines3/5

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

It mentions a prerequisite (requires telegram_setup and enabled), providing some usage context, but does not specify when not to use it or how it differs from siblings like telegram_poll or telegram_messages.

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

telegram_setupA

Configure the Telegram channel for this agent — register a bot token from @BotFather and link the chat(s) allowed to message the agent. The token is verified with Telegram and stored encrypted. Defaults to poll mode (call telegram_poll on a schedule); pass mode "webhook" with a public HTTPS webhookUrl + webhookSecret for push delivery.

ParametersJSON Schema
NameRequiredDescriptionDefault
botTokenYesTelegram bot API token from @BotFather (e.g. 123456789:AA...).
operatorChatIdNoThe chat id of the operator — always allowed to message the agent and to answer ask_operator questions.
allowedChatIdsNoAdditional chat ids permitted to message the agent. An empty allow-list means only the operator chat can reach the agent (fail-closed).
modeNoInbound transport: "poll" (default — pull updates with telegram_poll) or "webhook" (Telegram pushes updates).
webhookUrlNoWebhook mode only: public HTTPS URL Telegram delivers updates to.
webhookSecretNoWebhook mode only: shared secret echoed in the X-Telegram-Bot-Api-Secret-Token header (at least 16 chars, A-Z a-z 0-9 _ -).
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.2/5.0
Behavior3/5

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

With no annotations, description bears full burden. It discloses token verification, encrypted storage, and default mode, but omits behavior on invalid tokens, overrides, or side effects like overwriting previous config.

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?

Three sentences with no redundancy: first states purpose, second adds verification/encryption, third explains modes. Front-loaded and efficient.

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?

Given 7 params, no output schema, and no annotations, description covers core setup steps, token source, and modes. Missing details on return value or idempotency, but sufficient for typical usage.

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. Description adds value by specifying token source (@BotFather), linking allowedChatIds to operator chat concept, and clarifying mode requirements beyond enum descriptions.

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?

Description clearly states the tool configures the Telegram channel, registers a bot token from @BotFather, and links allowed chats. It distinguishes itself from sibling tools like telegram_poll and telegram_send by focusing on setup.

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?

Description explains when to use this tool (to set up Telegram) and mentions alternatives for inbound transport (poll vs webhook). It implicitly tells users to use telegram_poll after setup but lacks explicit exclusion guidelines.

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

template_sendB

Send an email using a saved template with variable substitution. Variables like {{name}} are replaced.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesTemplate ID
toYesRecipient email
variablesNoVariables to substitute: { name: "Alice" }
ccNoCC recipients
bccNoBCC recipients
wakeNoOptional. Names of the agents who should get a host turn when this template-rendered mail lands. Pass `[]` to deliver silently. Omit to wake everyone CC'd.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

B3.4/5.0
Behavior2/5

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

No annotations are provided, so the description must carry the burden for behavioral disclosure. It mentions variable substitution but lacks details on error handling, required authentication, what happens if the template is missing, or the return value. The presence of the '_account' parameter hints at authentication but is not explained.

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 description is two sentences, front-loaded with the core purpose, and no unnecessary words. It is concise but could be more structured for clarity.

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

Completeness3/5

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

The tool has 7 parameters and no output schema. The description covers the core functionality but does not explain optional parameters like cc, bcc, wake, or _account. For a complex tool, more context is needed for autonomous use.

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?

Schema coverage is 100%, so baseline is 3. The description adds minimal value beyond the schema, only illustrating variable format '{{name}}'. The schema itself already describes each parameter adequately.

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?

The description clearly states the action 'Send an email' and the resource 'saved template', and highlights the key feature of variable substitution with an example. This distinguishes it from sibling tools like send_email (plain) and broadcast_email.

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

Usage Guidelines3/5

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

The description implies usage for templated emails but does not explicitly state when to use vs alternatives or provide any exclusions. No guidance on prerequisites like having a saved template.

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

update_metadataA

Update the current agent's metadata. Merges provided keys with existing metadata.

ParametersJSON Schema
NameRequiredDescriptionDefault
metadataYesMetadata key-value pairs to set or update
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4/5.0
Behavior3/5

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

With no annotations, the description bears full burden. It discloses that the tool merges keys rather than replacing all metadata, which is good. However, it does not specify return value, size limits, or side effects, leaving some behavioral gaps.

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?

The description is extremely concise—two sentences with no extraneous words. It front-loads the verb and resource, making it efficient for an AI agent to parse.

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 simple update operation, the description covers the essential behavior (merge). It lacks details on what happens to existing keys not in the input, whether metadata persists across calls, and what the 'current agent' refers to, but overall it is sufficient given the tool's simplicity and lack of output schema.

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. The description adds value by clarifying 'merges provided keys with existing metadata', which goes beyond the schema's 'set or update'. This extra context justifies a score of 4.

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?

The description clearly states the tool updates the current agent's metadata and merges provided keys with existing metadata, distinguishing it from any potential sibling tools. The verb 'update' and resource 'current agent's metadata' are specific and unambiguous.

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

Usage Guidelines3/5

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

No explicit guidance on when to use this tool versus alternatives, though there are no obvious sibling tools for metadata update. The context is implied but no exclusions or alternative tool references are provided.

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

wait_for_emailA

Block until a matching email (or task) lands in your inbox. Push-based (SSE) — far more efficient than polling. Supports filtering by sender, subject substring, thread (In-Reply-To), or a participants list. The single-most-useful tool for thread-based coordination: send a kickoff email CC'ing your team, then wait_for_email({ subject: "<core thread subject>" }) to wake on the first reply. Non-matching events that arrive during the wait are ignored — you only resume when something you asked for shows up (or timeout).

ParametersJSON Schema
NameRequiredDescriptionDefault
timeoutNoMax seconds to wait (default: 120, max: 300)
fromNoOnly resume on an email FROM this address (case-insensitive substring match on the bare address — "orion" matches "orion@localhost").
subjectNoOnly resume on an email whose subject contains this string (case-insensitive). The thread's core subject works — "Build a small game" matches "Re: Build a small game".
inReplyToNoOnly resume on an email whose In-Reply-To header equals this Message-ID. Most precise thread filter — use when you have the exact Message-ID of the message you expect a reply to.
participantsNoOnly resume on an email from ANY of these addresses (case-insensitive). Use this to wait for any teammate's reply, e.g. ["vesper@localhost", "orion@localhost"].
includeTasksNoInclude task-assignment events as matches (default: true). Set false if you only care about email.
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A4.4/5.0
Behavior5/5

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

No annotations provided, so the description carries full burden. It discloses blocking nature, push-based mechanism, timeout (default and max), and that non-matching events are ignored. Side effects are none (pure read). This is thorough for a wait tool.

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?

The description is concise with no wasted sentences. It front-loads the core function, then provides a usage example and behavioral details. Every sentence adds value.

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?

No output schema, but the description explains return behavior (wakes on match or timeout). It covers blocking, filters, and timeout. Could mention return value format, but the behavior is well-specified. Minor gap in not describing what happens on timeout explicitly, but implied.

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?

Schema description coverage is 100%, so baseline is 3. The description adds some context (e.g., push-based, example usage) but does not significantly enhance parameter meaning beyond what the schema already provides. Each parameter in the schema already has a clear description.

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?

The description clearly states the tool blocks until a matching email or task arrives, specifies it is push-based (SSE) and more efficient than polling, and lists filtering options. It distinguishes itself from alternative polling methods.

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?

The description provides clear when-to-use context, especially for thread-based coordination with an example. It does not explicitly state when not to use or mention alternatives, but the push-based vs polling distinction implies the alternative. The sibling list contains many email tools, but no direct comparison is given.

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

whoamiA

Get the current agent's account info — name, email, role, and metadata

ParametersJSON Schema
NameRequiredDescriptionDefault
_accountNoOptional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).

TDQS

A3.6/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden. It lists the returned fields but does not disclose behavioral traits such as read-only nature, authentication requirements, rate limits, or side effects. This is insufficient for a tool with zero annotation coverage.

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?

The description is a single sentence that front-loads the verb and resource, with no extraneous words. It is appropriately concise for the tool's simplicity.

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 simple identity retrieval tool with one optional parameter and no output schema, the description adequately specifies the return fields (name, email, role, metadata). Minor missing details like error handling for invalid '_account' are acceptable given tool complexity.

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?

Schema coverage is 100% and the parameter '_account' has a detailed description in the schema. The tool description adds no additional meaning beyond the schema, so baseline score 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?

The description clearly states the tool retrieves the current agent's account info with specific fields (name, email, role, metadata), using a specific verb and resource. No sibling tool has a similar purpose, so it distinguishes well.

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

Usage Guidelines3/5

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

The description implies usage context (retrieving identity), but provides no explicit when-to-use or when-not-to-use guidance, nor alternatives. For a simple lookup this may suffice, but there is no mention of prerequisites or edge cases.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.9.103
    • Addedbroadcast_email
  2. 100 tool updatesv0.9.101
    • Addedbatch_delete
    • Addedbatch_mark_read
    • Addedbatch_mark_unread
    • Addedbatch_move
    • Addedbatch_read
    • Addedcall_agent
    • Addedcall_answer_query
    • Addedcall_cancel
    • Addedcall_open_queries
    • Addedcall_phone
    • Addedcall_status
    • Addedcall_transcript
    • Addedcheck_activity
    • Addedcheck_gateway_status
    • Addedcheck_health
    • Addedcheck_messages
    • Addedcheck_tasks
    • Addedclaim_task
    • Addedcleanup_agents
    • Addedcreate_account
    • Addedcreate_folder
    • Addeddelete_agent
    • Addeddelete_email
    • Addeddeletion_reports
    • Addedforward_email
    • Addedget_thread_id
    • Addedimport_relay_email
    • Addedinbox_digest
    • Addedinvoke
    • Addedlist_agents
    • Addedlist_folder
    • Addedlist_folders
    • Addedlist_inbox
    • Addedmanage_contacts
    • Addedmanage_drafts
    • Addedmanage_pending_emails
    • Addedmanage_rules
    • Addedmanage_scheduled
    • Addedmanage_signatures
    • Addedmanage_spam
    • Addedmanage_tags
    • Addedmanage_templates
    • Addedmark_read
    • Addedmark_unread
    • Addedmedia_audio_edit
    • Addedmedia_capabilities
    • Addedmedia_image_edit
    • Addedmedia_info
    • Addedmedia_tts
    • Addedmedia_tts_voices
    • Addedmedia_video_edit
    • Addedmedia_video_understand
    • Addedmedia_voice_clone
    • Addedmemory
    • Addedmemory_context
    • Addedmemory_reflect
    • Addedmemory_stats
    • Addedmessage_agent
    • Addedmove_email
    • Addedphone_capabilities
    • Addedphone_transport_setup
    • Addedpurchase_domain
    • Addedread_email
    • Addedreply_email
    • Addedrequest_tools
    • Addedresume_agent
    • Addedsave_thread_memory
    • Addedsearch_emails
    • Addedsend_email
    • Addedsend_test_email
    • Addedsetup_email_domain
    • Addedsetup_email_relay
    • Addedsetup_gmail_alias
    • Addedsetup_guide
    • Addedsetup_operator_email
    • Addedsetup_payment
    • Addedskill_list
    • Addedskill_load
    • Addedskill_search
    • Addedsms_check_code
    • Addedsms_config
    • Addedsms_messages
    • Addedsms_parse_email
    • Addedsms_read_voice
    • Addedsms_record
    • Addedsms_send
    • Addedsms_setup
    • Addedstop_agent
    • Addedstorage
    • Addedsubmit_result
    • Addedtail_worker
    • Addedtelegram_config
    • Addedtelegram_messages
    • Addedtelegram_poll
    • Addedtelegram_send
    • Addedtelegram_setup
    • Addedtemplate_send
    • Addedupdate_metadata
    • Addedwait_for_email
    • Addedwhoami
  3. 98 tool updatesv0.9.89
    • Removedbatch_delete
    • Removedbatch_mark_read
    • Removedbatch_mark_unread
    • Removedbatch_move
    • Removedbatch_read
    • Removedcall_agent
    • Removedcall_cancel
    • Removedcall_phone
    • Removedcall_status
    • Removedcall_transcript
    • Removedcheck_activity
    • Removedcheck_gateway_status
    • Removedcheck_health
    • Removedcheck_messages
    • Removedcheck_tasks
    • Removedclaim_task
    • Removedcleanup_agents
    • Removedcreate_account
    • Removedcreate_folder
    • Removeddelete_agent
    • Removeddelete_email
    • Removeddeletion_reports
    • Removedforward_email
    • Removedget_thread_id
    • Removedimport_relay_email
    • Removedinbox_digest
    • Removedinvoke
    • Removedlist_agents
    • Removedlist_folder
    • Removedlist_folders
    • Removedlist_inbox
    • Removedmanage_contacts
    • Removedmanage_drafts
    • Removedmanage_pending_emails
    • Removedmanage_rules
    • Removedmanage_scheduled
    • Removedmanage_signatures
    • Removedmanage_spam
    • Removedmanage_tags
    • Removedmanage_templates
    • Removedmark_read
    • Removedmark_unread
    • Removedmedia_audio_edit
    • Removedmedia_capabilities
    • Removedmedia_image_edit
    • Removedmedia_info
    • Removedmedia_tts
    • Removedmedia_tts_voices
    • Removedmedia_video_edit
    • Removedmedia_video_understand
    • Removedmedia_voice_clone
    • Removedmemory
    • Removedmemory_context
    • Removedmemory_reflect
    • Removedmemory_stats
    • Removedmessage_agent
    • Removedmove_email
    • Removedphone_capabilities
    • Removedphone_transport_setup
    • Removedpurchase_domain
    • Removedread_email
    • Removedreply_email
    • Removedrequest_tools
    • Removedresume_agent
    • Removedsave_thread_memory
    • Removedsearch_emails
    • Removedsend_email
    • Removedsend_test_email
    • Removedsetup_email_domain
    • Removedsetup_email_relay
    • Removedsetup_gmail_alias
    • Removedsetup_guide
    • Removedsetup_operator_email
    • Removedsetup_payment
    • Removedskill_list
    • Removedskill_load
    • Removedskill_search
    • Removedsms_check_code
    • Removedsms_config
    • Removedsms_messages
    • Removedsms_parse_email
    • Removedsms_read_voice
    • Removedsms_record
    • Removedsms_send
    • Removedsms_setup
    • Removedstop_agent
    • Removedstorage
    • Removedsubmit_result
    • Removedtail_worker
    • Removedtelegram_config
    • Removedtelegram_messages
    • Removedtelegram_poll
    • Removedtelegram_send
    • Removedtelegram_setup
    • Removedtemplate_send
    • Removedupdate_metadata
    • Removedwait_for_email
    • Removedwhoami
  4. 5 tool updatesv0.9.86
    • Changedforward_email1 field changed
      • changedInput schema / properties / wake / description
        Previous value: -"Optional. Names of the agents who should get a Claude turn when the forward lands. Pass `[]` to deliver silently. Omit to wake everyone CC'd."New value: +"Optional. Names of the agents who should get a host turn when the forward lands. Pass `[]` to deliver silently. Omit to wake everyone CC'd."
    • Changedmanage_drafts1 field changed
      • changedInput schema / properties / wake / description
        Previous value: -"Optional, for action=send. Names of the agents who should get a Claude turn when the drafted mail lands. Pass `[]` to deliver silently. Omit to wake everyone CC'd."New value: +"Optional, for action=send. Names of the agents who should get a host turn when the drafted mail lands. Pass `[]` to deliver silently. Omit to wake everyone CC'd."
    • Changedreply_email1 field changed
      • changedInput schema / properties / wake / description
        Previous value: -"Optional. Names of the agents who should get a Claude turn from the dispatcher when this reply lands. CC'd agents NOT in this list still receive the email but stay asleep — saves significant tokens on large threads. Pass `[]` to deliver silently. Omit to wake everyone CC'd."New value: +"Optional. Names of the agents who should get a host turn from the dispatcher when this reply lands. CC'd agents NOT in this list still receive the email but stay asleep — saves significant tokens on large threads. Pass `[]` to deliver silently. Omit to wake everyone CC'd."
    • Changedsend_email1 field changed
      • changedInput schema / properties / to / description
        Previous value: -"Primary actor — the agent(s) you want to act on this message. Usually one address; rarely two. **Everyone else on the thread goes on `cc`, NOT here.** Lumping all participants on `to` defeats the wake gating: every local @localhost recipient on `to` gets a Claude turn, so a 5-agent thread = 5 Claude turns per round. Comma-separated supported but use sparingly."New value: +"Primary actor — the agent(s) you want to act on this message. Usually one address; rarely two. **Everyone else on the thread goes on `cc`, NOT here.** Lumping all participants on `to` defeats the wake gating: every local @localhost recipient on `to` gets a host turn, so a 5-agent thread = 5 host turns per round. Comma-separated supported but use sparingly."
    • Changedtemplate_send1 field changed
      • changedInput schema / properties / wake / description
        Previous value: -"Optional. Names of the agents who should get a Claude turn when this template-rendered mail lands. Pass `[]` to deliver silently. Omit to wake everyone CC'd."New value: +"Optional. Names of the agents who should get a host turn when this template-rendered mail lands. Pass `[]` to deliver silently. Omit to wake everyone CC'd."
  5. 1 tool updatev0.9.84
    • Changedcall_phone8 fields changed
      • changedInput schema / properties / policy / properties / alternativePolicy / properties / maxTimeShiftMinutes / description
        Previous value: -"How far the agent may move a proposed appointment without re-asking the operator."New value: +"How far the agent may move a proposed appointment without re-asking the operator, non-negative integer."
      • changedInput schema / properties / policy / properties / maxAttempts / description
        Previous value: -"Max redial attempts (server caps this)."New value: +"Max redial attempts, positive integer. Server caps this."
      • addedInput schema / properties / policy / properties / maxCallDurationSeconds
        Added value: +{
+  "description": "Hard cap on call duration in seconds, positive integer. Server enforces a ceiling.",
+  "type": "number"
+}
      • addedInput schema / properties / policy / properties / maxCostPerMission
        Added value: +{
+  "description": "Cost cap in USD as a plain decimal (e.g. 2.0, not \"USD:2.00\"). Server enforces a ceiling.",
+  "type": "number"
+}
      • removedInput schema / properties / policy / properties / maxCostUsd
        Removed value: -{
-  "description": "Cost cap in USD — going over triggers costOverLimit.",
-  "type": "number"
-}
      • removedInput schema / properties / policy / properties / maxDurationSeconds
        Removed value: -{
-  "description": "Hard cap on call duration (server enforces a ceiling).",
-  "type": "number"
-}
      • addedInput schema / properties / policy / properties / policyVersion
        Added value: +{
+  "description": "Must be the literal number 1 (no other value is accepted).",
+  "type": "number"
+}
      • changedInput schema / properties / policy / required
        Previous value: -[
-  "regionAllowlist",
-  "maxDurationSeconds",
-  "maxCostUsd",
-  "maxAttempts",
-  "transcriptEnabled",
-  "recordingEnabled",
-  "confirmPolicy",
-  "alternativePolicy"
-]New value: +[
+  "policyVersion",
+  "regionAllowlist",
+  "maxCallDurationSeconds",
+  "maxCostPerMission",
+  "maxAttempts",
+  "transcriptEnabled",
+  "recordingEnabled",
+  "confirmPolicy",
+  "alternativePolicy"
+]
  6. 12 tool updatesv0.9.79
    • Changedcall_phone6 fields changed
      • changedInput schema / properties / policy / additionalProperties
        Previous value: -{}New value: +false
      • changedInput schema / properties / policy / description
        Previous value: -"OpenClaw phone mission policy: regionAllowlist, duration/cost/attempt limits, recording/transcript flags, confirmPolicy, alternativePolicy"New value: +"Phone mission policy — see tool description for the minimal valid shape. All fields required."
      • addedInput schema / properties / policy / properties
        Added value: +{
+  "alternativePolicy": {
+    "additionalProperties": false,
+    "properties": {
+      "maxTimeShiftMinutes": {
+        "description": "How far the agent may move a proposed appointment without re-asking the operator.",
+        "type": "number"
+      }
+    },
+    "required": [
+      "maxTimeShiftMinutes"
+    ],
+    "type": "object"
+  },
+  "confirmPolicy": {
+    "additionalProperties": false,
+    "description": "Risk-decision routing. Every field uses a FIXED literal — see tool description.",
+    "properties": {
+      "contractCommitment": {
+        "description": "Must be \"never\".",
+        "enum": [
+          "never"
+        ],
+        "type": "string"
+      },
+      "costOverLimit": {
+        "description": "Must be \"needs_operator\".",
+        "enum": [
+          "needs_operator"
+        ],
+        "type": "string"
+      },
+      "paymentDetails": {
+        "description": "Must be \"never\".",
+        "enum": [
+          "never"
+        ],
+        "type": "string"
+      },
+      "sensitivePersonalData": {
+        "description": "Must be \"needs_operator\".",
+        "enum": [
+          "needs_operator"
+        ],
+        "type": "string"
+      },
+      "unclearAlternative": {
+        "description": "Must be \"needs_operator\".",
+        "enum": [
+          "needs_operator"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "paymentDetails",
+      "contractCommitment",
+      "costOverLimit",
+      "sensitivePersonalData",
+      "unclearAlternative"
+    ],
+    "type": "object"
+  },
+  "maxAttempts": {
+    "description": "Max redial attempts (server caps this).",
+    "type": "number"
+  },
+  "maxCostUsd": {
+    "description": "Cost cap in USD — going over triggers costOverLimit.",
+    "type": "number"
+  },
+  "maxDurationSeconds": {
+    "description": "Hard cap on call duration (server enforces a ceiling).",
+    "type": "number"
+  },
+  "recordingEnabled": {
+    "type": "boolean"
+  },
+  "regionAllowlist": {
+    "description": "Regions the agent is allowed to dial. Must intersect the transport's supportedRegions.",
+    "items": {
+      "enum": [
+        "AT",
+        "DE",
+        "EU",
+        "WORLD"
+      ],
+      "type": "string"
+    },
+    "type": "array"
+  },
+  "transcriptEnabled": {
+    "type": "boolean"
+  }
+}
      • addedInput schema / properties / policy / required
        Added value: +[
+  "regionAllowlist",
+  "maxDurationSeconds",
+  "maxCostUsd",
+  "maxAttempts",
+  "transcriptEnabled",
+  "recordingEnabled",
+  "confirmPolicy",
+  "alternativePolicy"
+]
      • changedInput schema / properties / task / description
        Previous value: -"Concrete call objective, e.g. reserve a table for two at 19:30"New value: +"Concrete call objective, e.g. \"reserve a table for two at 19:30\""
      • changedInput schema / properties / to / description
        Previous value: -"Target phone number in E.164 format"New value: +"Target phone number in E.164 format (e.g. +15555550100)"
    • Addeddelete_email
    • Addedforward_email
    • Addedimport_relay_email
    • Addedlist_inbox
    • Addedmark_read
    • Addedmark_unread
    • Addedmove_email
    • Addedread_email
    • Addedreply_email
    • Addedsearch_emails
    • Addedsend_email
  7. 87 tool updatesv0.9.73
    • Addedbatch_delete
    • Addedbatch_mark_read
    • Addedbatch_mark_unread
    • Addedbatch_move
    • Addedbatch_read
    • Addedcall_agent
    • Addedcall_cancel
    • Addedcall_phone
    • Addedcall_status
    • Addedcall_transcript
    • Addedcheck_activity
    • Addedcheck_gateway_status
    • Addedcheck_health
    • Addedcheck_messages
    • Addedcheck_tasks
    • Addedclaim_task
    • Addedcleanup_agents
    • Addedcreate_account
    • Addedcreate_folder
    • Addeddelete_agent
    • Addeddeletion_reports
    • Addedget_thread_id
    • Addedinbox_digest
    • Addedinvoke
    • Addedlist_agents
    • Addedlist_folder
    • Addedlist_folders
    • Addedmanage_contacts
    • Addedmanage_drafts
    • Addedmanage_pending_emails
    • Addedmanage_rules
    • Addedmanage_scheduled
    • Addedmanage_signatures
    • Addedmanage_spam
    • Addedmanage_tags
    • Addedmanage_templates
    • Addedmedia_audio_edit
    • Addedmedia_capabilities
    • Addedmedia_image_edit
    • Addedmedia_info
    • Addedmedia_tts
    • Addedmedia_tts_voices
    • Addedmedia_video_edit
    • Addedmedia_video_understand
    • Addedmedia_voice_clone
    • Addedmemory
    • Addedmemory_context
    • Addedmemory_reflect
    • Addedmemory_stats
    • Addedmessage_agent
    • Addedphone_capabilities
    • Addedphone_transport_setup
    • Addedpurchase_domain
    • Addedrequest_tools
    • Addedresume_agent
    • Addedsave_thread_memory
    • Addedsend_test_email
    • Addedsetup_email_domain
    • Addedsetup_email_relay
    • Addedsetup_gmail_alias
    • Addedsetup_guide
    • Addedsetup_operator_email
    • Addedsetup_payment
    • Addedskill_list
    • Addedskill_load
    • Addedskill_search
    • Addedsms_check_code
    • Addedsms_config
    • Addedsms_messages
    • Addedsms_parse_email
    • Addedsms_read_voice
    • Addedsms_record
    • Addedsms_send
    • Addedsms_setup
    • Addedstop_agent
    • Addedstorage
    • Addedsubmit_result
    • Addedtail_worker
    • Addedtelegram_config
    • Addedtelegram_messages
    • Addedtelegram_poll
    • Addedtelegram_send
    • Addedtelegram_setup
    • Addedtemplate_send
    • Addedupdate_metadata
    • Addedwait_for_email
    • Addedwhoami
  8. 95 tool updatesv0.9.69
    • Removedbatch_delete
    • Removedbatch_mark_read
    • Removedbatch_mark_unread
    • Removedbatch_move
    • Removedbatch_read
    • Removedcall_agent
    • Removedcall_cancel
    • Removedcall_phone
    • Removedcall_status
    • Removedcall_transcript
    • Removedcheck_activity
    • Removedcheck_gateway_status
    • Removedcheck_health
    • Removedcheck_messages
    • Removedcheck_tasks
    • Removedclaim_task
    • Removedcleanup_agents
    • Removedcreate_account
    • Removedcreate_folder
    • Removeddelete_agent
    • Removeddelete_email
    • Removeddeletion_reports
    • Removedforward_email
    • Removedget_thread_id
    • Removedimport_relay_email
    • Removedinbox_digest
    • Removedinvoke
    • Removedlist_agents
    • Removedlist_folder
    • Removedlist_folders
    • Removedlist_inbox
    • Removedmanage_contacts
    • Removedmanage_drafts
    • Removedmanage_pending_emails
    • Removedmanage_rules
    • Removedmanage_scheduled
    • Removedmanage_signatures
    • Removedmanage_spam
    • Removedmanage_tags
    • Removedmanage_templates
    • Removedmark_read
    • Removedmark_unread
    • Removedmedia_audio_edit
    • Removedmedia_capabilities
    • Removedmedia_image_edit
    • Removedmedia_info
    • Removedmedia_tts
    • Removedmedia_tts_voices
    • Removedmedia_video_edit
    • Removedmedia_video_understand
    • Removedmedia_voice_clone
    • Removedmemory
    • Removedmemory_context
    • Removedmemory_reflect
    • Removedmemory_stats
    • Removedmessage_agent
    • Removedmove_email
    • Removedphone_capabilities
    • Removedphone_transport_setup
    • Removedpurchase_domain
    • Removedread_email
    • Removedreply_email
    • Removedrequest_tools
    • Removedresume_agent
    • Removedsave_thread_memory
    • Removedsearch_emails
    • Removedsend_email
    • Removedsend_test_email
    • Removedsetup_email_domain
    • Removedsetup_email_relay
    • Removedsetup_gmail_alias
    • Removedsetup_guide
    • Removedsetup_operator_email
    • Removedsetup_payment
    • Removedsms_check_code
    • Removedsms_config
    • Removedsms_messages
    • Removedsms_parse_email
    • Removedsms_read_voice
    • Removedsms_record
    • Removedsms_send
    • Removedsms_setup
    • Removedstop_agent
    • Removedstorage
    • Removedsubmit_result
    • Removedtail_worker
    • Removedtelegram_config
    • Removedtelegram_messages
    • Removedtelegram_poll
    • Removedtelegram_send
    • Removedtelegram_setup
    • Removedtemplate_send
    • Removedupdate_metadata
    • Removedwait_for_email
    • Removedwhoami
  9. 15 tool updatesv0.9.63
    • Addedmedia_audio_edit
    • Addedmedia_capabilities
    • Addedmedia_image_edit
    • Addedmedia_info
    • Addedmedia_tts
    • Addedmedia_tts_voices
    • Addedmedia_video_edit
    • Addedmedia_video_understand
    • Addedmedia_voice_clone
    • Changedphone_transport_setup9 fields changed
      • addedInput schema / properties / accountSid
        Added value: +{
+  "description": "Twilio only: the account SID (alias for username when provider is \"twilio\").",
+  "type": "string"
+}
      • changedInput schema / properties / apiUrl / description
        Previous value: -"Optional 46elks API base URL override"New value: +"Optional provider API base URL override (46elks or Twilio REST root)"
      • addedInput schema / properties / authToken
        Added value: +{
+  "description": "Twilio only: the account auth token (alias for password when provider is \"twilio\").",
+  "type": "string"
+}
      • changedInput schema / properties / password / description
        Previous value: -"46elks API password"New value: +"46elks API password. For twilio this is the auth token — prefer the authToken param for clarity."
      • changedInput schema / properties / provider / description
        Previous value: -"Phone provider. Currently 46elks is supported for call-control missions."New value: +"Phone provider: \"46elks\" (default) or \"twilio\". Both support call-control missions and realtime voice."
      • changedInput schema / properties / provider / enum
        Previous value: -[
-  "46elks"
-]New value: +[
+  "46elks",
+  "twilio"
+]
      • changedInput schema / properties / username / description
        Previous value: -"46elks API username"New value: +"46elks API username. For twilio this is the account SID — prefer the accountSid param for clarity."
      • changedInput schema / properties / webhookSecret / description
        Previous value: -"Shared secret included on provider webhook URLs"New value: +"Shared secret included on provider webhook URLs (at least 24 characters)"
      • changedInput schema / required
        Previous value: -[
-  "phoneNumber",
-  "username",
-  "password",
-  "webhookBaseUrl",
-  "webhookSecret"
-]New value: +[
+  "phoneNumber",
+  "webhookBaseUrl",
+  "webhookSecret"
+]
    • Addedtelegram_config
    • Addedtelegram_messages
    • Addedtelegram_poll
    • Addedtelegram_send
    • Addedtelegram_setup
  10. 13 tool updatesv0.9.51
    • Addedcall_cancel
    • Addedcall_phone
    • Addedcall_status
    • Addedcall_transcript
    • Addedmemory
    • Addedmemory_context
    • Addedmemory_reflect
    • Addedmemory_stats
    • Addedphone_capabilities
    • Addedphone_transport_setup
    • Addedresume_agent
    • Changedsms_setup8 fields changed
      • addedInput schema / properties / apiUrl
        Added value: +{
+  "description": "46elks only: optional API base URL override",
+  "type": "string"
+}
      • changedInput schema / properties / forwardingEmail / description
        Previous value: -"Email address Google Voice forwards SMS to (defaults to agent email)"New value: +"Google Voice only: email address Google Voice forwards SMS to (defaults to agent email)"
      • addedInput schema / properties / forwardingPassword
        Added value: +{
+  "description": "Google Voice only: app password for a separate forwarding Gmail",
+  "type": "string"
+}
      • addedInput schema / properties / password
        Added value: +{
+  "description": "46elks only: API password",
+  "type": "string"
+}
      • changedInput schema / properties / phoneNumber / description
        Previous value: -"Google Voice phone number (e.g. +12125551234)"New value: +"SMS phone number in E.164 format (e.g. +46701234567 or +12125551234)"
      • addedInput schema / properties / provider
        Added value: +{
+  "description": "SMS provider (default: google_voice)",
+  "enum": [
+    "google_voice",
+    "46elks"
+  ],
+  "type": "string"
+}
      • addedInput schema / properties / username
        Added value: +{
+  "description": "46elks only: API username",
+  "type": "string"
+}
      • addedInput schema / properties / webhookSecret
        Added value: +{
+  "description": "46elks only: shared secret required on inbound SMS webhooks",
+  "type": "string"
+}
    • Addedstop_agent
  11. 69 tool updatesv0.9.35
    • Addedbatch_delete
    • Addedbatch_mark_read
    • Addedbatch_mark_unread
    • Addedbatch_move
    • Addedbatch_read
    • Addedcall_agent
    • Addedcheck_activity
    • Addedcheck_gateway_status
    • Addedcheck_health
    • Addedcheck_messages
    • Addedcheck_tasks
    • Addedclaim_task
    • Addedcleanup_agents
    • Addedcreate_account
    • Addedcreate_folder
    • Addeddelete_agent
    • Addeddelete_email
    • Addeddeletion_reports
    • Addedforward_email
    • Addedget_thread_id
    • Addedimport_relay_email
    • Addedinbox_digest
    • Addedinvoke
    • Addedlist_agents
    • Addedlist_folder
    • Addedlist_folders
    • Addedlist_inbox
    • Addedmanage_contacts
    • Addedmanage_drafts
    • Addedmanage_pending_emails
    • Addedmanage_rules
    • Addedmanage_scheduled
    • Addedmanage_signatures
    • Addedmanage_spam
    • Addedmanage_tags
    • Addedmanage_templates
    • Addedmark_read
    • Addedmark_unread
    • Addedmessage_agent
    • Addedmove_email
    • Addedpurchase_domain
    • Addedread_email
    • Addedreply_email
    • Addedrequest_tools
    • Addedsave_thread_memory
    • Addedsearch_emails
    • Addedsend_email
    • Addedsend_test_email
    • Addedsetup_email_domain
    • Addedsetup_email_relay
    • Addedsetup_gmail_alias
    • Addedsetup_guide
    • Addedsetup_operator_email
    • Addedsetup_payment
    • Addedsms_check_code
    • Addedsms_config
    • Addedsms_messages
    • Addedsms_parse_email
    • Addedsms_read_voice
    • Addedsms_record
    • Addedsms_send
    • Addedsms_setup
    • Addedstorage
    • Addedsubmit_result
    • Addedtail_worker
    • Addedtemplate_send
    • Addedupdate_metadata
    • Addedwait_for_email
    • Addedwhoami
  12. 68 tool updatesv0.9.31
    • Removedbatch_delete
    • Removedbatch_mark_read
    • Removedbatch_mark_unread
    • Removedbatch_move
    • Removedbatch_read
    • Removedcall_agent
    • Removedcheck_activity
    • Removedcheck_gateway_status
    • Removedcheck_health
    • Removedcheck_messages
    • Removedcheck_tasks
    • Removedclaim_task
    • Removedcleanup_agents
    • Removedcreate_account
    • Removedcreate_folder
    • Removeddelete_agent
    • Removeddelete_email
    • Removeddeletion_reports
    • Removedforward_email
    • Removedget_thread_id
    • Removedimport_relay_email
    • Removedinbox_digest
    • Removedinvoke
    • Removedlist_agents
    • Removedlist_folder
    • Removedlist_folders
    • Removedlist_inbox
    • Removedmanage_contacts
    • Removedmanage_drafts
    • Removedmanage_pending_emails
    • Removedmanage_rules
    • Removedmanage_scheduled
    • Removedmanage_signatures
    • Removedmanage_spam
    • Removedmanage_tags
    • Removedmanage_templates
    • Removedmark_read
    • Removedmark_unread
    • Removedmessage_agent
    • Removedmove_email
    • Removedpurchase_domain
    • Removedread_email
    • Removedreply_email
    • Removedrequest_tools
    • Removedsave_thread_memory
    • Removedsearch_emails
    • Removedsend_email
    • Removedsend_test_email
    • Removedsetup_email_domain
    • Removedsetup_email_relay
    • Removedsetup_gmail_alias
    • Removedsetup_guide
    • Removedsetup_payment
    • Removedsms_check_code
    • Removedsms_config
    • Removedsms_messages
    • Removedsms_parse_email
    • Removedsms_read_voice
    • Removedsms_record
    • Removedsms_send
    • Removedsms_setup
    • Removedstorage
    • Removedsubmit_result
    • Removedtail_worker
    • Removedtemplate_send
    • Removedupdate_metadata
    • Removedwait_for_email
    • Removedwhoami
Deploy Server
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

TDQS

A3.6/5.0

Scored across 101 tools

Disambiguation5/5

Each tool has a clearly distinct purpose, even within large families like media or SMS. The descriptions are detailed and explicitly distinguish concepts like send_email vs broadcast_email, or call_phone vs sms_send, with guidance on when to use which. No two tools are ambiguous.

Naming Consistency5/5

Naming follows a consistent verb_noun pattern across all tools (e.g., send_email, list_inbox, read_email, delete_email, search_emails, reply_email, forward_email). Even specialized tools like media_tts, media_info, call_phone, and sms_config use a clear pattern of domain prefix + verb. No mixing of conventions or vague verbs.

Tool Count2/5

101 tools is far too many for a coherent toolset. While the server covers multiple domains (email, SMS, phone, Telegram, media, memory, skills), the sheer volume makes it difficult for an agent to navigate and choose tools effectively. The description explicitly mentions discoverability via request_tools, but that does not mitigate the disproportionate count.

Completeness4/5

The toolset is extraordinarily comprehensive, covering nearly every aspect of email management, multi-agent coordination, SMS, phone, Telegram, media editing, and persistent memory. Minor gaps exist (e.g., no direct email archive/restore, or phone call recording management), but these are non-critical and agents can work around them. Overall, the surface is extremely thorough.

Maintenance

ActivityMaintained
ResponsivenessResponsive

Resources

Related MCP Connectors

Related MCP Servers

  • AgentMail

    agentmail-to
    -
    license
    C
    quality
    C
    maintenance
    Gives on-the-fly inboxes to AI agents. Agents / LLM's can send, receive, and take action in isolated inboxes. Built for AI unlike Gmail. Check us out at agentmail.to
    10
    101
    -

  • courier-mcp

    antonioac1
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to create disposable email inboxes and automatically extract OTPs, magic links, and verification codes from incoming emails.
    18 npm
    MIT

  • voidmail

    voidly-ai
    A
    license
    Not graded
    quality
    D
    maintenance
    Email for AI agents. Create inboxes, send and receive emails without phone or CAPTCHA.
    10 npm
    MIT

  • zerodrop-mcp

    zerodrop-dev
    A
    license
    A
    quality
    A
    maintenance
    Provides disposable email inboxes for AI agents to automatically receive and extract OTPs and magic links, enabling seamless email verification during autonomous workflows.
    3
    40 npm
    MIT