To let an assistant use these tools, grant AI agents on the consent screen, or just
Conversations & inbox under its Fine-tune. The scope is conversations.
Read tools work with Read only or Read & write access; write tools only with
Read & write.
Your assistant doesn't see these tools straight away. It finds them with search_tools or
describe_tools, and runs one with use_tool, passing its name and
arguments. Most assistants do this for you: just ask for what you want.
What your assistant is told about this group
Day-to-day customer conversations. search_everything finds any person, conversation, message, escalation, booking or insurance record by name, reference or words, newest first. The inbox: to reply yourself, take the conversation over from the agent (takeover_conversation), send your message (send_conversation_message), then hand it back (release_conversation); conversations can also be closed, reopened or marked as spam. Escalations: assign, comment, resolve and set priority. Also scheduled follow-ups, contacts, the messages sent, and insights on conversations and where business comes from. send_conversation_message and create_follow_up reach REAL CUSTOMERS: always confirm the wording and timing with the user first.
The descriptions below are the ones your assistant reads, so they're written for it. When a connection covers more than one
organisation, the assistant passes org (the organisation's slug, from list_orgs) to say which one.
search_everything
Read Search everything
Searches the org's records for a name, email, phone, reference or words, newest first: people (contacts and leads), conversations, messages, escalations, bookings, lead tasks and notes, and with the insurance engine, customers, applications, quotes, policies and claims. At least 2 characters (3 for message text). Narrow with types; page older results of one type with before (the last result's at).
Arguments
| Field | Type | Description |
|---|---|---|
| query required | string | |
| types | array of string | |
| limit | integer | |
| before | string (date-time) | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_conversations
Read List conversations
The inbox: customer conversations across every channel. Filters mirror the dashboard (status, channel, direction, agent, who is handling it, spam, outcome quoted/bound; sort recent_activity by default).
Arguments
| Field | Type | Description |
|---|---|---|
| agent_id | string | |
| status | string | active (default), escalated, closed, waiting_for_approval or all |
| channel | string |
One of: "web", "sms", "whatsapp", "internal", "email", "voice", "chatgpt", "claude", "webmcp", "a2a", "mcp"
|
| spam | boolean | |
| outcome | string |
One of: "quoted", "bound"
|
| direction | string |
inbound: the customer started it, or has replied to one we started (an outreach message, say); outbound: we started it and they haven't replied yet
One of: "inbound", "outbound"
|
| handler | string |
ai: the agent is answering; human: a person has taken over
One of: "ai", "human"
|
| sort | string |
One of: "newest", "oldest", "recent_activity", "latest_activity", "most_messages", "status"
|
| limit | integer | Max rows (1-100, default 30) |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_conversation
Read Get a conversation
One conversation with its transcript (does NOT mark it read: use mark_conversation_read).
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| message_limit | integer | 1-500, default 100 |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
takeover_conversation
Write Take over a conversation
Put the conversation into human hands: the agent stops replying and the visitor is told an operator joined. The taking-over user is the authorizing user of this connection.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
release_conversation
Write Release a conversation
Hand the conversation back to the agent (only the current handler can release).
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
send_conversation_message
Write Send an operator message
Reply to the customer as the human operator (requires takeover first). Optionally share a library item by id or default:<key>. This message goes to a real customer: confirm the wording with the operator first.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| content | string | |
| library_item_id | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
mark_conversation_read
Write Mark read
Mark a conversation read for the inbox.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
mark_conversation_unread
Write Mark unread
Flag a conversation unread so it surfaces in the inbox again.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
set_conversation_spam
Write Mark spam / not spam
Flag or unflag a conversation as spam.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| spam required | boolean | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
set_conversation_star
Write Star / unstar a conversation
Star a conversation for the whole team, or take the star off. The inbox can show just the starred ones.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| starred required | boolean | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
close_conversation
Write Close a conversation
Close a conversation (reopenable).
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
start_conversation_over
Write Start a conversation over
Start a text, WhatsApp or email conversation over: it closes, and the person's next message opens a new conversation the agent greets fresh, without remembering this one. Their contact record, consent and care notes stay. Confirm first.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
bulk_start_conversations_over
Write Start several conversations over
Starts up to 200 inbox conversations over, as start_conversation_over does one: each closes, and the person's next message opens a new conversation the agent doesn't remember this one in. Web chats and ones already started over are skipped. Returns how many started over. Confirm first.
Arguments
| Field | Type | Description |
|---|---|---|
| ids required | array of string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
reopen_conversation
Write Reopen a conversation
Reopen a closed conversation.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
bulk_close_conversations
Write Close several conversations
Closes up to 200 inbox conversations at once (already-closed ones are skipped). Returns how many closed.
Arguments
| Field | Type | Description |
|---|---|---|
| ids required | array of string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
bulk_reopen_conversations
Write Reopen several conversations
Reopens up to 200 closed inbox conversations at once. Returns how many reopened.
Arguments
| Field | Type | Description |
|---|---|---|
| ids required | array of string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
bulk_mark_conversations_read
Write Mark several conversations read
Marks up to 200 inbox conversations read at once (read ones are skipped). Returns how many were marked.
Arguments
| Field | Type | Description |
|---|---|---|
| ids required | array of string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
bulk_mark_conversations_unread
Write Mark several conversations unread
Marks up to 200 inbox conversations unread at once (unread ones are skipped). Returns how many were marked.
Arguments
| Field | Type | Description |
|---|---|---|
| ids required | array of string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
bulk_star_conversations
Write Star / unstar several conversations
Stars (or, with starred false, unstars) up to 200 inbox conversations at once, for the whole team. Returns how many changed.
Arguments
| Field | Type | Description |
|---|---|---|
| ids required | array of string | |
| starred required | boolean | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
bulk_mark_conversations_spam
Write Mark several conversations spam
Flags up to 200 inbox conversations as spam at once (ones already flagged are skipped). Returns how many were flagged.
Arguments
| Field | Type | Description |
|---|---|---|
| ids required | array of string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
assign_conversation
Write Assign a conversation
Make an org member responsible for a conversation (omit user_id to unassign). Ownership only: the agent keeps replying. The assignee is notified unless it's you.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| user_id | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
bulk_assign_conversations
Write Assign several conversations
Assigns up to 200 inbox conversations to an org member at once (omit user_id to unassign them). Returns how many changed.
Arguments
| Field | Type | Description |
|---|---|---|
| ids required | array of string | |
| user_id | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
escalate_conversation
Write Escalate a conversation
Raise (or promote) the conversation's escalation for human attention.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| reason | string | |
| priority | string |
One of: "low", "normal", "high", "urgent"
|
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_escalations
Read List escalations
Escalations needing human attention (unresolved by default).
Arguments
| Field | Type | Description |
|---|---|---|
| status | string | unresolved (default), resolved, all, open or assigned |
| priority | string |
One of: "low", "normal", "high", "urgent"
|
| assigned_to_user_id | string | |
| unassigned | boolean | Only escalations nobody has picked up |
| agent_id | string | Only escalations from this agent's conversations |
| channel | string |
One of: "web", "sms", "whatsapp", "internal", "email", "voice", "chatgpt", "claude", "webmcp", "a2a", "mcp"
|
| limit | integer | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_escalation
Read Get an escalation
One escalation with its comment thread.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
assign_escalation
Write Assign an escalation
Assign an escalation to an org member (omit user_id to unassign).
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| user_id | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
set_escalation_star
Write Star / unstar an escalation
Star an escalation for the whole team, or take the star off. Starred escalations head the list.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| starred required | boolean | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
bulk_assign_escalations
Write Assign several escalations
Assigns up to 200 escalations to an org member at once (omit user_id to unassign them). Returns how many changed.
Arguments
| Field | Type | Description |
|---|---|---|
| ids required | array of string | |
| user_id | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
bulk_star_escalations
Write Star / unstar several escalations
Stars (or, with starred false, unstars) up to 200 escalations at once, for the whole team. Returns how many changed.
Arguments
| Field | Type | Description |
|---|---|---|
| ids required | array of string | |
| starred required | boolean | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
bulk_resolve_escalations
Write Resolve several escalations
Resolves up to 200 escalations at once, with the same optional note on each (resolved ones are skipped). Returns how many were resolved.
Arguments
| Field | Type | Description |
|---|---|---|
| ids required | array of string | |
| note | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
resolve_escalation
Write Resolve an escalation
Mark an escalation resolved with an optional note.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| note | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
comment_on_escalation
Write Comment on an escalation
Add a comment to the escalation's thread.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| body required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
update_escalation_priority
Write Change escalation priority
Change priority with a required justification note.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| priority required | string |
One of: "low", "normal", "high", "urgent"
|
| note required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_follow_ups
Read List scheduled follow-ups
Customer follow-ups ("call me back tomorrow"), newest due first.
Arguments
| Field | Type | Description |
|---|---|---|
| status | string |
One of: "pending", "completed", "cancelled", "failed", "missed"
|
| limit | integer | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
create_follow_up
Write Schedule a follow-up
Book a call or message follow-up on a conversation. One pending per conversation; must be in the future, within 30 days and outside the org's quiet hours; call/message channel requirements apply. Contacts a real customer when it fires: confirm with the operator first.
Arguments
| Field | Type | Description |
|---|---|---|
| conversation_id required | string | |
| topic required | string | |
| due_at required | string | ISO8601 datetime |
| follow_up_method | string |
Default call
One of: "call", "message"
|
| phone | string | Overrides the contact's number |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
reschedule_follow_up
Write Reschedule a follow-up
Move a pending follow-up to a new time (same horizon/quiet-hours rules).
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| due_at required | string | ISO8601 datetime |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
cancel_follow_up
Write Cancel a follow-up
Cancel a pending follow-up.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_insights_overview
Read Get the insights overview
The headline for a window against the one before it, as on Insights > Overview: visits (entries), leads (contact details captured), the goal's conversions (gross) and value (counted from every source: this platform, the CRM, uploads, stage moves), cancelled (of those, cancelled since; null when the goal can't be cancelled), spend (ad spend, lead prices, clawbacks, campaign costs) and profit (revenue measures less that spend); the engagement ladder; the top 5 sources and campaigns; and what wants a look (the review queue, campaigns losing money, contested agent writes, open leads with nobody on them or gone quiet). Money in pence. period: today, week, month (so far), last7, last30 (default), last90, last_month, or custom with from/to (YYYY-MM-DD).
Arguments
| Field | Type | Description |
|---|---|---|
| period | string |
One of: "today", "week", "month", "last7", "last30", "last90", "last_month", "custom"
|
| from | string | |
| to | string | |
| goal | string | A goal key (get_outcome_model); the org's default when omitted. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_unsubscribe_report
Read Get the unsubscribe report
Who said no, and through what, as on Insights > Unsubscribes: opt-outs (an unsubscribe link followed, a spam complaint, a STOP reply) against messages sent, for a window against the one before it. Each opt-out is put down to the message it came through; untraced are the ones no message could be (an old link, a STOP long after the last text). rate is opt-outs per 100 sent. By day, channel, outreach stream and message (an outreach step or issue, or a kind of send outside a stream), plus the latest opt-outs. channel and stream_id narrow every figure. period: today, week, month (so far), last7, last30 (default), last90, last_month, or custom with from/to (YYYY-MM-DD).
Arguments
| Field | Type | Description |
|---|---|---|
| period | string |
One of: "today", "week", "month", "last7", "last30", "last90", "last_month", "custom"
|
| from | string | |
| to | string | |
| channel | string |
One of: "email", "sms", "whatsapp"
|
| stream_id | string | An outreach stream id, from list_outreach_streams. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_conversation_analytics
Read Get conversation analytics
How the agents' conversations went in a window against the one before it, as on Insights > Conversations: volume by day and channel; the commercial funnel (applications, quotes, binds, premium; conversion rates are a cohort: of the conversations started in the window, how many reached each stage); operations (containment, takeovers, response and quote times); compliance (escalations, guardrail triggers, denials, spam); sentiment and vulnerability; bookings; channel health (opt-outs, bounces, complaints, failed deliveries); top intents, emotions and abandonment reasons; and each agent version's cohort. Rates are fractions (0.25 = 25%), money in pence, times in seconds. period: today, week, month (so far), last7, last30 (default), last90, last_month, or custom with from/to (YYYY-MM-DD). channel or agent_version_id narrow it.
Arguments
| Field | Type | Description |
|---|---|---|
| period | string |
One of: "today", "week", "month", "last7", "last30", "last90", "last_month", "custom"
|
| from | string | |
| to | string | |
| channel | string |
One of: "web", "sms", "whatsapp", "internal", "email", "voice", "chatgpt", "claude", "webmcp", "a2a", "mcp"
|
| agent_version_id | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_source_analytics
Read Get source analytics
Where the org's business comes from. For one provenance dimension (source_group: Google Ads, Google search, Meta ads, Facebook / Instagram, AI assistants, referral, direct...; or utm_source, utm_medium, utm_campaign, referrer_host, host (website), landing_page, device_type, browser, os, surface, channel, framed_on, click_id) returns per value: entries (visits that started a conversation or application) and the engagement ladder: engaged (first message or form answer), conversing (3+), leads (contact details captured), bookings, quotes, sales, each rung's rate of entries (stage_rates), the chosen goal's conversions, rate and value (goal_value, value_per_conversion, goal_measures: every measure its outcomes carry plus the org's derived measures, stored as pence, basis points or counts: goal.measures gives each unit), average premium (pence/month), days to sale, ad spend with cost per entry and per conversion, and share, with totals against the prior window and a daily timeline by source group. Conversions are gross; when the goal's outcome can be cancelled (a sale), cancelled is how many were cancelled since and still_on_book_rate the share that weren't. attribution: session (the visit it started on, default) or first_touch (the contact's first ever visit). period: today, week, month (so far), last7, last30, last90, last_month (last30 by default), or custom with from/to (YYYY-MM-DD).
Arguments
| Field | Type | Description |
|---|---|---|
| dimension | string |
One of: "source_group", "utm_source", "utm_medium", "utm_campaign", "referrer_host", "host", "landing_page", "device_type", "browser", "os", "surface", "channel", "framed_on", "click_id"
|
| attribution | string |
One of: "session", "first_touch"
|
| goal | string | A conversion goal key (get_outcome_model); the org's default goal when omitted. Its outcomes count as conversions, from any source. |
| period | string |
One of: "today", "week", "month", "last7", "last30", "last90", "last_month", "custom"
|
| from | string | |
| to | string | |
| filters | object | Narrow to entries matching every { dimension: value } given (up to 5; "(none)" = no value). |
| limit | integer | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_source_analytics_records
Read List source analytics records
The conversations and applications behind one number on the source analytics report: entries whose dimension (see get_source_analytics) has `value` ("(none)" for no value) and whose metric (entries, conversations, engaged, conversing, leads, applications, quotes, accepted, sales, payments, bookings, escalations) happened in the window. Newest first, up to 200.
Arguments
| Field | Type | Description |
|---|---|---|
| dimension required | string |
One of: "source_group", "utm_source", "utm_medium", "utm_campaign", "referrer_host", "host", "landing_page", "device_type", "browser", "os", "surface", "channel", "framed_on", "click_id"
|
| value required | string | |
| metric | string |
One of: "entries", "conversations", "engaged", "conversing", "leads", "applications", "quotes", "accepted", "sales", "payments", "bookings", "escalations"
|
| attribution | string |
One of: "session", "first_touch"
|
| period | string |
One of: "today", "week", "month", "last7", "last30", "last90", "last_month", "custom"
|
| from | string | |
| to | string | |
| filters | object | Narrow to entries matching every { dimension: value } given (up to 5; "(none)" = no value). |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_contacts
Read List contacts
The org's customer contacts, with the same filters as the dashboard Contacts table. channel narrows by identifier type (sms/whatsapp = has phone, email = has email, web = anonymous visitor id only). consent/unsubscribed take any, none or a channel. period is a date preset, or custom with from/to (YYYY-MM-DD), applied to date_field (default created).
Arguments
| Field | Type | Description |
|---|---|---|
| query | string | Matches name, email, phone or visitor id. |
| channel | string |
One of: "web", "sms", "whatsapp", "email"
|
| consent | string | any, none, or a channel (email, sms, whatsapp, phone, post). |
| unsubscribed | string | any, none, or a channel. |
| status | string |
One of: "active", "blocked", "vulnerable", "erased"
|
| tps | string |
One of: "clear", "registered", "not_applicable", "unchecked"
|
| email_status | string |
bounced (any reason), hard, soft (repeated soft bounces), complaint (marked as spam), or deliverable (an email address that hasn't bounced).
One of: "bounced", "hard", "soft", "complaint", "deliverable"
|
| date_field | string |
One of: "created", "last_inbound", "last_outbound"
|
| period | string |
One of: "today", "yesterday", "week", "last_week", "last7", "month", "last_month", "last30", "last90", "custom"
|
| from | string | |
| to | string | |
| sort | string |
One of: "newest", "oldest", "last_active", "least_active", "name_asc", "name_desc", "most_conversations", "fewest_conversations"
|
| limit | integer | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_contact
Read Get a contact
One contact with recent conversations, their consent (per purpose and channel) and its history.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_sent_messages
Read List sent messages
What actually went out to customers, exactly as it left, newest first: to one contact, in one conversation, or across the org. Each names the template versions it was built from (template_refs; see get_template_version).
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id | string | |
| conversation_id | string | |
| channel | string | email, sms, whatsapp, ... |
| limit | integer | 1 to 200, default 50 |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_sent_message
Read Get a sent message
One sent message exactly as the customer received it: the delivered text, an email's rendered HTML, an out-of-window WhatsApp's approved template, and the template versions it was built from.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
set_contact_blocked
Write Block/unblock a contact
Block a contact from reaching the org's agents (or unblock). Confirm with the operator first.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| blocked required | boolean | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |