---
title: "Phone numbers"
description: "Search, buy, bind and configure phone numbers, and bring your own numbers."
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://docs.trillet.ai/llms.txt). Append `.md` to any page URL for its markdown version.

{/* Generated by packages/mcp/scripts/gen-tool-reference.mjs from @trillet-ai/mcp v0.10.0. Do not edit by hand. */}

Search, buy, bind and configure phone numbers, and bring your own numbers. 8 tools.

## `trillet_list_phone_numbers`

**List phone numbers**

List the workspace's phone numbers: number, status, provider, bound call flow, recording, office hours, label. Name a number's assignment by callFlow.name, the name the customer sees; agent.name is the flow's inner agent and is often still "New Agent".

Flags: `read-only` `structured output`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `workspace_id` | string | no | Run this call in another workspace: its id or its name (see trillet_list_workspaces). Omit to use the default (TRILLET_WORKSPACE_ID, the workspace picked when the connector was approved, or the one set with trillet_switch_workspace). |

### Structured output

Returned as `structuredContent` (fields are optional; the same data is in the text result, where it is a bare array):

| Field | Type | Description |
| --- | --- | --- |
| `phoneNumbers` | object[] |  |

## `trillet_search_available_numbers`

**Search available numbers**

Search purchasable phone numbers. type is required except for AU. Toll-free numbers are not purchasable.

Flags: `read-only` `open-world`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `country` | string | yes | ISO country, e.g. "US", "AU", "GB" |
| `type` | string | no | "local" \| "mobile" \| "tollfree" (varies by country) |
| `area_code` | string | no |  |
| `contains` | string | no | Digit pattern the number should contain |
| `limit` | number | no | Default: `10`. |
| `workspace_id` | string | no | Run this call in another workspace: its id or its name (see trillet_list_workspaces). Omit to use the default (TRILLET_WORKSPACE_ID, the workspace picked when the connector was approved, or the one set with trillet_switch_workspace). |

## `trillet_purchase_phone_number`

**Purchase phone number (COSTS MONEY)**

Purchase a phone number found via search. Free-plan allocations complete immediately (201 with mode 'free'); otherwise the response contains a Stripe Checkout URL the user must open to pay. Requires confirm=true after the user explicitly approves the purchase. type required except AU; addressSid required outside US/CA/AU/GB.

Flags: `writes` `destructive` `open-world` `billed` `asks for confirmation`

Clients that support MCP elicitation show a confirmation form before this tool runs; declining cancels it with no changes. Other clients rely on their own approval prompt and the `confirm` argument.

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `country` | string | yes |  |
| `phone_number` | string | yes | Exact E.164 number from search results |
| `type` | string | no |  |
| `address_sid` | string | no |  |
| `confirm` | boolean | yes | Must be true. Only after the user explicitly approved. |
| `workspace_id` | string | no | Run this call in another workspace: its id or its name (see trillet_list_workspaces). Omit to use the default (TRILLET_WORKSPACE_ID, the workspace picked when the connector was approved, or the one set with trillet_switch_workspace). |

## `trillet_bind_phone_number`

**Bind phone number to agent**

