Skip to main content
Glama

Hail Communication for AI

Place a phone call

place_call

Start an outbound AI phone call.

    At least one of ``system_prompt``, ``llm`` or ``agent_id`` is required.
    US artificial-voice calls (47 CFR 64.1200(b)(1)) require the AI disclosure.
    Hail does not verify the lawful basis or the recipient's consent.
    A 4xx response returns no ``idempotency_key``.

    Returns the call ID, status, phone numbers and ``idempotency_key``, or an error.
    

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "to": "<to>",
      "recipient_consent": "<recipient_consent>"
    },
    "name": "place_call"
  }
}

Input Schema

NameRequiredDescriptionDefault
toYesRecipient phone number in E.164 format, such as ``+14155551234``.
llmNoOwn model endpoint compatible with OpenAI's chat completions API: ``{base_url, api_key, model}``. Omitted: Hail's bundled model.
from_NoCaller ID: an E.164 workspace number with voice, from ``list_numbers``. Omitted: an active workspace number, else one from the shared pool.
toolsNoNames of the agent tools allowed on this call. An empty list disables them. Omitted: every tool the workspace's channels support.
agent_idNoSaved agent whose settings the call uses, from ``list_agents`` or ``create_agent``. Explicit arguments override its settings.
languageNoSpoken language as a supported lowercase ISO 639-1 code, such as ``es``. Omitted: English. An unsupported code returns 422.
metadataNoFree-form JSON object stored on the call record. Keys starting with ``recording_`` are reserved.
llm_modelNoModel ID of the calling agent. Optional. Recorded for analytics only.
message_typeNo``informational`` for transactional or service messages, or ``marketing``.informational
ai_disclosureNoSpeak an AI notice at the start of the call. ``false`` skips it.
first_messageNoLine spoken on pickup. Without it, the agent reacts to the answer or silence.
system_promptNoTask instructions, added to the call agent's instructions.
consent_sourceNoWhere or how consent was obtained, such as ``signup form``. Required when ``message_type`` is ``marketing``.
idempotency_keyNoRetry key. The ``idempotency_key`` from an earlier response refers to that original request instead of starting a new one. Omitted: a new key is generated and returned.
recipient_consentYesAttestation that the recipient lawfully agreed to be contacted, as the user confirmed it. Hail does not check it; only ``true`` is accepted.
recording_enabledNoRecording for this call, overriding the agent and workspace settings.
consent_obtained_atNoWhen consent was obtained, as an ISO 8601 timestamp, if known.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / llm_model
      Added value: +{
      +  "description": "Model ID of the calling agent. Optional. Recorded for analytics only.",
      +  "type": "string"
      +}
  2. Changed1 schema field changed
    • changedInput schema / properties / recipient_consent / description
      Previous value: -"Attestation that the recipient lawfully consented to this contact. Only ``true`` is accepted."New value: +"Attestation that the recipient lawfully agreed to be contacted, as the user confirmed it. Hail does not check it; only ``true`` is accepted."
  3. First observed

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare this is a non-read-only, open-world, non-idempotent operation, so the bar is lower; the description still adds meaningful context by disclosing that Hail does not verify lawful basis or consent, that a 4xx response yields no idempotency_key, and what a success returns. It stops short of covering cost, rate limits, or what happens to an in-flight call on retry.

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?

Front-loaded with the core action, then constraints, then return shape — a sensible ordering. The legal citations are slightly dense but each sentence carries operational or compliance information rather than filler.

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

Completeness4/5

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

For a 17-parameter mutation with an output schema, the description covers the critical gating constraints (required-one-of, consent attestation, disclosure) and defers return-value detail to the output schema. Minor gaps remain around failure modes other than 4xx and retry semantics.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds a genuine cross-parameter constraint not expressible in the schema: at least one of system_prompt, llm or agent_id must be supplied. That is real meaning beyond the field-level descriptions.

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?

"Start an outbound AI phone call" gives a specific verb (start) and resource (outbound AI phone call), which cleanly separates it from retrieval siblings like get_call and list_calls without needing to name them.

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

Usage Guidelines3/5

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

The description supplies real preconditions — at least one of system_prompt, llm or agent_id is required, and US artificial-voice calls need the AI disclosure — but it never states when to choose this tool over alternatives or what situations make a call inappropriate beyond the legal caveat.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources