MCP tools reference

Every tool Telenow's MCP server offers: what it does, the permission it needs, what it takes and what it returns.

An assistant is shown only the tools its connection's permissions allow (Permissions, limits & safety). Every result comes twice, as structured JSON (structuredContent) and as text. When Telenow declines — a Do-Not-Call number, a missing value — the result has isError: true and a sentence saying why, which the assistant relays.

The tools that reach people are marked destructive and open-world in their MCP annotations, so ChatGPT and Claude ask you before running them.

"This assistant" below means one connection's assistant. With an organization API key as the bearer instead, the tools act for the whole organization: every live number, call and campaign, and every agent an assistant made.

Calls

list_numbers

The numbers the assistant may call from — the ones you picked when connecting (every live number of the organization for an API key). The first is the default caller ID.

Takes nothing. Returns numbers: { id, phone_number, country }.

place_call

Places one real phone call and returns at once with a call_id. Two ways:

• The built-in agent with a task — task, on_behalf_of and opening_line are required. The opening line is in the callee's language and says it is an AI assistant calling on behalf of on_behalf_of, and why.
• One of your agents — agent_id (an active one), plus variables for its {placeholders}. Its own prompt runs the call, so task, details and language are not used.

Returns { call_id, status, to, from, message } — status is dialing, or for a retried key the first attempt's placed or failed.

{ "to": "+919845012345", "task": "Ask whether they are open on Sunday and until when.", "on_behalf_of": "Asha",
  "opening_line": "Hi, I'm an AI assistant calling for Asha to ask about your Sunday hours." }

get_call

One call by call_id — from place_call, list_calls or a campaign's results.

list_calls

Recent calls on the assistant's numbers, newest first.

Returns calls with the call fields of get_call — status (in_progress or ended; only get_call tells dialing apart), direction, numbers, times, duration, outcome, answered_by — without end_reason, the summary, analysis and transcript.

Agents

list_agents

The organization's agents, most recently changed first: agent_id, name, kind (single_context or flow), active, model, speech_to_text, voice, created_by_assistant, changeable (this assistant may change it), and is_assistant_calls_agent. Takes an optional limit (1–200).

get_agent

One agent: prompt, opening line, voice, model, speech-to-text, session_config, variables, voicemail message, post-call analysis, objectives, time zone, changeable, its graph (flow, for a flow agent) and every other option in the Agents API's own shape (settings — exactly what create_agent and update_agent take back). Keys are never returned: each shows as a mask (••••1234), and update_agent keeps the stored key behind a mask sent back unchanged. A very large agent comes back without settings, then without flow, with a note saying so.

create_agent

Creates a single-context agent — one conversation with one goal. Requires name and system_prompt.

Options that reach outside the call — tools, pre-call lookups, transfer and tool steps, custom model or speech endpoints, any URL anywhere, isPublic, postCallWhatsApp, call-backs the agent books (sessionConfig.followup) — need the Give agents tools permission (Permissions, limits & safety). Credentials are never accepted, in any field; a new agent also refuses masked keys copied from another.

Returns { agent_id, name, kind, voice, model, speech_to_text, warnings, message }.

create_flow_agent

Creates a multi-step (flow) agent: the call as a graph of steps with conditions between them. Assistants use it when you describe several scenarios or conditional paths — different handling for different callers or answers, a keypad menu, details collected step by step, a path to a person from anywhere. Requires name and flow; takes everything create_agent takes (system_prompt here is what every step shares).

flow is the graph, in the same shape as an agent's metadata.flow in the Agents API — { startNodeId, nodes, edges }. Every step kind, field and condition is in Flow agents API. It is checked exactly as calls run it: a graph the runtime would discard is refused with the reasons — so is a graph of one step with no exits, which calls run single-context — and what would run but may misbehave comes back as warnings.

Returns the same as create_agent, with kind: "flow". Example: Multi-step calls.

update_agent

Changes an agent this assistant created. Requires agent_id; send only what changes — everything else stays. Each top-level settings object (llmConfig, sessionConfig, metadata, …) is merged onto the stored one, one level deep: settings the assistant does not mention survive, but a nested object it sends (callerMemory, silenceCheckin, …) replaces the stored one — send it whole. flow replaces the whole graph — read it with get_agent, change it, send it back; masked keys left as they are keep the stored keys, and a mask whose step now points somewhere new is refused. Giving a single-context agent a flow makes it a flow agent. Takes everything create_agent and create_flow_agent take except country. Returns { agent_id, name, warnings, message }.

list_voices

Voices an agent can use, each with a sample.

Returns provider and voices: { voice_id, name, preview_url, sample_text, language, languages, gender, accent, age, style, use_case, description, model }.

estimate_cost

The cost of a minute of calling, in USD — for an existing agent (agent_id) or a planned one (model, speech_to_text, voice: each { provider, model? }, plus system_prompt). What is left out of a plan comes from your organization's defaults for country; from_number picks the carrier. Returns per_minute (model, speech_to_text, voice, telephony, platform_fee, total), the stack priced, not_priced (parts the catalogue has no price for) and a note. See Costs per minute.

Campaigns

list_campaigns

Campaigns set to call from the assistant's numbers, newest first, each with its settings, progress (total, completed, failed, pending) and can_run (this assistant may start it and add people). Takes optional status (draft, running, paused, completed, cancelled) and limit (1–100, default 20); more says whether more matched.

get_campaign

One campaign and its results. Takes campaign_id, optional cursor (the previous page's next_cursor) and results_limit (0–100, default 50).

Each result: { call_id, phone, name, outcome, attempt, completed_at, fields, sentiment } — outcome is answered, no-answer, busy, failed or machine; fields is what the agent's analysis extracted. Results come in the order calls finished. An empty page means nothing newer yet; ask again later with the same cursor.

create_campaign

Creates a campaign as a draft — nothing is dialed. Requires name and agent_id.

Returns campaign, targets (added; duplicates — people this connection already added, by id; do_not_call — numbers on your list or already waiting in the campaign; skipped) and a message. Defaults and rules: Campaigns from a search.

add_campaign_targets

Adds people to a campaign this assistant created: campaign_id, targets (up to 1,000), optional variables. On a running campaign they are called right away. Returns the counts, plus campaign_status.

start_campaign

Starts or resumes a campaign this assistant created (campaign_id). Starting a running campaign changes nothing; a completed or cancelled one cannot be started.

pause_campaign

Pauses any campaign set to call from the assistant's numbers (campaign_id): no one new is dialed, and calls in progress finish.