Twilio

Run a valid twilio.buy_number call through the same SDK surface used by every toolkit.

Minimal tool call

import { Eyeball } from "@eyeball/sdk";

const eyeball = new Eyeball({
  apiKey: process.env.EYEBALL_API_KEY!,
  baseUrl: process.env.EYEBALL_EXECUTOR_URL!,
});

const output = await eyeball.tools.run(
  "twilio.buy_number",
  {
  "phoneNumber": "+12025550123"
},
  { userId: "demo_user",
  idempotencyKey: "docs:twilio.buy_number:demo-1" },
);
console.log(output);

The model receives canonical output. Your application retains the execution envelope through tools.execute or the execution APIs when it needs IDs, status, versions, and latency.

Supported canonical tools

Tool	Purpose	Execution	Effect	Version
`twilio.buy_number`	Acquire a provider telephone number into owned inventory. The new number is initially unbound.	sync or async	mutation	`1.0.0`
`twilio.end_call`	End an active call. Repeating the request leaves the call terminal.	sync or async	destructive mutation	`1.0.0`
`twilio.get_call`	Retrieve normalized lifecycle, participant phone numbers, timing, and provider-derived state for one call.	sync or async	read	`1.0.0`
`twilio.list_calls`	List calls with portable state, participant, and time filters. Provider ordering is preserved.	sync or async	read	`1.0.0`
`twilio.list_numbers`	List provider-owned telephone numbers with their current Eyeball agent-binding status.	sync or async	read	`1.0.0`
`twilio.release_number`	Permanently return an unbound telephone number to its provider. Bound numbers must be detached first.	sync or async	destructive mutation	`1.0.0`
`twilio.send_dtmf`	Send DTMF digits to an active call leg. Digits may trigger irreversible behavior in an external IVR.	sync or async	mutation	`1.0.0`
`twilio.start_call`	Start an outbound PSTN call. This is asynchronous by nature; poll the execution for allocation, then use get_call for carrier lifecycle state.	async	mutation	`1.0.0`
`twilio.transfer_call`	Transfer or bridge an active call to another E.164 destination.	sync or async	mutation	`1.0.0`

Only the rows above are implemented. A capability tool omitted by this manifest returns not_supported; eyeball never synthesizes provider parity.

Supported canonical triggers

This manifest does not implement a canonical trigger.

Input and output schemas

twilio.buy_number

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:voice_telephony:buy_number:1.0.0:twilio",
  "type": "object",
  "description": "Telephone number to acquire and its optional provider label.",
  "additionalProperties": false,
  "required": [
    "phoneNumber"
  ],
  "properties": {
    "phoneNumber": {
      "type": "string",
      "description": "Telephone number to acquire in E.164 form.",
      "pattern": "^\\+[1-9][0-9]{7,14}$"
    },
    "friendlyName": {
      "type": "string",
      "description": "Optional human-readable provider label.",
      "minLength": 1
    },
    "transportConnectionId": {
      "type": "string",
      "description": "Provider connection used by composed voice-agent inventory tools; direct provider tools use the execution connection.",
      "minLength": 1
    }
  }
}

Output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:voice_telephony:buy_number:output:1.0.0:twilio",
  "type": "object",
  "description": "The newly acquired unbound number.",
  "additionalProperties": false,
  "required": [
    "number"
  ],
  "properties": {
    "number": {
      "type": "object",
      "description": "One provider-owned telephone number with its Eyeball agent-binding state.",
      "additionalProperties": false,
      "required": [
        "numberId",
        "phoneNumber",
        "friendlyName",
        "provider",
        "bindingStatus",
        "createdAt"
      ],
      "properties": {
        "numberId": {
          "type": "string",
          "description": "Provider-stable owned-number identifier.",
          "minLength": 1
        },
        "phoneNumber": {
          "type": "string",
          "description": "Owned telephone number in E.164 form.",
          "pattern": "^\\+[1-9][0-9]{7,14}$"
        },
        "friendlyName": {
          "type": "string",
          "description": "Human-readable provider label.",
          "minLength": 1
        },
        "provider": {
          "type": "string",
          "description": "Provider toolkit that owns the number.",
          "minLength": 1
        },
        "bindingStatus": {
          "type": "string",
          "description": "Whether the number is currently attached to an Eyeball voice agent.",
          "enum": [
            "unbound",
            "bound"
          ]
        },
        "binding": {
          "type": "object",
          "description": "Pinned agent binding when bindingStatus is bound.",
          "additionalProperties": false,
          "required": [
            "bindingId",
            "agentId",
            "revision",
            "transportConnectionId"
          ],
          "properties": {
            "bindingId": {
              "type": "string",
              "description": "Stable binding identifier.",
              "minLength": 1
            },
            "agentId": {
              "type": "string",
              "description": "Bound voice-agent identifier.",
              "minLength": 1
            },
            "revision": {
              "type": "integer",
              "description": "Immutable agent revision pinned by the binding.",
              "minimum": 1
            },
            "transportConnectionId": {
              "type": "string",
              "description": "Twilio connection selected by the binding.",
              "minLength": 1
            }
          }
        },
        "createdAt": {
          "type": "string",
          "description": "Time the provider acquired the number.",
          "format": "date-time"
        }
      }
    }
  }
}

twilio.end_call

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:voice_telephony:end_call:1.0.0:twilio",
  "type": "object",
  "description": "End an active call. Repeating the request leaves the call terminal.",
  "additionalProperties": false,
  "required": [
    "callId"
  ],
  "properties": {
    "callId": {
      "type": "string",
      "description": "Provider-stable call identifier.",
      "minLength": 1
    }
  }
}

Output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:voice_telephony:end_call:output:1.0.0:twilio",
  "type": "object",
  "description": "Call state after the requested control operation.",
  "additionalProperties": false,
  "required": [
    "callId",
    "state",
    "to",
    "from",
    "direction",
    "createdAt",
    "updatedAt",
    "durationSeconds"
  ],
  "properties": {
    "callId": {
      "type": "string",
      "description": "Provider-stable call identifier.",
      "minLength": 1
    },
    "state": {
      "type": "string",
      "description": "Normalized provider call lifecycle state.",
      "enum": [
        "queued",
        "ringing",
        "in-progress",
        "completed",
        "busy",
        "no-answer",
        "failed",
        "canceled"
      ]
    },
    "to": {
      "type": "string",
      "description": "Current destination phone number.",
      "pattern": "^\\+[1-9][0-9]{7,14}$"
    },
    "from": {
      "type": "string",
      "description": "Originating phone number.",
      "pattern": "^\\+[1-9][0-9]{7,14}$"
    },
    "direction": {
      "type": "string",
      "description": "Direction in which the call was established.",
      "enum": [
        "inbound",
        "outbound"
      ]
    },
    "createdAt": {
      "type": "string",
      "description": "Time the provider created the call.",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "description": "Time the provider last changed the call.",
      "format": "date-time"
    },
    "startedAt": {
      "type": "string",
      "description": "Time a participant answered the call.",
      "format": "date-time"
    },
    "endedAt": {
      "type": "string",
      "description": "Time the call reached a terminal state.",
      "format": "date-time"
    },
    "durationSeconds": {
      "type": "integer",
      "description": "Connected call duration in whole seconds.",
      "minimum": 0
    },
    "transfers": {
      "type": "array",
      "description": "Destinations to which the call has been transferred.",
      "items": {
        "type": "string",
        "description": "A transfer destination.",
        "pattern": "^\\+[1-9][0-9]{7,14}$"
      }
    }
  }
}

twilio.get_call

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:voice_telephony:get_call:1.0.0:twilio",
  "type": "object",
  "description": "Identifier of the call to retrieve.",
  "additionalProperties": false,
  "required": [
    "callId"
  ],
  "properties": {
    "callId": {
      "type": "string",
      "description": "Provider-stable call identifier.",
      "minLength": 1
    }
  }
}

Output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:voice_telephony:get_call:output:1.0.0:twilio",
  "type": "object",
  "description": "Current normalized call state.",
  "additionalProperties": false,
  "required": [
    "callId",
    "state",
    "to",
    "from",
    "direction",
    "createdAt",
    "updatedAt",
    "durationSeconds"
  ],
  "properties": {
    "callId": {
      "type": "string",
      "description": "Provider-stable call identifier.",
      "minLength": 1
    },
    "state": {
      "type": "string",
      "description": "Normalized provider call lifecycle state.",
      "enum": [
        "queued",
        "ringing",
        "in-progress",
        "completed",
        "busy",
        "no-answer",
        "failed",
        "canceled"
      ]
    },
    "to": {
      "type": "string",
      "description": "Current destination phone number.",
      "pattern": "^\\+[1-9][0-9]{7,14}$"
    },
    "from": {
      "type": "string",
      "description": "Originating phone number.",
      "pattern": "^\\+[1-9][0-9]{7,14}$"
    },
    "direction": {
      "type": "string",
      "description": "Direction in which the call was established.",
      "enum": [
        "inbound",
        "outbound"
      ]
    },
    "createdAt": {
      "type": "string",
      "description": "Time the provider created the call.",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "description": "Time the provider last changed the call.",
      "format": "date-time"
    },
    "startedAt": {
      "type": "string",
      "description": "Time a participant answered the call.",
      "format": "date-time"
    },
    "endedAt": {
      "type": "string",
      "description": "Time the call reached a terminal state.",
      "format": "date-time"
    },
    "durationSeconds": {
      "type": "integer",
      "description": "Connected call duration in whole seconds.",
      "minimum": 0
    },
    "transfers": {
      "type": "array",
      "description": "Destinations to which the call has been transferred.",
      "items": {
        "type": "string",
        "description": "A transfer destination.",
        "pattern": "^\\+[1-9][0-9]{7,14}$"
      }
    }
  }
}

twilio.list_calls

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:voice_telephony:list_calls:1.0.0:twilio",
  "type": "object",
  "description": "Portable filters and pagination for provider calls.",
  "additionalProperties": false,
  "properties": {
    "state": {
      "type": "string",
      "description": "Normalized provider call lifecycle state.",
      "enum": [
        "queued",
        "ringing",
        "in-progress",
        "completed",
        "busy",
        "no-answer",
        "failed",
        "canceled"
      ]
    },
    "to": {
      "type": "string",
      "description": "Return only calls to this phone number.",
      "pattern": "^\\+[1-9][0-9]{7,14}$"
    },
    "from": {
      "type": "string",
      "description": "Return only calls from this phone number.",
      "pattern": "^\\+[1-9][0-9]{7,14}$"
    },
    "createdAfter": {
      "type": "string",
      "description": "Return calls created at or after this time.",
      "format": "date-time"
    },
    "createdBefore": {
      "type": "string",
      "description": "Return calls created before this time.",
      "format": "date-time"
    },
    "pageSize": {
      "type": "integer",
      "description": "Maximum number of calls to return in one page.",
      "minimum": 1,
      "maximum": 100,
      "default": 50
    },
    "pageToken": {
      "type": "string",
      "description": "Opaque continuation token from a previous call page.",
      "minLength": 1
    }
  }
}

Output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:voice_telephony:list_calls:output:1.0.0:twilio",
  "type": "object",
  "description": "One page of normalized calls.",
  "additionalProperties": false,
  "required": [
    "calls"
  ],
  "properties": {
    "calls": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "Normalized state and timing for one provider call.",
        "additionalProperties": false,
        "required": [
          "callId",
          "state",
          "to",
          "from",
          "direction",
          "createdAt",
          "updatedAt",
          "durationSeconds"
        ],
        "properties": {
          "callId": {
            "type": "string",
            "description": "Provider-stable call identifier.",
            "minLength": 1
          },
          "state": {
            "type": "string",
            "description": "Normalized provider call lifecycle state.",
            "enum": [
              "queued",
              "ringing",
              "in-progress",
              "completed",
              "busy",
              "no-answer",
              "failed",
              "canceled"
            ]
          },
          "to": {
            "type": "string",
            "description": "Current destination phone number.",
            "pattern": "^\\+[1-9][0-9]{7,14}$"
          },
          "from": {
            "type": "string",
            "description": "Originating phone number.",
            "pattern": "^\\+[1-9][0-9]{7,14}$"
          },
          "direction": {
            "type": "string",
            "description": "Direction in which the call was established.",
            "enum": [
              "inbound",
              "outbound"
            ]
          },
          "createdAt": {
            "type": "string",
            "description": "Time the provider created the call.",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "description": "Time the provider last changed the call.",
            "format": "date-time"
          },
          "startedAt": {
            "type": "string",
            "description": "Time a participant answered the call.",
            "format": "date-time"
          },
          "endedAt": {
            "type": "string",
            "description": "Time the call reached a terminal state.",
            "format": "date-time"
          },
          "durationSeconds": {
            "type": "integer",
            "description": "Connected call duration in whole seconds.",
            "minimum": 0
          },
          "transfers": {
            "type": "array",
            "description": "Destinations to which the call has been transferred.",
            "items": {
              "type": "string",
              "description": "A transfer destination.",
              "pattern": "^\\+[1-9][0-9]{7,14}$"
            }
          }
        }
      }
    },
    "nextPageToken": {
      "type": "string",
      "description": "Opaque token to request the next page of calls; absent when the result is complete.",
      "minLength": 1
    }
  }
}

