Read looks, never changes anything
·
Write creates or updates a record
·
Sensitive spends money or mints
a shareable link ·
Destructive removes access or
data
start_ai_voice_agent_call places a real phone call and debits Ringee credits
when usage settles. reveal_lead uses the allowance of the connected
enrichment provider instead; search_leads does not spend credits.Conventions
- Phone numbers are E.164:
+14155552671. - Dates and times are ISO-8601 with a timezone offset:
2026-05-23T14:30:00-04:00. - Ids are UUIDs returned by other tools. Never invent one.
- Paginated tools accept
page(1-based, default1) andlimit(default10, max50).
Workspaces
list_workspaces
Lists the personal account plus every organization the user belongs to, and flags the active one.
Takes no parameters.
switch_workspace
Changes the active workspace for every subsequent action. No re-authentication needed.
string
required
personal for the user’s own account, or an organization id from
list_workspaces. An exact organization name also works.Contacts
search_contacts
Searches the directory by name, phone, email, company, job title, state, website, revenue or company size. Returns id, name, phone, email and lastCallAt.
string
required
Search text. Pass
* to list all contacts, paginated.number
1-based page number.
number
Page size, max 50.
contactId before any tool that needs one.
get_contact
Fetches one contact in full, including recent calls, notes, meetings and tags.
string (uuid)
required
The contact to fetch.
find_contacts_by_outcome
Finds contacts whose calls reached given outcomes — who converted, showed interest or booked a meeting. Useful for deriving a real ICP from closed business.
string[]
required
One or more of
meeting_booked, sale, interested, follow_up,
callback_scheduled, not_interested, no_answer, voicemail,
wrong_number, gatekeeper.string
any (default) matches a contact with any call in those outcomes. last
considers only the most recent call.boolean
Include contacts flagged
doNotCall or unsubscribed. Defaults to false.number
1-based page number.
number
Page size, max 50.
lastOutcome and lastCallAt.
create_contact
string
required
E.164. Must be unique within the workspace — the tool fails fast on a
duplicate.
string
Display name.
string
Given name.
string
Family name.
string
Primary email.
string
Role at the company.
string
Company name.
string
State or region.
string
Company website.
string
Company revenue or range.
string
Headcount band.
string
Lead source label. Defaults to
mcp.string
Initial note.
string[]
Tag UUIDs to assign.
update_contact
Patches an existing contact. Only the fields you send change.
string (uuid)
required
The contact to update.
string[]
Replaces the contact’s tag set. Omit it to leave tags untouched.
create_contact. Ownership is verified before writing.
delete_contact
Destructive
Soft-deletes a contact by setting deletedAt.
string (uuid)
required
The contact to delete.
boolean
required
Must be the literal
true.string
required
Must exactly match the contact’s stored phone number in E.164.
Calls and follow-ups
list_calls
Returns calls in full detail: direction, status, timing, duration, logged outcome and note, plus the transcription and recording URL when present. Newest first. Cost and low-level telephony fields are intentionally excluded.
string (uuid)
Filter to one contact’s calls.
string[]
Only calls with one of these outcomes.
string[]
Only calls in these states:
pending, ringing, answered, recording,
completed, failed.string (ISO-8601)
Only calls created at or after this.
string (ISO-8601)
Only calls created at or before this.
number
1-based page number.
number
Page size, max 50.
log_call_outcome
Records how a past call went.
string (uuid)
required
An existing call belonging to the active workspace.
string
required
One of the
CallOutcome values listed under find_contacts_by_outcome.string
Free-text note.
create_callback
Schedules a reminder to call a contact back. Creates a callback task and a reminder.
string (uuid)
required
Who to call back.
string (ISO-8601)
required
Future datetime with offset.
string (uuid)
Originating call.
string
Free-text note.
schedule_meeting
Books a meeting. When the user has a Google or Microsoft calendar connected, the event is synced and a Meet or Teams link is generated.
string (uuid)
required
Who the meeting is with.
string (ISO-8601)
required
Start time with offset.
string
Meeting title.
number
Minutes. Defaults to 30.
string
Address or video URL.
string
Notes.
string
Sends a calendar invite to this address.
string
Calendar to sync with.
string (uuid)
Originating call.
This tool reaches an external system (calendar sync and email invites), so it
is flagged
openWorldHint.Call sessions
A call session is a queue of contacts plus a magic link that lets someone dial through them one by one — without logging in.create_call_session
Sensitive
object[]
required
Ordered queue, 1 to 500 entries. Each accepts
contactId and/or phoneNumber
(E.164, required when contactId is absent), plus optional name, company,
jobTitle, state, website, revenue, companySize. Provide contactId
when you have it — name and phone are then looked up server-side.string
Session title, visible to the magic-link recipient.
string (uuid)
Attribute calls to a campaign.
number
Link lifetime. Defaults to 60 minutes, max 30 days.
number
Auto-complete the session after N calls, max 500.
object
Free-form JSON persisted with the session; not exposed to the magic-link UI.
get_call_session
Returns safe metadata — status, contact count, calls completed, expiry, and whether a token is still active. It never exposes the raw magic link.
string (uuid)
required
The session to inspect.
update_call_session
string (uuid)
required
The session to update.
string
New title.
string (uuid) | null
Set a campaign, or
null to detach.number
Extend validity.
object[]
Replaces the queue. Only allowed before the first call has started.
object
Replace metadata.
delete_call_session
Destructive
Revokes the session. Past calls are preserved, but every active magic link stops working immediately.
string (uuid)
required
The session to revoke.
Lead prospecting
These tools use the workspace’s connected enrichment provider. Apollo is preferred when both are connected.search_leads
Searches for candidates. Results are not contacts yet.
string
apollo or prospeo. Auto-selected when omitted.string
Free-text keywords.
string[]
Job titles to include.
string[]
Job titles to exclude.
string[]
Seniority levels.
string[]
Departments.
string[]
Countries.
string[]
Cities.
string[]
Industries.
string[]
Company names.
string[]
Company domains.
string[]
Headcount bands.
string[]
Technologies in use.
boolean
Only candidates with an email.
boolean
Only candidates with a phone.
boolean
Only verified emails.
number
Page number.
number
Results per page, max 25.
jobId plus candidates with externalId, person and company summaries, and whether emails and phones are available. Pass the jobId to the two tools below.
reveal_lead
Sensitive
Spends provider credits
Reveals a candidate’s email — and optionally a mobile phone — and upserts a Ringee contact so the lead is immediately callable.
string (uuid)
required
From
search_leads.string
required
The candidate to reveal.
boolean
Also reveal a mobile phone. Costs extra provider credits.
import_leads_as_contacts
Bulk-imports candidates from a search job as Ringee contacts, deduplicated by phone number. Does not reveal hidden emails or phones — use reveal_lead first if you need those.
string (uuid)
required
From
search_leads.string[]
required
Candidates to import.
string[]
Tags to assign to every imported contact.
Campaigns
Campaign tools require an organization workspace. Organization members can read campaigns they are assigned to. Status changes and lead mutations require an organization admin.list_campaigns
Lists campaign ids, names, statuses and lead counts.
string
Filter name and description.
string
draft, active, paused or completed.number
1-based page number.
number
Page size, max 50.
get_campaign
Returns one campaign’s status, dialer mode, working hours, timezone, retry limits, wrap-up settings and lead count.
string (uuid)
required
Resolve with
list_campaigns.update_campaign_status
Changes a campaign’s lifecycle state. Allowed transitions are draft → active, active → paused|completed and paused → active|completed. completed is terminal.
string (uuid)
required
The campaign to change.
string
required
The new lifecycle state.
list_campaign_leads
Returns each CampaignLead id, status, attempts, last and next call time, and the linked contact.
string (uuid)
required
The campaign to inspect.
string
pending, queued, locked, dialing, in_call, wrap_up,
dispositioned, scheduled, completed, exhausted, dnc, or the
aggregate aliases called and dead.number
1-based page number.
number
Page size, max 50.
add_campaign_leads
Adds 1 to 200 leads. Ringee creates or reuses contacts by phone number and skips contacts already in the campaign.
string (uuid)
required
The target campaign.
object[]
required
Each entry requires
name and E.164 phone. Optional fields are email,
company, jobTitle, state, website, revenue and companySize.delete_campaign_lead
Destructive
Removes one lead from a campaign. Its campaign attempts and callbacks are deleted; the Contact and its general call history remain. A lead currently locked, dialing, in a call or wrapping up cannot be removed.
string (uuid)
required
The campaign.
string (uuid)
required
The CampaignLead id from
list_campaign_leads, not the contact id.boolean
required
Must be literal
true after explicit user approval.get_campaign_analytics
Returns attempts, connects, conversions, contact and conversion rates, average handle time, leads by status and disposition distribution.
string (uuid)
required
The campaign.
string (ISO-8601)
Window start. Pair with
endDate.string (ISO-8601)
Window end. Pair with
startDate.boolean
Include per-agent performance. Defaults to
true.boolean
Include the hourly histogram. Defaults to
false.Analytics and activity
get_call_analytics
Returns the numbers behind the dashboard overview: call volume, answer rate, outcomes, conversions, meetings, average duration and an outcome funnel.
string
today, yesterday, 7d, 30d, this_month or last_month.string (ISO-8601)
Custom start. Pair with
to.string (ISO-8601)
Custom end. Pair with
from.string
Campaign UUID, or literal
none for calls outside every campaign.string
Restrict every metric to one call outcome.
string
personal or organization.string (uuid)
Narrow organization results to one member; admin only.
string[]
Any of
kpis, funnel, by-outcome, over-time, best-time-of-day,
agents. Defaults to the first three.get_day_activity
Returns calls, callbacks and meetings for one calendar day.
string
required
Calendar date as
YYYY-MM-DD.string
Offset such as
-04:00. Defaults to UTC.string
Campaign UUID, or
none for calls outside campaigns.string[]
Only calls with these outcomes.
boolean
Defaults to
true.boolean
Defaults to
true.number
Maximum calls, default 50 and max 100.
list_callbacks
Lists callbacks soonest first, including their contact and originating campaign.
string
scheduled, due, in_progress, completed, missed or cancelled.number
1-based page number.
number
Page size, max 50.
Do Not Call
list_dnc
Lists suppressed numbers with their reason, source and creation time.
string
Phone-number fragment.
number
1-based page number.
number
Page size, max 50.
add_to_dnc
Suppresses one or more numbers. Every future dial to them from this workspace is blocked. Existing entries are reported as duplicates.
string[]
required
1 to 500 E.164 numbers.
string
Why they were suppressed, max 500 characters.
remove_from_dnc
Destructive
Releases a number so it becomes callable again.
string
required
E.164 number verified with
list_dnc.boolean
required
Must be literal
true after the user explicitly requests removal.AI pipelines
These read-only tools expose pipeline state and results. They require an organization admin, except a valid personal context for a freelancer.list_ai_pipelines
Lists follow_up_recommendations, script_optimization and objection_intelligence, including enabled contexts, pending actions and newly eligible calls. Takes no parameters.
get_ai_pipeline_results
string
required
Pipeline type returned by
list_ai_pipelines.string
required
campaign, organization_outside_campaign or personal.string (uuid)
Required for a campaign context.
string
pending, completed, dismissed or snoozed. Defaults to pending.AI Voice Agents
These tools require an organization workspace. See the focused AI Voice Agents MCP guide for the complete flow.list_ai_voice_agents
Lists agents, caller numbers and accepted variables by type.
number
Defaults to 20, max 100.
start_ai_voice_agent_call
Sensitive
Real billed call
Starts a server-originated AI conversation and returns immediately with a call id.
string (uuid)
required
Resolve with
list_ai_voice_agents.string
required
E.164 destination.
string (uuid)
Eligible caller number when no default can be resolved.
object
String values accepted by the agent type.
object
Free-form values echoed in the result.
get_ai_voice_agent_call
Returns status, outcome, summary, sentiment, extracted data and metadata for one AI voice agent call.
string (uuid)
required
From
start_ai_voice_agent_call.Placing calls
Human-operated Ringee calls are placed in the user’s browser or mobile app over WebRTC. There is no MCP tool that remotely presses the human dialer. Usecreate_call_session and share the joinUrl when a person should dial. Use start_ai_voice_agent_call only when the user explicitly wants a configured AI Voice Agent to place and conduct the call.
Next steps
Workspaces
How personal and organization scoping works
Safety
Confirmation rules for sensitive actions