Tools

reason Required · string · ≤ 500 characters

The reason for the call: an update, a decision or another purpose you defined. Shown in the app, never in the lock-screen notification.

opening Optional · string · ≤ 600 characters

Strongly recommended. The complete first spoken turn: introduce the agent, project and purpose, then include the question or update the human should respond to. Speech can be prepared while the call rings. After connection, listen with an empty converse message rather than immediately speaking again.

urgency Optional

One of low, normal or high. Urgency does not bypass your quiet hours or Do not disturb.

project Optional · string · ≤ 128 characters

Strongly recommended. Name the work or project so you can identify the agent in History and route callbacks to it.

idempotency_key Optional · string · ≤ 80 characters

Reuse a key to guard against a repeated ring within the ten-minute window. A busy attempt releases the key so it can be retried.

call_id Optional · string · ≤ 32 characters

Only after a ringing result: that result’s call_id, to keep waiting on the same ring. It never rings again, and only the agent that placed the ring can rejoin it.

{"status":"connected","call_id":"1789300000000","opening_queued":true,"next":"Your opening is already queued for playback. Call converse with message: \"\" and this call_id to listen for the human’s reply. Do not repeat the opening or send another message before listening; queued does not mean heard. The one exception is an opening that was only an introduction — if it did not contain the question or update the human should answer, send that now in one short message, without repeating the introduction."}

{"status":"no_answer","delivered":1,"timedOut":true}

{"status":"no_answer","delivered":0,"declined":true}

{"status":"no_answer","delivered":-1,"timedOut":true,"voicemail":"enabled — call leave_voicemail with a short spoken-style message summarizing what you needed and what you'll do"}

{"status":"busy"}

{"status":"duplicate","note":"this idempotency_key was already used — the call was already placed"}

{"status":"silenced","reason":"quiet_hours","until":"2026-09-14T08:00:00.000Z","voicemail":true}

{"status":"silenced","reason":"dnd","until":"2026-09-14T17:30:00.000Z","voicemail":true}

{"status":"silenced","reason":"dnd","voicemail":false}

{"status":"rate_limited"}

• connected: follow next (the same field check_in and stand_by answer with). When opening_queued is true, the opening is already in the call transcript for playback; call converse with message: "" to listen. This does not prove playback or hearing. An opening that was only an introduction is the one exception: its question or update still has to be sent once. The result normally includes call_id when the call’s start timestamp is available.
• ringing: the phone is still ringing after 50 seconds. Call request_human again at once with the same reason and the returned call_id; do not start a new call. On a rejoin, call_over means the named ring is no longer live — replaced, or ended for a reason other than a miss or decline, so no voicemail is owed — and cancelled means the agent’s own cancel ended it.
• no_answer: inspect delivered, timedOut, declined and any note. A decline is an explicit refusal; do not repeat the same request.
• delivered reports push delivery: -1 is unknown, 0 means none delivered, and a positive number is the reported count. An open app can receive a ring without push. Zero alone does not diagnose missing enrollment.
• busy: another call occupies the line; wait before retrying. duplicate means the key was already claimed. rate_limited means this request did not ring. These results do not create a missed-call voicemail opportunity.
• silenced: calling availability prevented the ring. reason identifies quiet hours or Do not disturb; until can identify when it lifts: the quiet-hours end, or the end your human chose for Do not disturb (absent when it runs until they turn it off). An explicitly requested callback has its own one-use invitation; this is not an agent override.

{"name":"request_human","arguments":{"project":"research","reason":"Review the findings","opening":"This is your research assistant. The review is complete. Which finding should we discuss first?"}}

{"name":"converse","arguments":{"message":"","call_id":"1789300000000"}}

For no_answer, the enabled-voicemail hint is a string. For silenced, voicemail is a boolean. Follow the returned invitation and the voicemail requirements.

message Required · string · ≤ 2,000 characters

What to say aloud. Use an empty string to listen only.

call_id Optional · string · ≤ 32 characters

Pass the ID returned by request_human. See the named-call check below that tool.

{"transcript":"Use option B, and keep the change reversible.","interrupted":true}

{"transcript":"Send me the research summary.","interrupted":false,"ended":true}

{"event":"silence"}

{"event":"call_ended"}

{"event":"call_ended","reason":"client_gone"}

{"error":"not_your_call","note":"That call is over — the id you named is not the call that is live now. Nothing was said or ended. If you still need your human, call request_human for a new call."}

• transcript is one merged turn. Words received while the agent was thinking are prepended, and a short adaptive quiet window closes the turn.
• interrupted: true means you cut the agent’s message off. It should respond to your words instead of resuming its script. The returned transcript contains your words. History can retain the full agent message and mark an estimated interruption point.
• A transcript with ended: true keeps your last words alongside the fact that the line is down. Use those words and continue the work; do not discard them or keep asking questions through the ended call.
• listening: the turn is not complete and this call used its 50-second budget — nothing said yet, or a reply still being spoken, whose words are kept for the next call. The line is open; call converse again at once with an empty message and the same call_id, without repeating your last message. The silence timer carries over. It can carry messageSpoken: false, as a transcript can.
• silence: re-prompt once or end the call. A bare call_ended carries no new words. Already-spoken late or buffered words can still be returned, so later results are not guaranteed to be identical.
• reason: "client_gone" means the phone’s connection dropped. It does not mean you chose to hang up; the question may still be open.

The pickup hello. If the first reply is only “Hi” or “Hello,” you may have spoken while picking up, before hearing the question. The agent should ask it again.

Put farewells in end_call. A goodbye sent through converse waits for another reply and leaves the call open.

message Required · string · ≤ 600 characters

The update, written to be spoken aloud.

call_id Optional · string · ≤ 32 characters

Pass the ID returned by request_human. See the named-call check below that tool.

{"ok":true,"spoken":true}

{"ok":true,"spoken":false,"note":"no call was live, so nothing was spoken — your human did not hear this. Call request_human if you still need them."}

{"error":"not_your_call","note":"That call is over — the id you named is not the call that is live now. Nothing was said or ended. If you still need your human, call request_human for a new call."}

spoken: true means the store accepted the message for an eligible ringing or live call. It is not a device playback acknowledgement. spoken: false means the words were not spoken through an eligible call; do not assume you heard them.

closing_message Optional · string · ≤ 600 characters

A concise farewell, accepted for speech when the call is live.

call_id Optional · string · ≤ 32 characters

Pass the ID returned by request_human. See the named-call check below that tool.

{"ok":true}

{"ok":true,"spoken":true}

{"ok":true,"spoken":false,"note":"the call was already over, so your closing message was not spoken. The call is ended either way."}

{"ok":true,"ended":false,"spoken":false,"note":"not ended — your human said something you have not heard yet, so nothing was spoken and the call is still live. Call converse with message: \"\" and this call_id to hear it, respond to what they said, then call end_call again."}

{"error":"not_your_call","note":"That call is over — the id you named is not the call that is live now. Nothing was said or ended. If you still need your human, call request_human for a new call."}

ended: false means it did not hang up: you said something the agent has not heard yet. It should listen with converse, respond, then end the call. Without a nonempty closing message, the result is otherwise {"ok":true}. With one, spoken reports whether it was accepted while the call was live. A ringing or already-ended call cannot speak the farewell. Neither successful shape proves you heard it.

project Optional · string · ≤ 128 characters

Strongly recommended. Name the work or project so you can identify the agent in History and route callbacks to it.

{"pending":"none"}

{"pending":"call_requested","message":"Your human says: \"Include the latest findings\"","next":"call request_human now"}

On call_requested, call request_human and address the attached note. message appears only when the human included a note.

project Optional · string · ≤ 128 characters

Strongly recommended. Name the work or project so you can identify the agent in History and route callbacks to it.

max_wait_seconds Optional · integer · 5–240

How long to wait before returning pending: "none"; defaults to 50. Raise it only when your MCP client allows tool calls that long.

project Optional · string · ≤ 128 characters

Strongly recommended. Name the work or project so you can identify the agent in History and route callbacks to it.

message Required · string · ≤ 1,500 characters

Who the agent is, which project, what it wanted to share and what it will do meanwhile.

project Optional · string · ≤ 128 characters

Strongly recommended. Name the work or project so you can identify the agent in History and route callbacks to it.

{"ok":true,"delivered":2,"note":"voicemail saved — a notification was accepted for delivery"}

{"ok":true,"delivered":0,"note":"voicemail saved in History — no device could be notified"}

{"ok":true,"delivered":-1,"note":"voicemail saved in History — we could not tell whether any device was notified"}

{"ok":false,"error":"voicemail_disabled — your human has turned voicemail off"}

{"ok":false,"error":"rate_limited — wait a minute"}

{"ok":false,"error":"no_missed_call — leave_voicemail only follows an unanswered request_human by this agent (within 15 minutes)"}

{"ok":false,"error":"voicemail_not_saved — history is unavailable right now"}

{"ok":false,"error":"voicemail_already_left — one voicemail per missed call"}

{"ok":false,"error":"empty_message — a voicemail needs something the human can hear"}

ok: true means the message was saved in History. delivered is how many of your devices the push service accepted a notification for — 0 means none, -1 means the device lookup itself failed and we cannot say. None of those numbers prove the message was read: a saved message, an accepted notification, and listening to the message are separate events, so read the note.