twilio.list_numbers

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:voice_telephony:list_numbers:1.0.0:twilio",
  "type": "object",
  "description": "Optional number filter and pagination controls.",
  "additionalProperties": false,
  "properties": {
    "phoneNumber": {
      "type": "string",
      "description": "Optional exact E.164 telephone-number filter.",
      "pattern": "^\\+[1-9][0-9]{7,14}$"
    },
    "transportConnectionId": {
      "type": "string",
      "description": "Provider connection used by composed voice-agent inventory tools; direct provider tools use the execution connection.",
      "minLength": 1
    },
    "pageSize": {
      "type": "integer",
      "description": "Maximum number of numbers to return in one page.",
      "minimum": 1,
      "maximum": 100,
      "default": 50
    },
    "pageToken": {
      "type": "string",
      "description": "Opaque continuation token from a previous numbers page.",
      "minLength": 1
    }
  }
}

Output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:voice_telephony:list_numbers:output:1.0.0:twilio",
  "type": "object",
  "description": "Owned telephone-number inventory and binding status.",
  "additionalProperties": false,
  "required": [
    "numbers"
  ],
  "properties": {
    "numbers": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "One provider-owned telephone number with its Eyeball agent-binding state.",
        "additionalProperties": false,
        "required": [
          "numberId",
          "phoneNumber",
          "friendlyName",
          "provider",
          "bindingStatus",
          "createdAt"
        ],
        "properties": {
          "numberId": {
            "type": "string",
            "description": "Provider-stable owned-number identifier.",
            "minLength": 1
          },
          "phoneNumber": {
            "type": "string",
            "description": "Owned telephone number in E.164 form.",
            "pattern": "^\\+[1-9][0-9]{7,14}$"
          },
          "friendlyName": {
            "type": "string",
            "description": "Human-readable provider label.",
            "minLength": 1
          },
          "provider": {
            "type": "string",
            "description": "Provider toolkit that owns the number.",
            "minLength": 1
          },
          "bindingStatus": {
            "type": "string",
            "description": "Whether the number is currently attached to an Eyeball voice agent.",
            "enum": [
              "unbound",
              "bound"
            ]
          },
          "binding": {
            "type": "object",
            "description": "Pinned agent binding when bindingStatus is bound.",
            "additionalProperties": false,
            "required": [
              "bindingId",
              "agentId",
              "revision",
              "transportConnectionId"
            ],
            "properties": {
              "bindingId": {
                "type": "string",
                "description": "Stable binding identifier.",
                "minLength": 1
              },
              "agentId": {
                "type": "string",
                "description": "Bound voice-agent identifier.",
                "minLength": 1
              },
              "revision": {
                "type": "integer",
                "description": "Immutable agent revision pinned by the binding.",
                "minimum": 1
              },
              "transportConnectionId": {
                "type": "string",
                "description": "Twilio connection selected by the binding.",
                "minLength": 1
              }
            }
          },
          "createdAt": {
            "type": "string",
            "description": "Time the provider acquired the number.",
            "format": "date-time"
          }
        }
      }
    },
    "nextPageToken": {
      "type": "string",
      "description": "Opaque token to request the next page of numbers; absent when the result is complete.",
      "minLength": 1
    }
  }
}

twilio.release_number

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:voice_telephony:release_number:1.0.0:twilio",
  "type": "object",
  "description": "Owned telephone number to return to the provider.",
  "additionalProperties": false,
  "required": [
    "phoneNumber"
  ],
  "properties": {
    "phoneNumber": {
      "type": "string",
      "description": "Owned telephone number to release in E.164 form.",
      "pattern": "^\\+[1-9][0-9]{7,14}$"
    },
    "transportConnectionId": {
      "type": "string",
      "description": "Provider connection used by composed voice-agent inventory tools; direct provider tools use the execution connection.",
      "minLength": 1
    }
  }
}

Output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:voice_telephony:release_number:output:1.0.0:twilio",
  "type": "object",
  "description": "Provider identifier and time of the completed release.",
  "additionalProperties": false,
  "required": [
    "numberId",
    "phoneNumber",
    "releasedAt"
  ],
  "properties": {
    "numberId": {
      "type": "string",
      "description": "Provider-stable identifier of the released number.",
      "minLength": 1
    },
    "phoneNumber": {
      "type": "string",
      "description": "Released telephone number in E.164 form.",
      "pattern": "^\\+[1-9][0-9]{7,14}$"
    },
    "releasedAt": {
      "type": "string",
      "description": "Time the number was returned to the provider.",
      "format": "date-time"
    }
  }
}

twilio.send_dtmf

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:voice_telephony:send_dtmf:1.0.0:twilio",
  "type": "object",
  "description": "Target call and DTMF digit sequence.",
  "additionalProperties": false,
  "required": [
    "callId",
    "digits"
  ],
  "properties": {
    "callId": {
      "type": "string",
      "description": "Provider-stable call identifier.",
      "minLength": 1
    },
    "digits": {
      "type": "string",
      "description": "DTMF digits, pauses, or waits to send.",
      "pattern": "^[0-9A-D*#wW]+$"
    }
  }
}

Output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:voice_telephony:send_dtmf:output:1.0.0:twilio",
  "type": "object",
  "description": "Confirmation that the provider accepted the DTMF sequence.",
  "additionalProperties": false,
  "required": [
    "callId",
    "state",
    "digitsSent"
  ],
  "properties": {
    "callId": {
      "type": "string",
      "description": "Provider-stable call identifier.",
      "minLength": 1
    },
    "state": {
      "type": "string",
      "description": "Normalized provider call lifecycle state.",
      "enum": [
        "queued",
        "ringing",
        "in-progress",
        "completed",
        "busy",
        "no-answer",
        "failed",
        "canceled"
      ]
    },
    "digitsSent": {
      "type": "string",
      "pattern": "^[0-9A-D*#wW]+$"
    }
  }
}

twilio.start_call

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:voice_telephony:start_call:1.0.0:twilio",
  "type": "object",
  "description": "Origin, destination, and optional voice-agent reference.",
  "additionalProperties": false,
  "required": [
    "to",
    "from"
  ],
  "properties": {
    "to": {
      "type": "string",
      "description": "Destination phone number in E.164 form.",
      "pattern": "^\\+[1-9][0-9]{7,14}$"
    },
    "from": {
      "type": "string",
      "description": "Owned originating phone number in E.164 form.",
      "pattern": "^\\+[1-9][0-9]{7,14}$"
    },
    "voiceAgentId": {
      "type": "string",
      "description": "Optional low-level voice-agent identifier interpreted by the provider integration.",
      "minLength": 1
    },
    "statusCallbackUrl": {
      "type": "string",
      "format": "uri",
      "description": "Optional provider callback URL for low-level call status."
    }
  }
}

Output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:voice_telephony:start_call:output:1.0.0:twilio",
  "type": "object",
  "description": "The newly allocated provider call in its initial state.",
  "additionalProperties": false,
  "required": [
    "callId",
    "state",
    "to",
    "from",
    "direction",
    "createdAt",
    "updatedAt",
    "durationSeconds"
  ],
  "properties": {
    "callId": {
      "type": "string",
      "description": "Provider-stable call identifier.",
      "minLength": 1
    },
    "state": {
      "type": "string",
      "description": "Normalized provider call lifecycle state.",
      "enum": [
        "queued",
        "ringing",
        "in-progress",
        "completed",
        "busy",
        "no-answer",
        "failed",
        "canceled"
      ]
    },
    "to": {
      "type": "string",
      "description": "Current destination phone number.",
      "pattern": "^\\+[1-9][0-9]{7,14}$"
    },
    "from": {
      "type": "string",
      "description": "Originating phone number.",
      "pattern": "^\\+[1-9][0-9]{7,14}$"
    },
    "direction": {
      "type": "string",
      "description": "Direction in which the call was established.",
      "enum": [
        "inbound",
        "outbound"
      ]
    },
    "createdAt": {
      "type": "string",
      "description": "Time the provider created the call.",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "description": "Time the provider last changed the call.",
      "format": "date-time"
    },
    "startedAt": {
      "type": "string",
      "description": "Time a participant answered the call.",
      "format": "date-time"
    },
    "endedAt": {
      "type": "string",
      "description": "Time the call reached a terminal state.",
      "format": "date-time"
    },
    "durationSeconds": {
      "type": "integer",
      "description": "Connected call duration in whole seconds.",
      "minimum": 0
    },
    "transfers": {
      "type": "array",
      "description": "Destinations to which the call has been transferred.",
      "items": {
        "type": "string",
        "description": "A transfer destination.",
        "pattern": "^\\+[1-9][0-9]{7,14}$"
      }
    }
  }
}

