Copy page

Tools

MCP Tools Reference

46 hand-crafted tools covering every agentic workflow on Neuratel. Each tool is built around what an AI assistant actually needs to accomplish — not around HTTP endpoints.

Tools marked ⚠️ place real calls, modify live routing, or incur costs. Your AI assistant is shown these warnings and will ask for confirmation before proceeding.

---

Agents

create_agent

Create a voice AI agent. Only name and instructions are required — all provider defaults are applied server-side (Groq brain, Cartesia voice, OpenAI transcriber).

Parameter	Type	Required	Notes
name	string	Yes	—
instructions	string	Yes	The agent's system prompt
brain_provider	string	No	groq, openai, phantom
brain_model	string	No	See Brain providers
temperature	float	No	0.0–2.0
max_tokens	int	No	Max completion tokens
voice_provider	string	No	cartesia, elevenlabs, phantom
voice_id	string	No	Provider voice ID
voice_model	string	No	e.g. sonic-3, eleven_flash_v2_5
voice_speed	float	No	Speaking speed
transcriber_provider	string	No	deepgram, openai, soniox, phantom
transcriber_model	string	No	See Transcriber providers
language	string	No	BCP-47 / ISO code
first_message	string	No	What the agent says first
first_message_delay_ms	int	No	Delay before first message
interruption_enabled	boolean	No	Allow caller to interrupt
max_call_duration	int	No	Max seconds (default 1800)
description	string	No	—
tags	string[]	No	—
config	object	No	Full config — see Advanced config

Returns: id, name, status, brain, voice, language, created_at

⚠️ Creates a billable resource.

Brain providers

Provider	Models
phantom (default)	phantom (default)
groq	meta-llama/llama-4-scout-17b-16e-instruct, llama-3.1-8b-instant, openai/gpt-oss-20b
openai	gpt-5.4, gpt-5.4-mini, gpt-5.4-nano, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano

Voice providers

Provider	Models	Notes
cartesia (default)	sonic-3	voice_id required
elevenlabs	eleven_flash_v2_5	voice_id required
phantom	phantom-english-speech-preview, phantom-arabic-speech-preview	Use config.voice.voice for voice name

Phantom English voices: aria, bella, claire, alex, david, marcus Phantom Arabic voices: omar, tariq, layla, nour

Transcriber providers

Provider	Models	Notes
soniox (default)	stt-rt-v4 (default)	Multilingual + semantic EOU built in. Default language_hints: ["en", "ar"]. When selected, the worker auto-routes turn_detection.mode to "stt".
deepgram	nova-3, nova-3-medical	Telephony-tuned English; lowest latency for English-only calls
openai	gpt-4o-mini-transcribe	GPT-4o transcription
phantom	phantom-stt-v1	Neuratel native

Advanced config

Use the config dict to set any field the agent studio form supports — same shape as get_agent returns. The REST API accepts these sections as top-level fields alongside name; the MCP tool wraps them in config for clarity. Named params always override the corresponding section in config.

Code
config={
    "turn_detection": {
        "mode": "semantic_vad",   # or "vad"
        "min_delay": 0.5,
        "max_delay": 6.0,
        "endpointing_mode": "dynamic"
    },
    "timeout": {
        "enabled": True,
        "trigger_seconds": 15.0,
        "warning_messages": ["Are you still there?"],
        "final_message": "Goodbye!"
    },
    "background_audio": {
        "ambient": {"enabled": True, "source": "office_ambience", "volume": 0.3},
        "thinking": {"enabled": True, "source": "keyboard_typing", "volume": 0.5}
    },
    "tools": {
        "rag": {"enabled": True, "knowledge_base_ids": ["kb-uuid"], "top_k": 5},
        "voicemail": {"enabled": True, "action": "hangup"},
        "hangup": {"enabled": True, "keywords": ["goodbye", "bye"]}
    },
    "transfer": {
        "enabled": True,
        "mode": "blind",
        "destinations": [{"name": "Support", "number": "+15551234567",
                          "description": "Human agent", "keywords": ["human", "agent"]}]
    },
    "analytics": {
        "recording": {"enabled": True},
        "summary": {"enabled": True},
        "success_evaluation": {"enabled": True, "criteria": "Did the agent resolve the issue?"}
    }
}

Named params always override the corresponding section in config.

---

list_agents

List all agents with a clean summary of each.

Parameter	Default
limit	20

Returns per agent: id, name, status, is_active, brain, voice_provider, call_count, created_at

---

get_agent

Get the full configuration of a specific agent — brain, voice, transcriber, conversation settings, transfer rules, analytics config, and tools.

Parameter	Required
agent_id	Yes

Returns: complete agent configuration object. Use this to read current state before updating.

---

update_agent

Update an agent's configuration. Only the fields you provide are changed.

Parameter	Type	Required	Notes
agent_id	string	Yes	—
name	string	No	—
instructions	string	No	Shortcut for brain.instructions
is_active	boolean	No	—
description	string	No	—
tags	string[]	No	—
brain_provider	string	No	—
brain_model	string	No	—
temperature	float	No	—
max_tokens	int	No	—
voice_provider	string	No	Must include when setting voice fields
voice_id	string	No	—
voice_model	string	No	—
voice_speed	float	No	—
transcriber_provider	string	No	Must include when setting transcriber fields
transcriber_model	string	No	—
language	string	No	—
first_message	string	No	—
first_message_delay_ms	int	No	—
interruption_enabled	boolean	No	—
max_call_duration	int	No	—
config	object	No	Any config section — same structure as get_agent

Returns: id, name, status, is_active, brain, voice, updated_at

When setting voice_provider, voice_id, or voice_model — always include voice_provider. The backend uses discriminated unions: a voice section without provider fails validation. Same applies to transcriber fields.

---

delete_agent

Permanently delete an agent.

Parameter	Required
agent_id	Yes

⚠️ Permanent. Any phone numbers assigned to this agent will stop answering calls.

---

duplicate_agent

Create an exact copy of an agent with all its configuration.

Parameter	Type	Required
agent_id	string	Yes
new_name	string	No

Returns: id, name, status, created_at

---

list_agent_templates

List pre-built agent templates you can use as starting points for new agents.

No parameters required.

Returns per template: id, name, description, category, default_config

---

get_agent_required_variables

Inspect an agent to find out which variables its prompt template needs. Use this before make_call or update_conversation_variables to make sure all required variables are supplied.

Parameter	Required
agent_id	Yes

Returns: dynamic_variables (list of variable names required by the agent's prompt template), system_variables (list of system variables the agent uses)

---

Calls

make_call

Place a single outbound phone call using a voice AI agent.

Prerequisites: agent_id from list_agents, number_id from list_numbers. Check get_balance first.

Parameter	Type	Required	Notes
agent_id	string	Yes	—
to_number	string	Yes	E.164 format (+12125551234)
number_id	string	Yes	From list_numbers
dynamic_variables	object	No	Template vars for {{variable}} in instructions
caller_id_name	string	No	Display name shown to recipient (max 50 chars)
caller_id_number	string	No	E.164 caller ID override
agent_override	object	No	Per-call config — same structure as agent config, deep-merged for this call only

Returns: call_id, success, to_number, from_number, agent_id, error

⚠️ Places a real phone call. Incurs telephony and AI costs.

---

list_calls

List recent voice sessions with a summary of each.

Parameter	Type	Default
limit	int	10
channel	string	— ("phone", "web", "whatsapp_voice")
direction	string	— ("inbound" or "outbound"; null for web sessions)
agent_id	string	—

Returns per call: id, status, channel, direction, duration_seconds, from_number, to_number, agent_id, started_at, ended_at, call_result

---

get_call

Get full details for a call — including the complete transcript.

This is the only tool you need to answer "What did the caller say?", "Was the agent successful?", or "What was discussed?". The transcript is returned as a list of {role, text} turns in order.

Parameter	Required
call_id	Yes

Returns: id, status, channel, direction, duration_seconds, from_number, to_number, caller_id, agent_id, started_at, ended_at, transcript (full conversation), recording_url, summary, analysis_status (pending | completed | failed), user_sentiment, user_sentiment_score, call_successful, call_successful_rationale, topics_discussed, extracted_data

Neither Vapi nor Retell return transcripts from their MCP tools.

---

hangup_call

Terminate an active call immediately.

Parameter	Required
call_id	Yes

Returns: call_id, status: "terminated"

⚠️ Immediately disconnects all participants.

---

get_active_calls

Get all calls currently in progress — who's on, which agent, how long it's been running.

No parameters required.

Returns: total_active, and per call: id, channel, direction, phone_number, agent_name, agent_id, duration_seconds, status, connection_status, started_at

Real-time supervision from your AI assistant.

---

Campaigns

create_campaign

Create a new outbound calling campaign.

Prerequisites: agent_id from list_agents, phone_number_id from list_numbers.

Parameter	Type	Required	Default
name	string	Yes	—
agent_id	string	Yes	—
phone_number_id	string	Yes	—
call_list_id	string	No	—
max_concurrent_calls	int	No	5
scheduled_start	string	No	ISO 8601 datetime

Returns: id, name, status, agent_id, created_at

---

list_campaigns

List all campaigns with current status and progress.

Parameter	Default
limit	20

Returns per campaign: id, name, status, agent_id, total_contacts, completed_calls, created_at

---

get_campaign

Get full details and current progress for a specific campaign.

Parameter	Required
campaign_id	Yes

Returns: complete campaign configuration and progress statistics.

---

start_campaign

Start an outbound calling campaign. The campaign begins dialing immediately.

Parameter	Required
campaign_id	Yes

⚠️ Begins placing real phone calls at scale.

---

pause_campaign

Pause a running campaign. Calls in progress finish; no new calls start.

Parameter	Required
campaign_id	Yes

---

stop_campaign

Permanently terminate a campaign.

Parameter	Required
campaign_id	Yes

⚠️ Remaining contacts will not be called. Cannot be reversed.

---

Phone Numbers

list_numbers

List all phone numbers with their current agent assignment.

No parameters required.

Returns per number: id, number, name, agent_id, is_active, capabilities

Run this before make_call to get a number_id.

---

assign_number

Assign a phone number to an agent. Inbound calls to this number will route to the agent immediately.

Parameter	Required
phone_number_id	Yes
agent_id	Yes

⚠️ Takes effect immediately. Replaces any existing assignment.

---

unassign_number

Remove the agent assignment from a phone number.

Parameter	Required
phone_number_id	Yes

---

Knowledge Base

No other voice AI MCP server exposes knowledge base management. These four tools let your AI assistant build out an agent's knowledge without touching the dashboard.

list_knowledge_bases

List all knowledge bases and their indexing status.

No parameters required.

Returns per KB: id, name, type, status, source_url, created_at

---

add_knowledge_from_text

Create a knowledge base from plain text — FAQs, policies, product information, scripts.

Parameter	Type	Required
name	string	Yes
text	string	Yes
description	string	No

Returns: id, name, status, created_at

---

add_knowledge_from_url

Create a knowledge base by fetching and indexing a URL.

Parameter	Type	Required
name	string	Yes
url	string	Yes — publicly accessible
description	string	No

Returns: id, name, source_url, status, created_at

---

attach_knowledge_to_agent

Connect knowledge bases to an agent. The agent searches these sources during calls.

Parameter	Type	Required
agent_id	string	Yes
knowledge_base_ids	string[]	Yes

Replaces all currently attached knowledge bases. Include all IDs you want attached, not just new ones.

---

Billing

get_balance

Get current account balance and credit status. The MCP tool returns the raw values your authenticated client receives from the API — gate make_call and start_campaign on has_credits.

No parameters required.

Returns: balance, balance_cents, has_credits, currency

---

get_usage

Get usage summary for the last N days. Voice calls are billed per second.

Parameter	Default
days	30

Returns: call_count, total_seconds, total_minutes, total_billed, period_start, period_end

---

Webhooks

create_webhook

Create a webhook to receive real-time event notifications.

Parameter	Type	Required	Default
name	string	Yes	—
url	string	Yes — HTTPS	—
events	string[]	No	all events

Available event types:

Event	Status
call.started	✅ Dispatched
call.ended	✅ Dispatched
call.failed	✅ Dispatched
campaign.started	✅ Dispatched
campaign.paused	✅ Dispatched
campaign.resumed	✅ Dispatched
campaign.stopped	✅ Dispatched
campaign.cancelled	✅ Dispatched
campaign.completed	✅ Dispatched
campaign.retry_scheduled	✅ Dispatched
dnc.added	✅ Dispatched
call.ringing	Reserved
call.answered	Reserved
call.transferred	Reserved
call.summary.ready	Reserved
transcript.partial	Reserved
transcript.final	Reserved
transcript.ready	Reserved
recording.ready	Reserved
agent.turn.started	Reserved
agent.turn.ended	Reserved
agent.tool.called	Reserved

"Reserved" events are defined in the API but not yet dispatched in production.

Returns: id, url, events, secret (shown once — store immediately), is_active, created_at

---

list_webhooks

List all active webhook subscriptions with delivery health.

No parameters required.

Returns per webhook: id, url, name, events, is_active, failure_count, last_success_at, created_at

---

Conversations

These tools work across all chat-capable channels — SMS, WhatsApp, and voice. They let your AI assistant read, send, and analyse multi-turn conversations without leaving the MCP context.

list_conversations

List conversation threads across SMS, WhatsApp, and voice.

Parameter	Type	Required	Default	Notes
channel	string	No	—	"sms", "whatsapp", "voice"
status	string	No	—	e.g. "open", "closed"
limit	int	No	20	Max 100

Returns per conversation: id, channel, contact, agent_id, status, last_message_at, unread_count

---

get_conversation

Get the full envelope for a single conversation.

Parameter	Required
conversation_id	Yes

Returns: id, channel, contact, agent_id, status, dynamic_variables, last_message_at, created_at

---

list_conversation_messages

List messages in a conversation, newest first.

Parameter	Type	Required	Default	Notes
conversation_id	string	Yes	—	—
limit	int	No	50	Max 200
since	string	No	—	ISO 8601 timestamp
before	string	No	—	ISO 8601 timestamp

Returns per message: id, direction, body, media_urls, sent_at, client_temp_id

---

send_conversation_message

Send a freeform reply on an existing SMS or WhatsApp conversation.

Parameter	Type	Required	Notes
conversation_id	string	Yes	—
body	string	Yes	Message text
media_urls	string[]	No	Attachments (WhatsApp only)
client_temp_id	string	No	Idempotency key for retries

Returns: id, conversation_id, direction, body, sent_at, client_temp_id

⚠️ Sends a real outbound SMS or WhatsApp message. Incurs carrier costs.

---

mark_conversation_read

Mark all messages in a conversation as read. Clears the unread counter used by list_conversations.

Parameter	Required
conversation_id	Yes

Returns: conversation_id, unread_count

---

get_conversation_timeline

Get a unified chronological timeline of messages and voice sessions for a conversation. Voice calls appear as voice_session events with transcript and recording_url inline.

Parameter	Type	Required	Default	Notes
conversation_id	string	Yes	—	—
limit	int	No	50	Max 200
since	string	No	—	ISO 8601 timestamp
before	string	No	—	ISO 8601 timestamp

Returns: list of events, each with type ("message" or "voice_session"), at, and the type-specific payload.

---

update_conversation_variables

Set or merge dynamic variables on a conversation. Variables are inherited by subsequent voice and chat turns that render the agent's prompt template.

Parameter	Type	Required	Default	Notes
conversation_id	string	Yes	—	—
dynamic_variables	object	Yes	—	Key/value pairs to set
replace	boolean	No	false	true = replace entire dict, false = merge

Returns: updated conversation object with new dynamic_variables.

---

get_chat_analytics

Get analytics for SMS and WhatsApp conversations over a date range.

Parameter	Type	Required	Notes
start_date	string	No	ISO date (YYYY-MM-DD)
end_date	string	No	ISO date (YYYY-MM-DD)
channel	string	No	"sms", "whatsapp"
agent_id	string	No	Filter to a specific agent
interval	string	No	"hour", "day", "week", "month"

Returns: inbound_messages, outbound_messages, avg_response_time_seconds, agent_utilisation, per-conversation outcomes (resolved, unresolved, handoff).

---

DNC (Do Not Call)

DNC tools enforce outbound dialing compliance. Always check dnc_check before placing a single call or starting a campaign. Dialing a DNC-listed number carries regulatory penalties.

dnc_check

Check whether a phone number is on a DNC list.

Parameter	Type	Required	Notes
phone	string	Yes	E.164 format

Returns: phone, is_blocked, source ("org_upload", "inbound_optout", "platform"), added_at, reason

Always check before placing outbound calls. Dialing DNC-listed numbers carries regulatory penalties.

---

dnc_list_entries

List DNC entries for the current organisation.

Parameter	Type	Required	Default	Notes
source	string	No	—	"org_upload", "inbound_optout", "platform"
limit	int	No	100	—

Returns per entry: id, phone, source, reason, added_at

---

dnc_add_entry

Add a phone number to the DNC list. All subsequent outbound calls to this number are blocked.

Parameter	Type	Required	Notes
phone	string	Yes	E.164 format
reason	string	No	Why the number is being added

Returns: id, phone, source: "org_upload", added_at

⚠️ Once added, all subsequent outbound calls to this number are blocked.

---

dnc_delete_entry

Remove a DNC entry by ID. Only org_upload entries can be removed — inbound_optout and platform entries are immutable.

Parameter	Required
entry_id	Yes

Returns: id, deleted: true

Only org_upload entries can be removed. Platform-managed entries are immutable.

---

dnc_get_settings

Get current DNC protection settings for the organisation.

No parameters required.

Returns: protection_enabled, auto_add_inbound_optouts

---

dnc_update_settings

Update DNC protection settings. With auto_add_inbound_optouts = true, any contact that replies "STOP" (or equivalent) is automatically added to the DNC list.

Parameter	Type	Required	Notes
protection_enabled	boolean	No	Master switch for outbound DNC enforcement
auto_add_inbound_optouts	boolean	No	Auto-add inbound opt-out replies to the DNC list

Returns: updated settings object.

---

Analytics

get_combined_analytics

Get unified analytics across voice and chat channels over a date range.

Parameter	Type	Required	Notes
start_date	string	No	ISO date (YYYY-MM-DD)
end_date	string	No	ISO date (YYYY-MM-DD)
agent_id	string	No	Filter to a specific agent
channel	string	No	"phone", "web", "whatsapp_voice", "sms", "whatsapp"
direction	string	No	"inbound", "outbound"
interval	string	No	"hour", "day", "week", "month"

Returns: total_volume, success_rate, avg_sentiment, total_cost, per-bucket time series combining voice and chat metrics.

---

Variables

get_system_variables_catalog

List the platform's built-in system__* template variables — the ones you can reference in any agent's prompt without defining them yourself. Use this to discover what's available before authoring instructions.

No parameters required.

Returns per variable: name, description, available_on (list of channels where the variable is populated, e.g. ["phone", "web", "sms", "whatsapp"])