Tools reference

device_status#

No input. Battery, charging state, network, signal, how long the socket has been up, queued events, whether the app is paused, and a one-line summary of the policy in force.

returns

{battery_pct, charging, network: "wifi"|"cellular"|"none", signal_bars, connected_since, pending_events, paused, policy_summary}

wait_for_events#

Blocks until at least one event is queued or the timeout elapses, then returns and acknowledges the events it returned. Call it in a loop to react to incoming texts and calls. The relay allows this call the timeout plus fifteen seconds before it reports device_timeout.

input

{timeout_s: int (1–600, default 300)}

returns

{events: [...], timed_out: bool}

events_recent#

Non-blocking read of recent events, acknowledged or not.

input

{since?: RFC3339, limit: int (default 50)}

sms_send policy#

Queues a text. Bodies up to 1600 characters are split into parts automatically. The result says queued; a later sms_sent and, where the carrier reports it, sms_delivered event carries the outcome. May return denied or confirmation_timeout under policy.

input

{to: string, body: string}

returns

{id, parts, status: "queued"}

sms_list#

Newest first across all conversations.

input

{limit: int (default 20, max 200), since?: RFC3339, address?: string}

returns

{messages: [{id, ts, address, direction: "in"|"out", body, thread_id, read}]}

sms_thread#

The conversation with one number, oldest first within the window.

input

{address: string, limit: int (default 30)}

sms_search#

Case-insensitive substring match over body and address.

input

{query: string, limit: int (default 20)}

contacts_search#

Matches display name or phone number.

input

{query: string, limit: int (default 10)}

returns

{contacts: [{name, numbers: [{number, label}]}]}

contacts_add always confirms#

Creates a contact stored on the phone, with no account sync. Duplicate numbers in the input are collapsed and the result has them normalised to E.164 where possible. The owner must approve every call on the phone; there is no allow mode, and a denylisted number is refused outright. A number first seen through this tool does not count as “in contacts” for sends or dials until the owner has approved one send or dial to it on the phone, so Claude cannot launder an unknown number into an allowed one.

input

{name: string (1–100), numbers: [{number, label?: "mobile"|"home"|"work"|"other"}] (1–5), email?: string (≤200), note?: string (≤500)}

returns

{id, name, numbers: [{number, label}]}

errors

denied: <reason>, confirmation_timeout, permission_missing: WRITE_CONTACTS, invalid_argument: <detail>

call_dial policy#

Places a call through the default dialer. Claude manages the call; it cannot hear or speak on it.

input

{number: string}

returns

{status: "dialing"}

call_answer#

No input. Answers the ringing call. Error no_ringing_call if nothing is ringing.

call_reject#

No input. Rejects the ringing call.

call_hangup#

No input. Ends the active or dialing call. Error no_active_call if there is none.

call_state#

No input.

returns

{state: "idle"|"ringing"|"offhook", number?, contact?, since?, duration_s?}

call_log#

input

{limit: int (default 20, max 200), since?: RFC3339}

returns

{calls: [{ts, number, contact?, type: "incoming"|"outgoing"|"missed"|"rejected", duration_s}]}