Skip to main content
Glama

Place an outbound call

make_call
Destructive

Places one outbound voice call via Vobiz, plays spoken text or audio, and returns a request UUID for call-status follow-up.

Instructions

Place ONE outbound call through Vobiz (POST /Account/{auth_id}/Call/); say (text to speak) and/or play (a direct https .mp3/.wav link, or the name of a file in the audio library) is the simplest way to put content on it: this server hosts the call script, and the call ends automatically after the content unless loop is 0. answer_url is only for callers hosting their own VobizXML; a call with neither answer_url nor say/play only speaks a short placeholder greeting and ends after a few seconds. Required: to (destination, E.164), from (caller ID: must be an active number on this account), and confirm: true after the user has explicitly approved this exact call. Success means Vobiz ACCEPTED/QUEUED the request and returned a request_uuid; it does NOT mean the call connected. Follow up with get_call_status using the returned request_uuid as call_uuid. Never call this twice for the same intent: if the outcome is unknown, check list_live_calls / list_call_records instead. Pass a unique idempotency_key per intended call: repeating a key replays the first result instead of dialling again; without one, an identical call inside the duplicate window fails with duplicate_blocked. Once the call is live, act on it with speak_text, play_audio, transfer_call or end_call. Server policy (enforced, not negotiable by the model): allowed destination countries, blocked prefixes, max duration, per-minute/hour caps, max concurrent calls, minimum balance; outbound calling itself can be switched off (calls_disabled).

Input Schema