Bind a workspace phone number to an agent so calls route to it (sets the number active, provisions SIP trunks for the flow's direction). The agent MUST already have a call flow. Omitted optional fields keep their current values. metadataTags values become \{\{_metadata.<key>\}\} in prompts/tools; secretBindings maps alias -> workspace secret NAME (both slug-safe lowercase) enabling per-number \{\{_secret.<alias>\}\}.

Flags: `writes` `destructive` `structured output`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `agent_id` | string | yes |  |
| `phone_number_id` | string | yes |  |
| `record_calls` | boolean | no |  |
| `recording_public` | boolean | no |  |
| `office_hours` | object | no | Phone-number-level office hours (flat shape with abbreviated day names) |
| `metadata_tags` | object (map) | no |  |
| `secret_bindings` | object (map) | no | alias -> existing workspace secret name; 400 if a name doesn't exist |
| `label` | string | no |  |
| `transfer_caller_id_mode` | "from-transferee" \| "from-transferor" | no |  |
| `workspace_id` | string | no | Run this call in another workspace: its id or its name (see trillet_list_workspaces). Omit to use the default (TRILLET_WORKSPACE_ID, the workspace picked when the connector was approved, or the one set with trillet_switch_workspace). |

### Structured output

Returned as `structuredContent` (fields are optional; the same data is in the text result):

| Field | Type | Description |
| --- | --- | --- |
| `bound` | boolean |  |
| `phoneNumber` | string |  |
| `agent` | string |  |
| `direction` | string |  |

## `trillet_release_phone_number`

**Release phone number from agent**

Unbind a phone number from an agent (the number stays owned by the workspace, it just stops routing to the agent). Fails if the number is not currently bound to that agent.

Flags: `writes` `destructive` `asks for confirmation`

Clients that support MCP elicitation show a confirmation form before this tool runs; declining cancels it with no changes. Other clients rely on their own approval prompt.

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `agent_id` | string | yes |  |
| `phone_number_id` | string | yes |  |
| `workspace_id` | string | no | Run this call in another workspace: its id or its name (see trillet_list_workspaces). Omit to use the default (TRILLET_WORKSPACE_ID, the workspace picked when the connector was approved, or the one set with trillet_switch_workspace). |

## `trillet_get_phone_number_config`

**Get phone number config**

Fetch a number's routing config: agent, direction, recording, office hours, tags, bindings.

Flags: `read-only`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `phone_number_id` | string | yes |  |
| `workspace_id` | string | no | Run this call in another workspace: its id or its name (see trillet_list_workspaces). Omit to use the default (TRILLET_WORKSPACE_ID, the workspace picked when the connector was approved, or the one set with trillet_switch_workspace). |

## `trillet_update_phone_number_config`

**Update phone number config**

Update a number's routing config in place: agent, max call duration, recording, office hours, caller-id mode on transfers, metadata tags, secret bindings, label. Only the fields you send change. Every secret name in secret_bindings must already exist as a workspace secret (400 otherwise).

Flags: `writes` `destructive`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `phone_number_id` | string | yes |  |
| `agent_id` | string | no |  |
| `max_call_duration` | number | no | Seconds |
| `recording_enabled` | boolean | no |  |
| `office_hours` | object | no | Phone-number-level office hours (flat shape with abbreviated day names) |
| `transfer_caller_id_mode` | "from-transferee" \| "from-transferor" | no |  |
| `metadata_tags` | object (map) | no |  |
| `secret_bindings` | object (map) | no | alias -> existing workspace secret name |
| `label` | string | no |  |
| `workspace_id` | string | no | Run this call in another workspace: its id or its name (see trillet_list_workspaces). Omit to use the default (TRILLET_WORKSPACE_ID, the workspace picked when the connector was approved, or the one set with trillet_switch_workspace). |

## `trillet_register_external_number`

**Register BYO / SIP number**

Register an externally-owned number (bring-your-own Twilio number or a SIP trunk from another carrier, e.g. CommsChannel) so Trillet can route calls on it. provider 'twilio' needs \{accountSid, authToken\}; provider 'sip' needs trunk credentials \{address, username, password, sipType, appendPlus\}. After registering, bind it to an agent like any other number. GOTCHA: DTMF keypresses are known to be dropped on some CommsChannel trunks.

Flags: `writes` `destructive` `open-world` `asks for confirmation`

Clients that support MCP elicitation show a confirmation form before this tool runs; declining cancels it with no changes. Other clients rely on their own approval prompt and the `confirm` argument.

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `phone_number` | string | yes | E.164 number being brought over |
| `provider` | "twilio" \| "sip" | yes |  |
| `credentials` | object (map) | yes | Provider credentials. twilio: \{accountSid, authToken\}. sip: \{address, username, password, sipType, appendPlus\} |
| `confirm` | boolean | yes | Must be true. Only set after the user explicitly approved registering this number. |
| `workspace_id` | string | no | Run this call in another workspace: its id or its name (see trillet_list_workspaces). Omit to use the default (TRILLET_WORKSPACE_ID, the workspace picked when the connector was approved, or the one set with trillet_switch_workspace). |