List registered phone numbers

Tool: list_phone_numbers. Requires Viewer or higher in the applicable workspace and a connected OAuth session. Lists workspace PSTN/SIP addresses, assignments, active/default flags, and phone-system names and IDs. These are numbers already registered in Agent Builder, not numbers available to purchase. No provider inventory request is made. Follow next_page until null with unchanged filters. total counts all matches; pages are live reads. Use returned internal IDs for assignment rather than guessing them.

Arguments

Name	Type	Required	Defaults and limits
`is_active`	boolean or null	No	Default: `null`
`page`	integer	No	Default: `1`; minimum: `1`
`page_size`	integer	No	Default: `50`; minimum: `1`; maximum: `100`
`workflow_id`	integer or null	No	Default: `null`

Example arguments

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

{
  "page": 1,
  "page_size": 50
}

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: Reads data. Retry: Declared idempotent. Discovery annotations describe behavior; they do not grant permission or replace confirmation for consequential actions.

Input schema

{
  "additionalProperties": false,
  "properties": {
    "is_active": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "page": {
      "default": 1,
      "minimum": 1,
      "type": "integer"
    },
    "page_size": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    },
    "workflow_id": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "type": "object"
}

Result schema

{
  "properties": {
    "next_page": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ]
    },
    "organization_id": {
      "type": "integer"
    },
    "page": {
      "type": "integer"
    },
    "page_size": {
      "type": "integer"
    },
    "phone_numbers": {
      "items": {
        "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"
      },
      "type": "array"
    },
    "total": {
      "type": "integer"
    }
  },
  "required": [
    "organization_id",
    "phone_numbers",
    "total",
    "page",
    "page_size",
    "next_page"
  ],
  "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