NameRequiredDescriptionDefault
toYesDestination number in E.164, e.g. +919876543210. One number only.
sayNoText spoken when the call is answered (max 600 characters), e.g. "Your table is ready."
fromYesCaller ID: a Vobiz number on this account, E.164.
loopNoHow many times to play the audio (or speak the text when there is no audio), 0..10, default 1. 0 = repeat until the call is hung up.
playNoAudio played when the call is answered: a direct https link to an .mp3 or .wav FILE (not a web page such as Pixabay, YouTube, Spotify or SoundCloud), or the name or id of a file in the audio library.
orderNoWith both say and play: which comes first (default play_then_say).
voiceNoSpeech voice for `say` (default WOMAN).
confirmYesMust be true, set only after the user explicitly confirmed this call (destination and caller ID). If your client supports MCP elicitation, the server asks the user to approve directly and this flag is not relied on; otherwise it is your attestation that the user approved.
languageNoSpeech language for `say` (default en-US).
answer_urlNoYour own URL that returns VobizXML when the call is answered. Not combinable with say/play. Defaults to the server's VOBIZ_DEFAULT_ANSWER_URL.
hangup_urlNoURL notified when the call hangs up (defaults to answer_url; with say/play, to this server's script hangup URL).
time_limitNoMaximum call duration in seconds. Defaults to, and may not exceed, the server's VOBIZ_MAX_CALL_DURATION_SEC.
caller_nameNoCaller name shown where supported (max 50 chars).
ring_timeoutNoSeconds to ring before giving up (default 120).
answer_methodNoHTTP method for answer_url (default POST).
idempotency_keyNoUnique key for this intended call (e.g. a UUID). Repeating it replays the first result instead of dialling again; a new key is the only way to place a second identical call inside the duplicate window.

Output Schema

NameRequiredDescriptionDefault
okNoTrue on success. On a failure the result is isError with ok: false plus `error` (kind), `message`, `retryable` and sometimes `http_status`.
noteNoReminder that acceptance is not connection and how to follow up.
api_idNoVobiz API request id for support queries, or null.
how_toNoPresent with `script`: what happens when the call is answered and how to check whether it was.
scriptNoPresent when say/play was given (or the placeholder greeting is used): what this server's hosted call script plays and in which order.
acceptedNoTrue when Vobiz accepted or queued the call request.
replayedNoTrue when an idempotency_key was repeated and this is the stored result of the first attempt; no new call was placed.
connectedNoAlways false here: acceptance says nothing about the call being answered. Follow it with get_call_status.
time_limitNoMaximum duration in seconds the call was placed with (after the server's cap).
http_statusNoHTTP status Vobiz answered with.
request_uuidNoVobiz's identifier for the call; pass it as call_uuid to get_call_status, end_call and the in-call tools.
backend_messageNoVobiz's own confirmation text, or null when it sent none.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changedv1.4.2
    • changedInput schema / properties / answer_url / description
      Previous value: -"URL that returns Vobiz XML when the call is answered. Defaults to the server's VOBIZ_DEFAULT_ANSWER_URL."New value: +"Your own URL that returns VobizXML when the call is answered. Not combinable with say/play. Defaults to the server's VOBIZ_DEFAULT_ANSWER_URL."
    • changedInput schema / properties / confirm / description
      Previous value: -"Must be true, set only after the user explicitly confirmed this call (destination and caller ID)."New value: +"Must be true, set only after the user explicitly confirmed this call (destination and caller ID). If your client supports MCP elicitation, the server asks the user to approve directly and this flag is not relied on; otherwise it is your attestation that the user approved."
    • changedInput schema / properties / hangup_url / description
      Previous value: -"URL notified when the call hangs up (defaults to answer_url)."New value: +"URL notified when the call hangs up (defaults to answer_url; with say/play, to this server's script hangup URL)."
    • changedInput schema / properties / idempotency_key / description
      Previous value: -"Unique key for this intended operation (e.g. a UUID). Repeating it replays the first result instead of acting again."New value: +"Unique key for this intended call (e.g. a UUID). Repeating it replays the first result instead of dialling again; a new key is the only way to place a second identical call inside the duplicate window."
    • addedInput schema / properties / language
      Added value: +{
      +  "description": "Speech language for `say` (default en-US).",
      +  "enum": [
      +    "da-DK",
      +    "nl-NL",
      +    "en-AU",
      +    "en-GB",
      +    "en-US",
      +    "en-IN",
      +    "fr-FR",
      +    "fr-CA",
      +    "de-DE",
      +    "it-IT",
      +    "pl-PL",
      +    "pt-PT",
      +    "pt-BR",
      +    "ru-RU",
      +    "es-ES",
      +    "es-US",
      +    "sv-SE",
      +    "hi-IN"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / loop
      Added value: +{
      +  "description": "How many times to play the audio (or speak the text when there is no audio), 0..10, default 1. 0 = repeat until the call is hung up.",
      +  "maximum": 10,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedInput schema / properties / order
      Added value: +{
      +  "description": "With both say and play: which comes first (default play_then_say).",
      +  "enum": [
      +    "play_then_say",
      +    "say_then_play"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / play
      Added value: +{
      +  "description": "Audio played when the call is answered: a direct https link to an .mp3 or .wav FILE (not a web page such as Pixabay, YouTube, Spotify or SoundCloud), or the name or id of a file in the audio library.",
      +  "maxLength": 2048,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / say
      Added value: +{
      +  "description": "Text spoken when the call is answered (max 600 characters), e.g. \"Your table is ready.\"",
      +  "maxLength": 600,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / voice
      Added value: +{
      +  "description": "Speech voice for `say` (default WOMAN).",
      +  "enum": [
      +    "WOMAN",
      +    "MAN"
      +  ],
      +  "type": "string"
      +}
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": {},
      +  "properties": {
      +    "accepted": {
      +      "description": "True when Vobiz accepted or queued the call request.",
      +      "type": "boolean"
      +    },
      +    "api_id": {
      +      "description": "Vobiz API request id for support queries, or null.",
      +      "type": [
      +        "string",
      +        "number",
      +        "null"
      +      ]
      +    },
      +    "backend_message": {
      +      "description": "Vobiz's own confirmation text, or null when it sent none.",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "connected": {
      +      "description": "Always false here: acceptance says nothing about the call being answered. Follow it with get_call_status.",
      +      "type": "boolean"
      +    },
      +    "how_to": {
      +      "description": "Present with `script`: what happens when the call is answered and how to check whether it was.",
      +      "type": "string"
      +    },
      +    "http_status": {
      +      "description": "HTTP status Vobiz answered with.",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "note": {
      +      "description": "Reminder that acceptance is not connection and how to follow up.",
      +      "type": "string"
      +    },
      +    "ok": {
      +      "description": "True on success. On a failure the result is isError with ok: false plus `error` (kind), `message`, `retryable` and sometimes `http_status`.",
      +      "type": "boolean"
      +    },
      +    "replayed": {
      +      "description": "True when an idempotency_key was repeated and this is the stored result of the first attempt; no new call was placed.",
      +      "type": "boolean"
      +    },
      +    "request_uuid": {
      +      "description": "Vobiz's identifier for the call; pass it as call_uuid to get_call_status, end_call and the in-call tools.",
      +      "type": "string"
      +    },
      +    "script": {
      +      "additionalProperties": {},
      +      "description": "Present when say/play was given (or the placeholder greeting is used): what this server's hosted call script plays and in which order.",
      +      "propertyNames": {
      +        "type": "string"
      +      },
      +      "type": "object"
      +    },
      +    "time_limit": {
      +      "description": "Maximum duration in seconds the call was placed with (after the server's cap).",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    }
      +  },
      +  "type": "object"
      +}
  2. First observedv1.1.1

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Far exceeds what the annotations convey: the call ends automatically unless loop is 0, an empty call only plays a placeholder and hangs up, success means ACCEPTED/QUEUED rather than connected, idempotency_key replay semantics, duplicate_blocked behavior, and the enforced server policy (country blocks, caps, concurrency, balance, calls_disabled). These are exactly the operational facts an agent needs before a destructive, non-idempotent, open-world call.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Long but densely informative and well front-loaded — the core action and the required-parameter set come first, then workflow, then idempotency, then policy. Every sentence carries distinct operational content, though the sheer length and semicolon-chaining make it heavier than strictly necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 16-parameter, open-world, destructive call tool with an output schema, the description covers what the annotations cannot: the meaning of success, the post-call workflow, idempotency and duplicate handling, and the non-negotiable server policies. Nothing an agent needs in order to call it safely is missing, and return-value detail is correctly left to the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so per the rubric the baseline is 3. The description reinforces the required trio (to, from, confirm) and the 'from must be an active number on this account' constraint, but most of that is already present in the schema field descriptions, so it adds little beyond duplication.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Place ONE outbound call through Vobiz'), including the underlying endpoint, and the 'ONE' emphasis immediately separates it from sibling list/status tools like get_call_status and list_live_calls. An agent can distinguish it from every sibling without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly sequences the whole workflow: follow up with get_call_status using the request_uuid, and once live use speak_text, play_audio, transfer_call or end_call. It also states when NOT to call it ('never call this twice for the same intent; check list_live_calls / list_call_records if the outcome is unknown') and explains the say/play vs answer_url alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools