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.

{"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","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.
• 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 the quiet-hours end. 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.
• 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."}

{"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."}

Without a nonempty closing message, the result is {"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.

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 not enabled voicemail"}

{"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.