MCP Tools Reference

All tools are called via the MCP protocol over SSE transport. Each tool requires authentication unless running in demo mode.

Tokens

Two token types pass over the wire — both are bearer tokens, only the

scope differs:

• teamToken (org-admin) — the workspace-wide credential returned by

and admin tools. The same value used to be called team_token,

owner_token, or ownerToken — those names are deprecated; use

teamToken.

• agentToken (per-agent runtime) — the bearer minted when a host

agent. Used for runtime tools (send-message, make-call, etc.). The

agentId parameter is auto-detected from this token.

Each tool's description starts with a [scope: ...] prefix indicating

which token tier may call it. The four scopes form a strict hierarchy

— a higher scope subsumes every lower scope:

• [scope: any] — no auth required (e.g. comms_ping). Anyone.
• [scope: agent] — agent-runtime token, org-admin token, or super-admin

channel-status, etc.

• [scope: org-admin] — org-admin token or super-admin token. Workspace

• [scope: super-admin] — super-admin token only. Cross-org / system-level

A super-admin token can call every tool. An org-admin token can call

agent and org-admin tools but not super-admin ones. An agent

token can call only agent tools (and any).

Tool name convention

Every Butt-Dial tool starts with the comms_ prefix (e.g. comms_send_message,

comms_get_channel_status). The prefix is a stable namespace, not a wart

— it de-conflicts our tools from other MCP servers an agent may have

mounted alongside ours. The prefix is intentional and will not be removed.

Naming convention

All input and output fields are camelCase (agentId, displayName,

callbackUrl, retryAfter). Some legacy snake_case keys are still

accepted on input and emitted on output for backward compatibility, but

they are marked deprecated and will be removed in a future release.

Gendered Languages

Languages like Hebrew, Arabic, French, Spanish, Portuguese, Italian, German, Russian, Polish, and Hindi conjugate verbs and adjectives by gender. For these languages:

• Client gender (agentGender) — set during provisioning (male/female/neutral). Determines how the AI refers to itself.
• Target gender (targetGender) — set per-interaction on outbound tools (male/female/unknown). Determines how the AI addresses the recipient.

For voice calls, gender conjugation instructions are automatically appended to the system prompt. For text messages, gender context is returned as metadata in the response so your AI can conjugate correctly.

Non-gendered languages (English, Chinese, Japanese, etc.) are unaffected — the gender parameters are accepted but produce no instructions.

comms_ping

Health check and connectivity test.

{
"status": "ok",
"server": "agentos-comms",
"version": "0.1.0",
"echo": "hello"
}

comms_send_message

Send SMS, email, or WhatsApp message.

{
"type": "status",
"status": "accepted",
"messageId": "uuid",
"channel": "sms",
"to": "+15559876543"
}

After sending, delivery status updates (sent, delivered, failed) are POSTed to your callbackUrl.

Compliance checks: Content filter, DNC list, TCPA time-of-day, CAN-SPAM (email).

comms_make_call

Initiate an outbound AI voice call.

{
"success": true,
"callSid": "CAxxxxxx",
"sessionId": "uuid",
"status": "queued",
"from": "+15551234567",
"to": "+15559876543"
}

comms_send_voice_message

Generate TTS audio and deliver via phone call.

comms_get_waiting_messages

Fetch messages that couldn't be delivered while your client was offline (dead letters). Fetching automatically acknowledges them — no separate step needed.

{
"success": true,
"messages": [
{
"id": 1,
"channel": "sms",
"direction": "inbound",
"from": "+15559876543",
"to": "+15551234567",
"body": "Are you there?",
"reason": "callback_failed",
"createdAt": "2026-02-22T10:00:00Z"
}
],
"count": 1
}

Dead letters are stored when: client is offline (inbound), send fails (outbound), or provider errors. Acknowledged messages are auto-purged after 7 days.

comms_transfer_call

Transfer a live voice call to a human or another client.

comms_get_group_members

List participants of a WhatsApp group. Returns phone numbers so you can DM any member directly.

{
"success": true,
"groupId": "120363XXXXX@g.us",
"participantCount": 5,
"participants": [
{ "phone": "+15551234567", "isAdmin": true, "displayName": "John" },
{ "phone": "+15559876543", "isAdmin": false, "displayName": "Jane" }
]
}

comms_call_on_behalf

Secretary call — calls someone on your behalf. An AI asks if they're available, and if yes, bridges you into the call.

comms_bridge_call

Manage call bridges — route inbound local calls to outbound local numbers via VoIP.

comms_send_otp

Send a one-time verification code via SMS, email, or WhatsApp. Code expires in 5 minutes.

comms_verify_otp

Verify a one-time code. Returns whether the code is valid.

comms_record_consent

Record that a contact has given consent to be contacted on a channel.

comms_revoke_consent

Revoke a contact's consent on a channel. No further outbound allowed.

comms_check_consent

Check whether a contact has granted consent on a channel.

comms_expand_client_pool

Resize the client pool. Admin only.

comms_provision_channels

Provision phone/SMS/WhatsApp/email/voice for a new client.

comms_deprovision_channels

Tear down all channels for a client. Releases phone number and WhatsApp pool slot.

comms_get_channel_status

Check provisioning and health status of all channels for a client.

comms_onboard_customer

*Enterprise/SaaS edition only.*

Full automated onboarding: provisions all channels, generates DNS records, returns setup package.

comms_register_provider

Register or update third-party provider credentials. Admin only.

comms_set_client_limits

Configure rate limits and spending caps. Admin only.

comms_get_usage_dashboard

Usage statistics, costs, and rate limits per client.

comms_get_billing_summary

*Enterprise/SaaS edition only.*

Billing summary with provider costs, markup, and billed costs.

comms_set_billing_config

*Enterprise/SaaS edition only.*

Set billing tier, markup, and billing email. Admin only.

comms_whatsapp_action

WhatsApp-specific actions (13): send_location, send_contact, typing, mark_read, react, edit, delete, forward, send_poll, send_buttons, post_status, set_chat_ttl, send_view_once.

comms_create_session / comms_get_session / comms_list_sessions / comms_close_session

Session management — isolated communication tunnels. Auto-created on inbound messages.

comms_find_agent / comms_message_agent

Agent-to-Agent directory and messaging within your team.

The system agent

Every org has one indelible Butt-Dial System agent (is_system=1).

• Purpose: outbound system messages (verification emails, billing

delete or reassign it.

• Where you'll see it: comms_find_agent returns it alongside the

excludes it (we count user-registered agents only).

• Channels: seeded with an email_address for outbound delivery.

• Authorship: ID format is the same UUID as any agent; recipients

You cannot register a new agent named "Butt-Dial System" — the name is

reserved per-org. You also cannot deregister the system agent —

attempts return code: SYSTEM_AGENT_PROTECTED.

comms_rotate_token

Rotate your security token. 30-second grace period to reconnect.

comms_update_profile

Update name, greeting, system prompt, voice, language, or gender.

comms_manage_inbound_filter

Add/list/delete keyword or contact-based filters for inbound messages.

Voice Services

Butt-Dial provides 5 voice modes — all work across any voice-capable provider (phone, WhatsApp, LINE, Viber, Telegram):

Voice Notes: Add voiceNote: true to comms_send_message. Smart voice selection: pass a voice ID or description like "warm female narrator". 16 languages auto-detected.

Cross-Channel OTP

Verify identity across channels: comms_send_otp, comms_verify_otp, comms_check_trust. Unknown caller on voice → OTP via SMS → verified.