Tool reference
Every Skysay 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. Required scopes are published
under _meta["ai.skysay/required_scopes"], with alternatives under
_meta["ai.skysay/alternative_required_scopes"]. Read tool responses from
result.structuredContent and check result.isError; see the
MCP client migration guide.
| Tool | Scope | Description |
|---|
account_overview | account:read | Bounded workspace summary: wallet, usage totals with up to 10 line items, and for agents, numbers, number requests, calls and SMS conversations a total with up to 5 newest previews and the list_tool that pages them. Never includes SMS message content. See Bounded results and paging. |
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. |
create_wallet_topup | wallet:write | Initiate an explicitly owner-approved purchased-wallet top-up for the authenticated workspace: return a direct Stripe Checkout URL, or use a compatible wallet’s approved shared payment token. Permission alone approves no payment; see funding paths and limits. Absent from the read-only connector. |
| 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 (at most limit agents and 25,000 characters) 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. |
get_agent_variables | agents:read | Read an AI agent's call variables config with its revision and schema_hash; the same answer as GET /v1/agents/{agent_id}/variables. |
set_agent_variables | agents:write | Replace an AI agent's whole call variables config, checked and republished at once. Send base_revision to be refused rather than overwrite a newer write. A refused config returns error.body.issues. |
| 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 | Bounded newest-first { numbers, pagination } page of phone numbers with registration status (limit 1–50, default 10; at most 25,000 characters). |
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 | Bounded newest-first { calls, pagination } page of call records without runtime_config (limit 1–50, default 10; at most 25,000 characters). get_call returns the full record. |
get_call | calls:read | Get call status, recording state, and where its conversation workflow ended (outcome, interrupts taken, settled). |
get_call_recording | recordings:read | Get recording metadata and disclosure state. |
get_call_transcript | recordings:read | Get transcript turns. |
get_call_summary | recordings:read | Get the call's AI summary: summary, follow-up, goal met and sentiment, each an AI estimate. |
create_outbound_call | calls:write | Place a policy-gated outbound call. |
| Tool | Scope | Description |
|---|
list_contact_lists | calls:read | Bounded newest-first { contact_lists, pagination } page of the workspace's contact lists, the REST contact-list record (limit 1–50, default 20; at most 25,000 characters). |
get_contact_list | calls:read | Read one contact list, the REST record with row_count. |
list_contacts | calls:read | Bounded { contact_list_id, contacts, pagination } page of one list's contacts in import order, the REST contact record (limit 1–100, default 25; at most 25,000 characters; a contact too large for any page is named in pagination.omitted). |
| Tool | Scope | Description |
|---|
list_conversations | sms:read | List SMS conversations for a workspace. |
send_sms | sms:send | Send a policy-gated SMS message. |
send_agent_template_message | sms:send and agents:read | Send one of an AI agent's published SMS templates, filled with your variables and slots, from a number in the agent's own project. |
| 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 status and verdicts. Conversation content and recording references additionally require recordings:read. |
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. |
The authored configuration and run metadata take agents:read.
get_simulation_run omits transcript, recording references and facts without
recordings:read, along with assertion actual values, rubric rationale and
linked-evidence notes that can repeat conversation content.
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.