Assign a phone number to an agent

Tool: assign_phone_number_to_agent. Requires Admin or Owner in the applicable workspace and a connected OAuth session. Changes inbound routing and may contact the phone provider. Use IDs from list_phone_numbers and list_agents. For replacement, obtain user authorization, set confirm_reassignment: true, and supply the current inbound_workflow_id as expected_inbound_workflow_id. A stale or unconfirmed replacement fails without saving. saved: true means the assignment was saved. Inspect provider_sync and warnings separately: a provider failure can leave the assignment saved, and successful sync may still need manual provider routing. Repeating the same assignment retries sync. This does not buy/activate numbers, publish agents, place calls, or verify a live call.

Arguments

Name	Type	Required	Defaults and limits
`confirm_reassignment`	boolean	No	Default: `false`
`expected_inbound_workflow_id`	integer or null	No	Default: `null`
`phone_number_id`	integer	Yes	exclusiveMinimum: `0`
`workflow_id`	integer	Yes	exclusiveMinimum: `0`

Example arguments

Replace sample resource IDs with IDs returned in your selected workspace.

{
  "phone_number_id": 7,
  "workflow_id": 42
}

Result and errors

The schema below describes MCP structuredContent, including the result wrapper where present. Your client may also display a text representation. Read success flags and structured errors before continuing; transport success alone does not prove the operation succeeded. Authentication, missing membership, and insufficient role can fail before a tool result is produced. See troubleshooting. Effect: Changes state. Retry: Declared idempotent. Discovery annotations describe behavior; they do not grant permission or replace confirmation for consequential actions.

Input schema

{
  "additionalProperties": false,
  "properties": {
    "confirm_reassignment": {
      "default": false,
      "type": "boolean"
    },
    "expected_inbound_workflow_id": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "phone_number_id": {
      "exclusiveMinimum": 0,
      "type": "integer"
    },
    "workflow_id": {
      "exclusiveMinimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "phone_number_id",
    "workflow_id"
  ],
  "type": "object"
}

Result schema

{
  "properties": {
    "organization_id": {
      "type": "integer"
    },
    "phone_number": {
      "properties": {
        "address": {
          "type": "string"
        },
        "address_normalized": {
          "type": "string"
        },
        "address_type": {
          "type": "string"
        },
        "country_code": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "id": {
          "type": "integer"
        },
        "inbound_workflow_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ]
        },
        "inbound_workflow_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "inbound_workflow_status": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "is_active": {
          "type": "boolean"
        },
        "is_default_caller_id": {
          "type": "boolean"
        },
        "label": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "provider": {
          "type": "string"
        },
        "telephony_configuration_id": {
          "type": "integer"
        },
        "telephony_configuration_name": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "telephony_configuration_id",
        "telephony_configuration_name",
        "provider",
        "address",
        "address_normalized",
        "address_type",
        "country_code",
        "label",
        "is_active",
        "is_default_caller_id",
        "inbound_workflow_id",
        "inbound_workflow_name",
        "inbound_workflow_status"
      ],
      "type": "object"
    },
    "provider_sync": {
      "properties": {
        "message": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "ok": {
          "type": "boolean"
        }
      },
      "required": [
        "ok"
      ],
      "type": "object"
    },
    "saved": {
      "const": true,
      "default": true,
      "type": "boolean"
    },
    "warnings": {
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "organization_id",
    "phone_number",
    "provider_sync",
    "warnings"
  ],
  "type": "object"
}

Get started

Use MCP

Workspaces

Agents

Calls and outcomes

Phone numbers

Resources

Authoring guidance

Documentation

Arguments

Example arguments

Result and errors

​Arguments

​Example arguments

​Result and errors

Arguments

Example arguments

Result and errors