MCP tools

Each tool calls the universe’s own API and returns its JSON answer as text.

send_email

Sends an email from one of your addresses to simulated people. Returns its message_id.

Input	Required	Meaning
from	yes	Your sending address.
to	yes	Recipients (a list).
subject	yes	The subject.
cc		Copies (a list).
text		Plain-text body.
html		HTML body.

Calls POST /api/send.

wait_for_reply

Waits for the next email a simulated person sends, optionally in reply to a given message. By default their reply is written now instead of after their usual delay. A person may decide not to reply.

Input	Required	Meaning
from	yes	The person’s address.
in_reply_to		The message_id of your email.
timeout_seconds		How long to wait. Default 30.
fast		Write their due reply now. Default true.

Calls GET /api/wait/reply.

wait_for_email

Waits for the next email to an address. Returns its text plus any one-time codes and sign-in links.

Input	Required	Meaning
to	yes	The receiving address.
from		Part of the sender’s address.
subject		Words in the subject.
contains		Words in the body.
timeout_seconds		How long to wait. Default 30.

Calls GET /api/wait. Only mail that arrives after the call starts counts.

read_mailbox

Lists the messages in a mailbox folder, newest first, with the start of each message’s text.

Input	Required	Meaning
address	yes	The mailbox address.
folder		INBOX (default), Sent, Junk …

Calls GET /api/mailboxes/{address}/messages.

list_mailboxes

Every mailbox in the universe, with message counts. No inputs. Calls GET /api/mailboxes.

list_people

The simulated people in the universe: who they are, what they want, how they behave. No inputs. Calls GET /api/personas.

create_person

Adds a simulated person who will receive and answer email.

Input	Required	Meaning
name	yes	Their name.
address	yes	Their email address.
role		Such as homeowner or buyer.
org		Their company.
who		Who they are.
wants		What they want.
temperament		responsive, busy, procedural, skeptical, flaky, difficult or ghost.

Calls POST /api/personas.

push_case

Tells the simulation what your system knows about a matter, such as a deal or a ticket. The people involved learn the story and stay consistent with it.

Input	Required	Meaning
id	yes	Your id for the matter.
title		A short title.
known		What your system knows.
people		The people on it.

Calls PUT /api/cases/{id}; the other inputs are passed through as the case. See Cases for the fields the API accepts.

Caution

The case API expects known as an object of keys and values, such as {"budget": "180k"}, and each person’s addresses as a list named addresses. A plain-text known is refused with an error, and a person given only address joins the case without being cast as a persona. Tell your agent to use these shapes.

email_health

The spam score, link check, client compatibility and accessibility of an email you sent.

Input	Required	Meaning
message_id	yes	The message_id from send_email.

Calls GET /api/inspect.

advance_clock

Moves simulated time forward; everything due on the way happens.

Input	Required	Meaning
duration	yes	Such as 1h, 3h or 2d.

Calls POST /api/clock/advance.

insights

What happened to the mail you sent: reached, junked, replied, clicked, how people feel.

Input	Required	Meaning
days		The period. Default 30.

Calls GET /api/insights.