MCP tool reference
Six tools let an AI assistant place phone calls, follow their progress, and collect callbacks.
Connection
| Protocol | Model Context Protocol, streamable HTTP transport |
|---|---|
| Endpoint | https://<server>/mcp |
| Authentication | Authorization: Bearer <api key> on every request. Get a key at /pricing and manage it at /account. Requests without a valid key get 401. Each key only sees its own calls. |
| Health check | GET /healthz (no token needed) returns {"ok": true} |
Minutes and billing
New accounts include 10 free minutes; after that a monthly plan includes 50 (Starter, $5) or 200 (Plus, $20) minutes per billing period. Only talk time on outbound calls counts. The allowance is checked before dialing. When it's used up, the call tools place no call and return:
{
"error": "payment_required",
"message": "You've used your 10 free minutes. Subscribe to keep placing calls: https://…/account",
"billing_url": "https://…/account"
}
Show the message and link to the user and don't retry. get_call_status,
list_calls and get_updates keep working. When two or fewer minutes are
left, call results also include a billing_notice string to pass on. A call that runs
20 minutes past the remaining minutes is ended politely, and its result includes a
cut_off explanation.
Typical flow
- Confirm the business, phone number and brief with the user.
- Call
place_call(or a specialized shortcut). It returns acall_idimmediately. - Poll
get_call_statusabout every 20 seconds untildoneistrue. Calls usually take 1 to 5 minutes. - Tell the user the summary, key details, unanswered questions and suggested next steps from the
report. - Whenever a response includes
unread_updates > 0, callget_updatesand tell the user what the business said when it called back.
Phone numbers use E.164 format, for example +14155550123.
place_call
General-purpose call for any errand: questions, availability, quotes, pickup orders, reservations, and scheduling, rescheduling or cancelling appointments.
| Parameter | Type | Description |
|---|---|---|
business_name | string, required | Name of the business. |
phone_number | string, required | Business phone number (E.164). |
customer_name | string, required | Full name of the user the call is for. The agent introduces itself as their assistant. |
goal | string, required | One or two sentences on what the call should accomplish, including exact items when ordering. |
questions | string[] | Up to 10 specific questions. Each comes back in the report's answers. |
shareable_details | object | Extra details the agent may share, e.g. {"email": "alex@example.com"}. Name and callback number are always allowed. Never include card numbers or SSNs. |
authority | enum | info_only (default, commits to nothing) or may_commit_within_limits (may book, order, schedule or cancel within limits). may_book_within_limits is an alias. |
limits | string | Required when the agent may commit. Free-text limits, e.g. "Oct 10–12 only, max $250/night, no deposit". |
max_spend | number | Maximum total spend. |
max_deposit | number | Maximum deposit or prepayment. Defaults to none. |
max_cancellation_fee | number | Maximum cancellation or no-show fee. Defaults to none. |
allowed_date_time_window | string | Allowed date and time window. |
party_size_min, party_size_max | integer | Allowed party size range. |
callback_number | string | The user's number for the business to call back. The agent may share it. |
assistant_name | string | The assistant's own name. The agent opens with "Hi, this is {assistant_name}, an AI assistant calling on behalf of {customer_name}." |
book_restaurant_reservation
Shortcut tuned for booking a restaurant table.
| Parameter | Type | Description |
|---|---|---|
restaurant_name | string, required | Name of the restaurant. |
phone_number | string, required | Restaurant phone number (E.164). |
customer_name | string, required | Full name of the user. |
party_size | integer, required | Number of guests. |
date | string, required | Requested date, e.g. "Fri Oct 10". |
time | string, required | Requested time, e.g. "7:30 PM". |
flexibility | string | Acceptable alternatives, e.g. "6:30–8:30pm same day". Without it, the agent only collects the closest available times. |
special_requests | string | Seating, allergies or occasion. |
shareable_details, callback_number, assistant_name | Same as place_call. |
request_handyman_quote
Shortcut for asking a handyman or contractor for a price and availability. It never books.
| Parameter | Type | Description |
|---|---|---|
business_name | string, required | Business or person. |
phone_number | string, required | Phone number (E.164). |
customer_name | string, required | Full name of the user. |
job_description | string, required | What needs doing, e.g. "replace a leaking kitchen faucet". |
location | string, required | City, neighborhood or ZIP. Avoid a full street address. |
preferred_timing | string | e.g. "weekday mornings next week". |
budget | string | Mentioned only if the business asks. |
shareable_details, callback_number, assistant_name | Same as place_call. |
What the call tools return
All three call tools return immediately with the call record: call_id,
status, done, business_name, phone_number and
next_step. Invalid input returns {"error": "invalid_request"}; a call the
server won't place (for example a number outside the allowed dialing regions, or too many calls at once) returns
{"error": "rejected"}.
get_call_status
Read-only. Gets the status and result of a call.
| Parameter | Type | Description |
|---|---|---|
call_id | string, required | The id returned when the call started. |
include_transcript | boolean | Include the speaker-labeled transcript. Defaults to yes once the call is done. |
Once done is true, the response includes a report with the
original request, who answered (person, voicemail,
phone_menu, no_answer or not_connected), start and end
times, duration, how the call ended, whether the agent committed on the user's behalf, an
answer for each question, unanswered questions and suggested next steps. It also lists any
callbacks linked to this call.
list_calls
Read-only. Lists recent calls, newest first, without reports or transcripts.
| Parameter | Type | Description |
|---|---|---|
limit | integer | 1 to 50. Default 10. |
get_updates
Collects calls businesses made back to the agent that haven't been reported yet. Each update is returned once, then marked as seen.
| Parameter | Type | Description |
|---|---|---|
limit | integer | 1 to 50. Default 20. Oldest first. |
Each update has kind: callback (a business returned one of your calls;
original_call identifies it) or message (an unknown caller left a
message). remaining says how many are still unread. The server can't push
notifications, so assistants should check get_updates on a schedule after a call
ends in voicemail or a promised callback.
Status and outcome values
| Field | Values |
|---|---|
status | In progress: queued, dispatched, dialing, in_progress. Final: completed, failed, no_answer. |
outcome | booked, ordered, quote_received, info_received, unavailable, declined, needs_followup, voicemail |
direction | outbound or inbound. Inbound callbacks set callback_of to the original call_id. |
Example
// tools/call
{
"name": "place_call",
"arguments": {
"business_name": "Golden Gate Bakery",
"phone_number": "+14155550123",
"customer_name": "Alex Kim",
"assistant_name": "Eva",
"goal": "Find out whether they have egg tarts today and until what time.",
"questions": ["Do you have egg tarts today?", "What time do you close?"]
}
}
// result
{
"call_id": "3f9c1a7b2e4d",
"status": "queued",
"done": false,
"next_step": "Poll get_call_status with this call_id until done is true."
}