Tool reference
Every OpenPhonex MCP tool with its required scope, generated from the server's TOOL_SCOPES.
Every tool the agent can call, with the scope it requires. Scopes are
authoritative on the server (TOOL_SCOPES in src/telephony_ai/mcp.py) — treat
the live tools/list on your instance as canonical.
| Tool | Scope | Description |
|---|
account_overview | account:read | Wallet, agents, numbers, calls, SMS conversations, and usage for a workspace. |
list_audio_environments | account:read | Read the immutable versioned ambience catalogue (including Off). It has the same result and scope as GET /v1/audio-environments; it never contacts a provider or changes a selection. |
| Tool | Scope | Description |
|---|
get_coverage | coverage:read | Supported countries with voice, SMS, registration, and onboarding speed. |
get_number_catalog | coverage:read | Number SKUs with setup/monthly price, capabilities, and onboarding terms. |
get_agent_catalog | agents:read or coverage:read | Selectable STT/LLM/TTS providers with cost, latency, languages, streaming, runnability, plus conversation_engines; optional metered_only: boolean defaults to false, and true returns only component-metered choices. |
check_number_requirements | coverage:read | Country and number-type onboarding requirements in plain terms. |
| Tool | Scope | Description |
|---|
list_agents | agents:read | Bounded newest-first { agents, pagination } page using the safe REST agent item projection. |
get_agent | agents:read | Read one safe agent configuration projection. |
create_agent | agents:write | Create a first-class agent in external_audio, external_text, or hosted mode. |
connect_external_agent | agents:write | Shortcut for an external_audio agent with webhook + audio-stream URLs. |
update_agent | agents:write | Apply the generic mutable-agent PATCH fields and REST validation. |
get_agent_voice_stack | agents:read | Read the selected stack and sparse language profiles. |
set_agent_voice_stack | agents:write | Set transcriber/model/voice, first message, system prompt, language, and optional voice_frontend (cascade or gpt_live). |
preview_voice | agents:write | Explicit bounded, rate-limited provider/BYOK Listen action; may have provider and safe state effects, so it is not read-only. |
| Tool | Scope | Description |
|---|
create_trial_call | trial_calls:write | Create an offline fixture with synthetic_only: true. Shared-number live PIN trials are retired. |
| Tool | Scope | Description |
|---|
list_numbers | numbers:read | List phone numbers and registration status. |
get_number_rules | numbers:read | Get customer-facing number rules for one phone number. |
list_phone_servers | numbers:read | List customer phone servers for self-hosted media/calling. |
request_number | numbers:write | Create a managed number request (live ordering needs operator approval). |
update_number_rules | numbers:write | Update customer-facing number rules for one phone number. |
create_phone_server | numbers:write | Create a customer phone server (dry-run verify before assigning). |
test_phone_server | numbers:write | Dry-run verify a customer phone server before assigning a number. |
| Tool | Scope | Description |
|---|
list_calls | calls:read | List calls for a workspace. |
get_call | calls:read | Get call status and recording state. |
get_call_recording | recordings:read | Get recording metadata and disclosure state. |
get_call_transcript | recordings:read | Get transcript turns. |
create_outbound_call | calls:write | Place a policy-gated outbound call. |
| Tool | Scope | Description |
|---|
list_conversations | sms:read | List SMS conversations for a workspace. |
send_sms | sms:send | Send a policy-gated SMS message. |
| Tool | Scope | Description |
|---|
evaluate_outbound_policy | policy:evaluate | Return the outbound policy decision and cost before anything leaves. |
authorize_outbound | policy:evaluate | Authorize a policy-approved outbound action. |
get_capabilities | onboarding:read | Read the workspace capabilities (state, profiles, channels, destinations, caps, calling rules, usage). |
request_capabilities | onboarding:write | Request more capabilities (profiles, channels, destinations) and accept the outbound policy. The destination choice is required: all_countries: true, or countries naming at least one ISO 3166-1 alpha-2 code. |
Scripted synthetic callers exercising one of your AI agents. See
Simulations Lab for what a suite is and what a run
costs.
| Tool | Scope | Description |
|---|
list_simulation_suites | agents:read | An AI agent's suites, each with the health of its latest run. |
get_simulation_suite | agents:read | One suite: scenarios, runners, policy, run history, and run_setup. |
create_simulation_suite | agents:write | Create a suite, optionally with its whole scenario list in one call. |
preview_simulation_run | agents:read | What a run would cost and which runners this deployment admits. Creates nothing. |
start_simulation_run | agents:write | Start a run. Spends your budget; idempotency_key is required. |
get_simulation_run | agents:read | One run's attempts with verdicts, facts, transcripts and evidence links. |
get_simulation_run_results | simulation_suites:read | The redacted pass/fail projection for a build server. |
cancel_simulation_run | agents:write | Cancel a queued or running run. |
Two scopes, deliberately. The rich reads take agents:read because they return
authored scenarios and what your callers said. get_simulation_run_results
takes only simulation_suites:read, so a CI job can gate a deploy on a run
without holding a key that reads every AI agent's configuration.
See Scopes & permissions for the full scope catalog and
fail-closed semantics.