Skip to main content
Glama
hail

hail

Official

Route an email address to an agent

route_email_domain
Idempotent

Assign an agent to reply to inbound email for a domain and set whether it answers workspace members or anyone; stop replies by clearing the agent.

Instructions

Choose which agent answers mail to an address, and who it answers.

    Setting ``email_agent_id`` together with ``clear_agent=True`` is an error.
    With ``email_agent_scope="anyone"``, a stranger can make the agent use its
    allowed tools. Mail without a passing DMARC result gets no reply.
    A custom domain must be verified with inbound and sending on.
    A field left out keeps its value, except that a new agent starts at ``"members"``.

    Returns the updated ``EmailDomainResponse`` as a dict, or
    ``{"error": "<message>"}``.
    

Tool call template

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "domain_id": "<domain_id>"
    },
    "name": "route_email_domain"
  }
}

Input Schema

NameRequiredDescriptionDefault
domain_idYesEmail identity ID, the ``id`` from ``list_email_domains``.
clear_agentNo``true`` stops the agent replying to this address's mail.
email_agent_idNoAgent that replies to inbound mail, from ``list_agents`` or ``create_agent``.
email_agent_scopeNoWho the agent answers: ``members`` (verified members of the workspace whose mail passes DMARC) or ``anyone`` (every sender whose mail passes DMARC and the spam checks). Omitted: the current scope stays; a newly set agent starts at ``members``.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.32.0

TDQS

A4.3/5.0
Behavior5/5

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), it discloses the partial-update contract (an omitted field keeps its value), the special new-agent default of "members", the mutual-exclusion error, prerequisite domain verification, the DMARC no-reply behavior, and the return/error shape. That is a lot of behavior the schema and annotations do not carry.

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

Conciseness4/5

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

Front-loads the purpose in one line, then a tight block of constraints, then the return shape. Dense but no filler; the return sentence is partly redundant with the output schema, which keeps it from a 5.

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 4-parameter mutation tool with full schema coverage and an output schema, the description covers everything an agent needs: conflicts, defaults, prerequisites, security implications, and error return format.

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 already 100%, so the baseline is 3. The description still adds cross-parameter meaning, notably that email_agent_id and clear_agent are mutually exclusive and that "anyone" allows a stranger to drive the agent's allowed tools, which the per-parameter schema text does not convey.

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

Purpose4/5

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

States a specific verb and resource: choosing which agent answers mail to an address and who it may answer. That distinguishes it from update_agent (agent properties), route_number (numbers), and send_email (outbound), though it never names a sibling or explicitly says when to prefer one.

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

Usage Guidelines4/5

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

Gives concrete usage conditions: conflicting email_agent_id plus clear_agent is an error, scope="anyone" exposes the agent to strangers, DMARC-failing mail gets no reply, and custom domains must be verified with inbound and sending enabled. These are prerequisites rather than explicit routing between alternatives, so not a 5.

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