Phone numbers

North American phone numbers with answering rules, calls, texts and voicemail.

A phone numbers resource is a resource with kind phones. Each number answers calls according to its settings. It plays a greeting, forwards the call, and then takes voicemail with transcription.

Numbers are billed to the organization’s billing card immediately, then monthly. Pass the search price as price_cents. If the price has changed, the call fails without charging. Paid numbers require a paid plan.

Numbers use E.164 format (+19195550142), and tools also accept common formats such as (919) 555-0142. A conversation pairs one of the resource’s numbers with a peer and contains their texts, calls and voicemail. Read state is shared by everyone.

Outbound calls ring the caller’s own phone (via) first, then connect to the destination, showing the resource’s number. Texting US numbers from a local number requires 10DLC carrier registration.

The examples use the callTool helper. To connect, see the Quickstart or Authentication.

Phone numbers

Permissions

A limited agent can make only the changes its permissions allow. Read-only access allows no changes. See Access and permissions.

Phone numbersAllows
buyBuy and release numbers. Spends money.
answerSet answering rules and block or unblock callers.
callCall and text, name contacts, and mark conversations read.
voicemailMark voicemail as heard and delete it.

Phone numbers

Limits

These limits apply alongside the general limits.

WhatLimit
Numbers50 per resource
Texts1,600 characters
Labels and contact names100 characters
Greetings500 characters
Forwarded call ring time5–60 seconds

Tools · Phone numbers

phone_list

Returns the numbers, answering settings and contacts in a phone numbers resource.

Parameters

project_id string Required
The project id.
space_id string Required
The phone numbers resource id, from list_spaces.

Returns

An object with numbers and contacts. Each number has status (ordering until the carrier fulfills the order, active, failed or released), city, state, monthly_cents, paid_until and its answering settings (label, greeting, forward_to, ring_seconds, voicemail). contacts lists external numbers that communicate with these numbers, each with name and blocked.

tools/call · phone_list
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "phone_list",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "5c9e1a7f3b2d46c8a0e4b6f2d8c1a3e7"
      }
    }
  }'
Result
{
  "numbers": [
    {
      "number": "+19195550142",
      "status": "active",
      "city": "Raleigh",
      "state": "NC",
      "monthly_cents": 299,
      "ordered_at": "2026-09-30T23:46:04.560Z",
      "paid_until": "2026-10-30T23:46:04.560Z",
      "released_at": null,
      "error": "",
      "created_at": "2026-09-30T23:46:04.560Z",
      "label": "Support",
      "forward_to": "+12125550188",
      "ring_seconds": 20,
      "greeting": "Thanks for calling Launch Co.",
      "voicemail": true
    }
  ],
  "contacts": [
    {
      "number": "+12025550166",
      "name": "Sam Lee",
      "blocked": false
    }
  ]
}

Tools · Phone numbers

phone_buy

Buys a number returned by phone_search. The first month is charged to the organization’s billing card immediately, and refunded if the carrier fails the order. After that, the number is billed monthly. Paid numbers require a paid plan. The number answers with voicemail until you configure it with phone_update.

Parameters

project_id string Required
The project id.
space_id string Required
The phone numbers resource id, from list_spaces.
number string Required
One of the resource’s numbers, in E.164 (+19195550142) or a common format.
price_cents integer Required
Price per month in cents, from phone_search. The call fails without charging if the price has changed.
city string
The city from phone_search, for display.
state string
The state from phone_search.

Returns

The number, as returned by phone_list, with status active, or ordering while the carrier fulfills the order.

tools/call · phone_buy
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "phone_buy",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "5c9e1a7f3b2d46c8a0e4b6f2d8c1a3e7",
        "number": "+19195550142",
        "price_cents": 299,
        "city": "RALEIGH",
        "state": "NC"
      }
    }
  }'
Result
{
  "number": "+19195550142",
  "status": "active",
  "city": "RALEIGH",
  "state": "NC",
  "monthly_cents": 299,
  "ordered_at": "2026-09-30T23:46:04.560Z",
  "paid_until": "2026-10-30T23:46:04.560Z",
  "released_at": null,
  "error": "",
  "created_at": "2026-09-30T23:46:04.560Z",
  "label": "",
  "forward_to": "",
  "ring_seconds": 20,
  "greeting": "",
  "voicemail": true
}

Tools · Phone numbers

phone_update

Sets how a number answers calls. Omitted fields are unchanged. Callers hear the greeting, and then forward_to rings, showing the caller’s number. If there is no forward_to, or it doesn’t answer, the call goes to voicemail when voicemail is on. Otherwise, the call ends.

Parameters

project_id string Required
The project id.
space_id string Required
The phone numbers resource id, from list_spaces.
number string Required
One of the resource’s numbers, in E.164 (+19195550142) or a common format.
label string
Label shown with the number, up to 100 characters.
greeting string
Text spoken first, up to 500 characters. Empty for none.
forward_to string
Phone number to ring. Can’t be one of the resource’s numbers. Empty for none.
ring_seconds integer
How long forward_to rings, 5–60 seconds.
voicemail boolean
Whether to take voicemail for unanswered calls.

Returns

The number, as returned by phone_list.

tools/call · phone_update
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "phone_update",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "5c9e1a7f3b2d46c8a0e4b6f2d8c1a3e7",
        "number": "+19195550142",
        "label": "Support",
        "forward_to": "(212) 555-0188",
        "greeting": "Thanks for calling Launch Co."
      }
    }
  }'
Result
{
  "number": "+19195550142",
  "status": "active",
  "city": "Raleigh",
  "state": "NC",
  "monthly_cents": 299,
  "ordered_at": "2026-09-30T23:46:04.560Z",
  "paid_until": "2026-10-30T23:46:04.560Z",
  "released_at": null,
  "error": "",
  "created_at": "2026-09-30T23:46:04.560Z",
  "label": "Support",
  "forward_to": "+12125550188",
  "ring_seconds": 20,
  "greeting": "Thanks for calling Launch Co.",
  "voicemail": true
}

Tools · Phone numbers

phone_release

Releases a number to the carrier immediately. The number stops answering calls and stops being billed. The paid period isn’t refunded.

Parameters

project_id string Required
The project id.
space_id string Required
The phone numbers resource id, from list_spaces.
number string Required
One of the resource’s numbers, in E.164 (+19195550142) or a common format.

Returns

The number, now released.

tools/call · phone_release
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "phone_release",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "5c9e1a7f3b2d46c8a0e4b6f2d8c1a3e7",
        "number": "+19195550142"
      }
    }
  }'
Result
{
  "number": "+19195550142",
  "status": "released",
  "city": "Raleigh",
  "state": "NC",
  "monthly_cents": 299,
  "ordered_at": "2026-09-30T23:46:04.560Z",
  "paid_until": "2026-10-30T23:46:04.560Z",
  "released_at": "2026-09-30T23:46:04.800Z",
  "error": "",
  "created_at": "2026-09-30T23:46:04.560Z",
  "label": "Support",
  "forward_to": "+12125550188",
  "ring_seconds": 20,
  "greeting": "Thanks for calling Launch Co.",
  "voicemail": true
}

Tools · Phone numbers

phone_remove

Removes a number from the list once it is no longer held, because its order failed or it was released. Its calls, voicemail and texts are kept.

Parameters

project_id string Required
The project id.
space_id string Required
The phone numbers resource id, from list_spaces.
number string Required
One of the resource’s numbers, in E.164 (+19195550142) or a common format.

Returns

The removed number.

tools/call · phone_remove
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "phone_remove",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "5c9e1a7f3b2d46c8a0e4b6f2d8c1a3e7",
        "number": "+19195550142"
      }
    }
  }'
Result
{
  "removed": "+19195550142"
}

Tools · Phone numbers

phone_save_contact

Names, blocks or unblocks an external phone number. A name is shown everywhere the number appears. Calls from a blocked number are rejected, and its texts are dropped. Omitted fields are unchanged.

Parameters

project_id string Required
The project id.
space_id string Required
The phone numbers resource id, from list_spaces.
contact string Required
The external phone number.
name string
Up to 100 characters. Empty removes the name.
blocked boolean
Whether the number is blocked.

Returns

The contact, with its number, name and blocked.

tools/call · phone_save_contact
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "phone_save_contact",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "5c9e1a7f3b2d46c8a0e4b6f2d8c1a3e7",
        "contact": "(202) 555-0166",
        "name": "Sam Lee"
      }
    }
  }'
Result
{
  "number": "+12025550166",
  "name": "Sam Lee",
  "blocked": false
}

Tools · Calls and texts

phone_list_conversations

Lists text conversations on the resource’s numbers, newest first. Each conversation is identified by a number and a peer.

Parameters

project_id string Required
The project id.
space_id string Required
The phone numbers resource id, from list_spaces.
number string
One of the resource’s numbers to filter by.

Returns

An array of conversations, each with number, peer, last (the newest text) and unread (texts received since the conversation was last read).

tools/call · phone_list_conversations
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "phone_list_conversations",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "5c9e1a7f3b2d46c8a0e4b6f2d8c1a3e7"
      }
    }
  }'
Result
[
  {
    "number": "+19195550142",
    "peer": "+12025550166",
    "last": {
      "id": "9e3c7a1f5b4d42e8a6c0b2f4d8e1a3c5",
      "number": "+19195550142",
      "direction": "out",
      "peer": "+12025550166",
      "body": "Yes, the 21st. See you there.",
      "status": "delivered",
      "segments": 1,
      "error": "",
      "sent_by": "5761e31cd8538b7da8a3ddd4157bd632",
      "created_at": "2026-09-30T23:46:04.620Z"
    },
    "unread": 0
  }
]

Tools · Calls and texts

phone_read_conversation

Returns a conversation’s texts, calls and voicemail, oldest first, and marks the conversation read for everyone.

Parameters

project_id string Required
The project id.
space_id string Required
The phone numbers resource id, from list_spaces.
number string Required
One of the resource’s numbers, in E.164 (+19195550142) or a common format.
peer string Required
The other party’s number.
limit integer
Number of most recent items to return, 1–500. Defaults to 100.
mark_read boolean
Whether to mark the conversation read. Defaults to true.

Returns

An object with number, peer, contact (or null), items and read. Each item has a kind (text, call or voicemail) and the same fields as in phone_list_calls and phone_list_voicemails. A text’s status is sending, sent, delivered, failed (with error) or received. read is false if the agent can’t mark the conversation read.

tools/call · phone_read_conversation
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "phone_read_conversation",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "5c9e1a7f3b2d46c8a0e4b6f2d8c1a3e7",
        "number": "+19195550142",
        "peer": "+12025550166"
      }
    }
  }'
