Muse Voice Agent

MCP tool reference

Six tools let an AI assistant place phone calls, follow their progress, and collect callbacks.

Connection

ProtocolModel Context Protocol, streamable HTTP transport
Endpointhttps://<server>/mcp
AuthenticationAuthorization: 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 checkGET /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

  1. Confirm the business, phone number and brief with the user.
  2. Call place_call (or a specialized shortcut). It returns a call_id immediately.
  3. Poll get_call_status about every 20 seconds until done is true. Calls usually take 1 to 5 minutes.
  4. Tell the user the summary, key details, unanswered questions and suggested next steps from the report.
  5. Whenever a response includes unread_updates > 0, call get_updates and 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.

ParameterTypeDescription
business_namestring, requiredName of the business.
phone_numberstring, requiredBusiness phone number (E.164).
customer_namestring, requiredFull name of the user the call is for. The agent introduces itself as their assistant.
goalstring, requiredOne or two sentences on what the call should accomplish, including exact items when ordering.
questionsstring[]Up to 10 specific questions. Each comes back in the report's answers.
shareable_detailsobjectExtra details the agent may share, e.g. {"email": "alex@example.com"}. Name and callback number are always allowed. Never include card numbers or SSNs.
authorityenuminfo_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.
limitsstringRequired when the agent may commit. Free-text limits, e.g. "Oct 10–12 only, max $250/night, no deposit".
max_spendnumberMaximum total spend.
max_depositnumberMaximum deposit or prepayment. Defaults to none.
max_cancellation_feenumberMaximum cancellation or no-show fee. Defaults to none.
allowed_date_time_windowstringAllowed date and time window.
party_size_min, party_size_maxintegerAllowed party size range.
callback_numberstringThe user's number for the business to call back. The agent may share it.
assistant_namestringThe 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.

ParameterTypeDescription
restaurant_namestring, requiredName of the restaurant.
phone_numberstring, requiredRestaurant phone number (E.164).
customer_namestring, requiredFull name of the user.
party_sizeinteger, requiredNumber of guests.
datestring, requiredRequested date, e.g. "Fri Oct 10".
timestring, requiredRequested time, e.g. "7:30 PM".
flexibilitystringAcceptable alternatives, e.g. "6:30–8:30pm same day". Without it, the agent only collects the closest available times.
special_requestsstringSeating, allergies or occasion.
shareable_details, callback_number, assistant_nameSame as place_call.

request_handyman_quote

Shortcut for asking a handyman or contractor for a price and availability. It never books.

ParameterTypeDescription
business_namestring, requiredBusiness or person.
phone_numberstring, requiredPhone number (E.164).
customer_namestring, requiredFull name of the user.
job_descriptionstring, requiredWhat needs doing, e.g. "replace a leaking kitchen faucet".
locationstring, requiredCity, neighborhood or ZIP. Avoid a full street address.
preferred_timingstringe.g. "weekday mornings next week".
budgetstringMentioned only if the business asks.
shareable_details, callback_number, assistant_nameSame 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.

ParameterTypeDescription
call_idstring, requiredThe id returned when the call started.
include_transcriptbooleanInclude 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.

ParameterTypeDescription
limitinteger1 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.

ParameterTypeDescription
limitinteger1 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

FieldValues
statusIn progress: queued, dispatched, dialing, in_progress. Final: completed, failed, no_answer.
outcomebooked, ordered, quote_received, info_received, unavailable, declined, needs_followup, voicemail
directionoutbound 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."
}
The agent always says it's an AI, discloses recording, won't share payment details or unapproved personal information, and never commits beyond the limits you pass. See the home page for the full list of safeguards.