twilio.transfer_call

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:voice_telephony:transfer_call:1.0.0:twilio",
  "type": "object",
  "description": "Transfer or bridge an active call to another E.164 destination.",
  "additionalProperties": false,
  "required": [
    "callId",
    "to"
  ],
  "properties": {
    "callId": {
      "type": "string",
      "description": "Provider-stable call identifier.",
      "minLength": 1
    },
    "to": {
      "type": "string",
      "description": "New destination phone number.",
      "pattern": "^\\+[1-9][0-9]{7,14}$"
    }
  }
}

Output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:voice_telephony:transfer_call:output:1.0.0:twilio",
  "type": "object",
  "description": "Call state after the requested control operation.",
  "additionalProperties": false,
  "required": [
    "callId",
    "state",
    "to",
    "from",
    "direction",
    "createdAt",
    "updatedAt",
    "durationSeconds"
  ],
  "properties": {
    "callId": {
      "type": "string",
      "description": "Provider-stable call identifier.",
      "minLength": 1
    },
    "state": {
      "type": "string",
      "description": "Normalized provider call lifecycle state.",
      "enum": [
        "queued",
        "ringing",
        "in-progress",
        "completed",
        "busy",
        "no-answer",
        "failed",
        "canceled"
      ]
    },
    "to": {
      "type": "string",
      "description": "Current destination phone number.",
      "pattern": "^\\+[1-9][0-9]{7,14}$"
    },
    "from": {
      "type": "string",
      "description": "Originating phone number.",
      "pattern": "^\\+[1-9][0-9]{7,14}$"
    },
    "direction": {
      "type": "string",
      "description": "Direction in which the call was established.",
      "enum": [
        "inbound",
        "outbound"
      ]
    },
    "createdAt": {
      "type": "string",
      "description": "Time the provider created the call.",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "description": "Time the provider last changed the call.",
      "format": "date-time"
    },
    "startedAt": {
      "type": "string",
      "description": "Time a participant answered the call.",
      "format": "date-time"
    },
    "endedAt": {
      "type": "string",
      "description": "Time the call reached a terminal state.",
      "format": "date-time"
    },
    "durationSeconds": {
      "type": "integer",
      "description": "Connected call duration in whole seconds.",
      "minimum": 0
    },
    "transfers": {
      "type": "array",
      "description": "Destinations to which the call has been transferred.",
      "items": {
        "type": "string",
        "description": "A transfer destination.",
        "pattern": "^\\+[1-9][0-9]{7,14}$"
      }
    }
  }
}

Authentication

Property	Value
Auth class	`basic`
Required scopes	None
Optional scopes	None
Credential fields	`accountSid`, `authToken`

Credentials are resolved inside the executor by CredentialProvider. They never belong in tool input, x_provider, model context, logs, or execution output.

Provider-specific extensions

This manifest declares no provider-specific schema extensions. Use only canonical fields.

Provider differences may appear only under x_provider.twilio and only when the schema above declares them.

Sync and async behavior

These tools require async mode: twilio.start_call. Other tools accept sync or async mode.

Mutations require a stable Idempotency-Key. The TypeScript SDK accepts it as idempotencyKey; it is never part of the JSON request body.

REST example

curl "$EYEBALL_EXECUTOR_URL/v1/execute" \
  -H "Authorization: Bearer $EYEBALL_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: docs:twilio.buy_number:demo-1' \
  --data '{"tool":"twilio.buy_number","userId":"demo_user","input":{"phoneNumber":"+12025550123"},"mode":"sync"}'

Point EYEBALL_EXECUTOR_URL at a mock-configured executor to run through the real catalog, validation, credential seam, adapter, normalized errors, and execution records with no Twilio account. Mock selection changes the executor endpoint and trusted provider base-URL configuration, never the execute request.

Limitations

This page describes the manifest's explicit P0 subset, not every operation offered by the provider.
Provider account policy, consent UI, quota details, and current wire compatibility still require a real-provider certification pass.
Fields outside the canonical schemas and declared x_provider extensions are rejected.

Versions

Contract	Version
Runtime catalog	`1.1`
Manifest catalog	`1.0`
Manifest schema	`1.0`
Source	`native`
Tier	`P0`
Capabilities	`voice_telephony`

Use Testing with mocks to exercise this toolkit before connecting a live provider account.

Minimal tool call

Supported canonical tools

Supported canonical triggers

Input and output schemas

Authentication

Provider-specific extensions

Sync and async behavior

REST example

Mock support

Limitations

Versions

Next