Result
{
  "number": "+19195550142",
  "peer": "+12025550166",
  "contact": {
    "number": "+12025550166",
    "name": "Sam Lee",
    "blocked": false
  },
  "items": [
    {
      "kind": "call",
      "id": "b3d7f1a5c9e240b6d8a2c4e6f0b1d3a5",
      "number": "+19195550142",
      "direction": "in",
      "peer": "+12025550166",
      "status": "voicemail",
      "started_at": "2026-09-30T23:46:04.580Z",
      "answered_at": null,
      "ended_at": "2026-09-30T23:46:04.590Z",
      "duration": 42,
      "cause": "hangup",
      "placed_by": null,
      "via": null
    },
    {
      "kind": "voicemail",
      "id": "f7a1c5e9b3d246a8c0e2f4b6d8a1c3e5",
      "number": "+19195550142",
      "peer": "+12025550166",
      "call_id": "b3d7f1a5c9e240b6d8a2c4e6f0b1d3a5",
      "duration": 18,
      "transcript": "Hi, it’s Sam calling about the launch. Call me back when you can.",
      "heard": false,
      "created_at": "2026-09-30T23:46:04.590Z"
    },
    {
      "kind": "text",
      "id": "1a5c9e3f7b2d48a6c0e4f8b2d6a9c1e3",
      "number": "+19195550142",
      "direction": "in",
      "peer": "+12025550166",
      "body": "Is the launch still on for the 21st?",
      "status": "received",
      "segments": 1,
      "error": "",
      "sent_by": null,
      "created_at": "2026-09-30T23:46:04.600Z"
    },
    {
      "kind": "text",
      "id": "9e3c7a1f5b4d42e8a6c0b2f4d8e1a3c5",
      "number": "+19195550142",
      "direction": "out",
      "peer": "+12025550166",
      "body": "Yes, the 21st. See you there.",
      "status": "delivered",
      "segments": 1,
      "error": "",
      "sent_by": "5761e31cd8538b7da8a3ddd4157bd632",
      "created_at": "2026-09-30T23:46:04.620Z"
    }
  ],
  "read": true
}

Tools · Calls and texts

phone_send_text

Sends a text from one of the resource’s numbers. Delivery status (sent, delivered, or failed with a reason) appears later in phone_read_conversation. Texting US numbers from a local number requires 10DLC carrier registration. Until the number is registered, carriers reject its texts.

Parameters

project_id string Required
The project id.
space_id string Required
The phone numbers resource id, from list_spaces.
number string Required
One of the resource’s numbers, in E.164 (+19195550142) or a common format.
to string Required
The recipient’s number.
body string Required
1–1,600 characters, trimmed.

Returns

The text, with status sending.

tools/call · phone_send_text
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "phone_send_text",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "5c9e1a7f3b2d46c8a0e4b6f2d8c1a3e7",
        "number": "+19195550142",
        "to": "+12025550166",
        "body": "Yes, the 21st. See you there."
      }
    }
  }'
Result
{
  "id": "9e3c7a1f5b4d42e8a6c0b2f4d8e1a3c5",
  "number": "+19195550142",
  "direction": "out",
  "peer": "+12025550166",
  "body": "Yes, the 21st. See you there.",
  "status": "sending",
  "segments": 1,
  "error": "",
  "sent_by": "5761e31cd8538b7da8a3ddd4157bd632",
  "created_at": "2026-09-30T23:46:04.620Z"
}

Tools · Calls and texts

phone_place_call

Places a call from one of the resource’s numbers. The call first rings via, the caller’s own phone. Once that phone answers, the call connects to to, showing the resource’s number.

Parameters

project_id string Required
The project id.
space_id string Required
The phone numbers resource id, from list_spaces.
number string Required
One of the resource’s numbers, in E.164 (+19195550142) or a common format.
to string Required
The number to call.
via string
The phone to ring first. Defaults to the phone the acting person last used with this number, or else the number’s forward_to.

Returns

The call, with status ringing.

tools/call · phone_place_call
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "phone_place_call",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "5c9e1a7f3b2d46c8a0e4b6f2d8c1a3e7",
        "number": "+19195550142",
        "to": "+12025550166",
        "via": "+12125550188"
      }
    }
  }'
Result
{
  "id": "8a4c6e2f0b9d41a3c5e7f9b1d3a5c7e9",
  "number": "+19195550142",
  "direction": "out",
  "peer": "+12025550166",
  "status": "ringing",
  "started_at": "2026-09-30T23:46:04.900Z",
  "answered_at": null,
  "ended_at": null,
  "duration": null,
  "cause": "",
  "placed_by": "5761e31cd8538b7da8a3ddd4157bd632",
  "via": "+12125550188"
}

Tools · Calls and texts

phone_list_calls

Lists calls on the resource’s numbers, newest first.

Parameters

project_id string Required
The project id.
space_id string Required
The phone numbers resource id, from list_spaces.
number string
One of the resource’s numbers to filter by.
limit integer
Number of calls to return, 1–500. Defaults to 100.

Returns

An array of calls, each with direction (in or out), peer, status (ringing, forwarding, answered, voicemail, missed, completed or failed), started_at, answered_at, ended_at, duration (seconds) and cause (why the call ended). Outbound calls include placed_by and via.

tools/call · phone_list_calls
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "phone_list_calls",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "5c9e1a7f3b2d46c8a0e4b6f2d8c1a3e7"
      }
    }
  }'
Result
[
  {
    "id": "b3d7f1a5c9e240b6d8a2c4e6f0b1d3a5",
    "number": "+19195550142",
    "direction": "in",
    "peer": "+12025550166",
    "status": "voicemail",
    "started_at": "2026-09-30T23:46:04.580Z",
    "answered_at": null,
    "ended_at": "2026-09-30T23:46:04.590Z",
    "duration": 42,
    "cause": "hangup",
    "placed_by": null,
    "via": null
  }
]

Tools · Calls and texts

phone_list_voicemails

Lists voicemail on the resource’s numbers, newest first.

Parameters

project_id string Required
The project id.
space_id string Required
The phone numbers resource id, from list_spaces.
number string
One of the resource’s numbers to filter by.

Returns

An array of voicemail messages, each with peer, call_id, duration (seconds), transcript (null while pending, empty if none) and heard. Recordings can be played in the app.

tools/call · phone_list_voicemails
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "phone_list_voicemails",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "5c9e1a7f3b2d46c8a0e4b6f2d8c1a3e7"
      }
    }
  }'
Result
[
  {
    "id": "f7a1c5e9b3d246a8c0e2f4b6d8a1c3e5",
    "number": "+19195550142",
    "peer": "+12025550166",
    "call_id": "b3d7f1a5c9e240b6d8a2c4e6f0b1d3a5",
    "duration": 18,
    "transcript": "Hi, it’s Sam calling about the launch. Call me back when you can.",
    "heard": false,
    "created_at": "2026-09-30T23:46:04.590Z"
  }
]

Tools · Calls and texts

phone_update_voicemail

Marks a voicemail heard or unheard.

Parameters

project_id string Required
The project id.
space_id string Required
The phone numbers resource id, from list_spaces.
voicemail_id string Required
The voicemail id.
heard boolean Required
Whether the voicemail has been heard.

Returns

The voicemail’s id and heard.

tools/call · phone_update_voicemail
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "phone_update_voicemail",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "5c9e1a7f3b2d46c8a0e4b6f2d8c1a3e7",
        "voicemail_id": "f7a1c5e9b3d246a8c0e2f4b6d8a1c3e5",
        "heard": true
      }
    }
  }'
Result
{
  "id": "f7a1c5e9b3d246a8c0e2f4b6d8a1c3e5",
  "heard": true
}

Tools · Calls and texts

phone_delete_voicemail

Deletes a voicemail.

Parameters

project_id string Required
The project id.
space_id string Required
The phone numbers resource id, from list_spaces.
voicemail_id string Required
The voicemail id.

Returns

The deleted voicemail’s id.

tools/call · phone_delete_voicemail
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "phone_delete_voicemail",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "5c9e1a7f3b2d46c8a0e4b6f2d8c1a3e7",
        "voicemail_id": "f7a1c5e9b3d246a8c0e2f4b6d8a1c3e5"
      }
    }
  }'
Result
{
  "deleted": "f7a1c5e9b3d246a8c0e2f4b6d8a1c3e5"
}

Questions or something missing? Contact us.