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"
|
| 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) |
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) |
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) |
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"
|
| 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) |
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_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"
|
| 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"
|
| 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) |