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
A limited agent can make only the changes its permissions allow. Read-only access allows no changes. See Access and permissions.
| Phone numbers | Allows |
|---|---|
buy | Buy and release numbers. Spends money. |
answer | Set answering rules and block or unblock callers. |
call | Call and text, name contacts, and mark conversations read. |
voicemail | Mark voicemail as heard and delete it. |
Phone numbers
These limits apply alongside the general limits.
| What | Limit |
|---|---|
| Numbers | 50 per resource |
| Texts | 1,600 characters |
| Labels and contact names | 100 characters |
| Greetings | 500 characters |
| Forwarded call ring time | 5–60 seconds |
Tools · Phone numbers
Returns the numbers, answering settings and contacts in a phone numbers resource.
project_id string Requiredspace_id string Requiredlist_spaces.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.
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"
}
}
}'{
"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
Searches for available North American numbers. Pass one criterion: an area code, a city and state (or a state alone), a ZIP code, toll-free, or ending digits.
project_id string Requiredspace_id string Requiredlist_spaces.area_code string 919.city string state.state string NC.zip string toll_free boolean contains string FLOWERS is 356-9377.Up to 12 numbers, each with city, state, the monthly price in cents and held (true if already held here).
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_search",
"arguments": {
"project_id": "b6909c9cf00c1d482686b5f52eadd58e",
"space_id": "5c9e1a7f3b2d46c8a0e4b6f2d8c1a3e7",
"area_code": "919"
}
}
}'[
{
"number": "+19195550142",
"city": "RALEIGH",
"state": "NC",
"cents": 299,
"held": false
},
{
"number": "+19195550177",
"city": "DURHAM",
"state": "NC",
"cents": 299,
"held": false
}
]Tools · Phone numbers
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.
project_id string Requiredspace_id string Requiredlist_spaces.number string Required+19195550142) or a common format.price_cents integer Requiredphone_search. The call fails without charging if the price has changed.city string phone_search, for display.state string phone_search.The number, as returned by phone_list, with status active, or ordering while the carrier fulfills the order.
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"
}
}
}'{
"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
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.
project_id string Requiredspace_id string Requiredlist_spaces.number string Required+19195550142) or a common format.label string greeting string forward_to string ring_seconds integer forward_to rings, 5–60 seconds.voicemail boolean The number, as returned by 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_update",
"arguments": {
"project_id": "b6909c9cf00c1d482686b5f52eadd58e",
"space_id": "5c9e1a7f3b2d46c8a0e4b6f2d8c1a3e7",
"number": "+19195550142",
"label": "Support",
"forward_to": "(212) 555-0188",
"greeting": "Thanks for calling Launch Co."
}
}
}'{
"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
Releases a number to the carrier immediately. The number stops answering calls and stops being billed. The paid period isn’t refunded.
project_id string Requiredspace_id string Requiredlist_spaces.number string Required+19195550142) or a common format.The number, now released.
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"
}
}
}'{
"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
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.
project_id string Requiredspace_id string Requiredlist_spaces.number string Required+19195550142) or a common format.The removed number.
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"
}
}
}'{
"removed": "+19195550142"
}Tools · Phone numbers
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.
project_id string Requiredspace_id string Requiredlist_spaces.contact string Requiredname string blocked boolean The contact, with its number, name and blocked.
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"
}
}
}'{
"number": "+12025550166",
"name": "Sam Lee",
"blocked": false
}Tools · Calls and texts
Lists text conversations on the resource’s numbers, newest first. Each conversation is identified by a number and a peer.
project_id string Requiredspace_id string Requiredlist_spaces.number string An array of conversations, each with number, peer, last (the newest text) and unread (texts received since the conversation was last read).
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"
}
}
}'[
{
"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
Returns a conversation’s texts, calls and voicemail, oldest first, and marks the conversation read for everyone.
project_id string Requiredspace_id string Requiredlist_spaces.number string Required+19195550142) or a common format.peer string Requiredlimit integer mark_read boolean 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.
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"
}
}
}'{
"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
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.
project_id string Requiredspace_id string Requiredlist_spaces.number string Required+19195550142) or a common format.to string Requiredbody string RequiredThe text, with status sending.
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."
}
}
}'{
"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
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.
project_id string Requiredspace_id string Requiredlist_spaces.number string Required+19195550142) or a common format.to string Requiredvia string forward_to.The call, with status ringing.
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"
}
}
}'{
"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
Lists calls on the resource’s numbers, newest first.
project_id string Requiredspace_id string Requiredlist_spaces.number string limit integer 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.
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"
}
}
}'[
{
"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
Lists voicemail on the resource’s numbers, newest first.
project_id string Requiredspace_id string Requiredlist_spaces.number string 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.
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"
}
}
}'[
{
"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
Marks a voicemail heard or unheard.
project_id string Requiredspace_id string Requiredlist_spaces.voicemail_id string Requiredheard boolean RequiredThe voicemail’s id and heard.
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
}
}
}'{
"id": "f7a1c5e9b3d246a8c0e2f4b6d8a1c3e5",
"heard": true
}Tools · Calls and texts
Deletes a voicemail.
project_id string Requiredspace_id string Requiredlist_spaces.voicemail_id string RequiredThe deleted voicemail’s id.
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"
}
}
}'{
"deleted": "f7a1c5e9b3d246a8c0e2f4b6d8a1c3e5"
}Questions or something missing? Contact us.