---
name: parrot-phone
description: >
  Drive real phone calls through the Parrot MCP server (endpoint /mcp). Your
  API key binds ONE phone line; on it you place or answer a call with an AI
  voice agent, watch the live transcript, steer the agent mid-call, answer its
  questions, and collect the structured outcome. Use whenever the user wants to make/receive an actual
  phone call, run a phone task ("call X and ask/book/confirm …"), or supervise
  a call in progress.
---

# Driving phone calls over the Parrot MCP

Parrot places and receives REAL phone calls on physical phone lines. You give a
line a task in plain language; an AI voice agent conducts the conversation; you
supervise it live. This skill is the operating manual — the tool docstrings
carry the parameter details.

## Mental model

- **device** — one physical phone line. **Your key IS the device selection**:
  every tool operates on the one line the key was created for — there is no
  list_devices and no device_id parameter anywhere.
- **call** — one phone call on the line (`call_id`). ONE call at a time;
  parallelism = multiple keys (one per line), each as its own MCP server entry.
- **objective** — the task in plain language; compiled into the voice agent's
  prompt for that call.
- **steering** — a silent instruction into a live call (`steer_call`); the
  remote party never hears it.
- **events** — the call's append-only stream (transcript, tool calls, admin
  messages, state changes), read via `get_call_events` with an opaque `cursor`.

Two facts that surprise people:

1. **`peer_number` can be null** — caller ID may arrive late or never. Never
   wait for it; answer/proceed and let the agent ask who's calling.
2. **The `cursor` is opaque.** Echo back exactly what the server returned
   ("" to start). The server handles new-call rollover — no seq bookkeeping.

## Outbound call — the canonical loop

```
1. get_device_status → confirm online, bt_connected, call_state="idle"
2. place_call(to_number, max_duration_s=…, objective="…", context="…")
     → {call_id, state: "RINGING"}
3. loop: get_call_events(cursor=<last cursor>, wait_seconds=25)
     - read transcript (role "user" = remote party, "assistant" = agent)
     - steer_call("…", urgency="soon") if the agent is stuck
     - exit when call_ended == true      (do NOT sleep between polls)
4. get_call_result(call_id)   # immediate — inspect outcome/retryable,
                              # reports = the agent's distilled findings,
                              # summary = optional AI recap (may be null)
```

`max_duration_s` is REQUIRED (hard hang-up cap; server clamps to the account
ceiling). Most calls need zero steering — the agent reports via
`report_to_admin` and hangs up on its own.

**Joining mid-call / resuming after context loss:** `get_call_status(call_id)`
returns a compact snapshot — state, `transcript_tail`, `pending_request_info`,
`last_event_age_s`, and a `cursor` you can feed straight into `get_call_events`.

**Filtering:** `get_call_events(types="transcript,request_info,state")` skips
noise permanently; if you filter, KEEP `request_info` in the set.

## Voice-agent questions (request_info)

Mid-call the voice agent can ask YOU for information it lacks. The question
arrives as a `request_info` event `{query_id, query}`. Answer it explicitly:
`respond_to_request_info(call_id, query_id, answer)` — within ~60s, or the
agent continues without it. No client gets an automatic form.

## Inbound call

An ESP32 board answers every ring itself (hands-free pickup) with the line's
bound assistant, and the call appears in `get_call_events`. To change which
assistant answers, call `configure_device(assistant_id=…)` before the next ring.

On Parrot App for Windows, automatic answering is a setting that starts off.
With it off the line rings until answered, and you are the router — within the
carrier's ~20 s ring window:

```
1. get_call_events(wait_seconds=25)                 # idle watch, wakes on RING
2. decide from peer_number (your judgment — lookup/CRM/heuristic)
3. answer_call(assistant_id="…" | assistant={…} | objective="…")
     # per-call override, cleared at call end — never leaks to the next call
```

There is no number-routing table on the server, by design. `configure_device`
sets the STANDING assistant (persists across calls); per-call overrides on
`answer_call` do not.

## Assistants & per-call overrides

- **`objective` (recommended)** — fills only the task slot (`{{OBJECTIVE}}`)
  of the effective assistant: `assistant_id` if given, else the line's bound
  assistant. Its guardrails stay intact. `context` / `caller_identity` fill
  sibling slots. A slot the prompt lacks has no effect; the call still runs.
- **`assistant_id`** — run a saved assistant (list_assistants / get_assistant
  to discover).
- **`assistant={…}` — inline temporary assistant.** create_assistant's
  authoring fields (objective, system_prompt, opening_line, provider, model,
  voice, language, first_speaker, temperature, template_params) layered
  over the base for THIS call only, never saved. Equivalent to
  create→use→delete. Unknown fields fail loud.
- **`system_prompt` (nuclear)** — replaces the ENTIRE prompt; all scaffolding
  gone, restate everything yourself.

Authoring SAVED assistants (create/update/delete, model/voice options) requires
explicit OAuth approval at `/mcp/assistants`. For both calling and authoring,
use the Console's device connection at `/mcp/devices/<device_id>`; approval is
locked to that line. Ordinary device API keys do not grant saved-assistant writes.
Calling-only OAuth uses `/mcp/devices/<device_id>/calls` and locks the same line.
Assistant-only `/mcp/assistants` is an account permission with no device binding;
it remains usable when no phone lines are attached or their ownership changes.

## Outcomes & retry

`get_call_result` → `outcome` + `retryable` describe the call deterministically:
`answered` (read reports/transcript to check the task) ·
`needs_human` (escalated; redial won't help) · `no_answer` (retryable) ·
`agent_hangup` (inspect transcript; usually a task issue) · `error`
(check the returned retry guidance and error details). An older call record may
have `outcome: null`; inspect the transcript and line status before retrying.
Full mapping:
[call-end taxonomy](https://parrotvoice.app/docs/call-end-taxonomy/).

For structured fields, run a saved assistant that defines `extract_schema`:
`get_call_result` then carries the optional, asynchronous `extracted` fields.
Or analyze the returned `transcript` yourself. MCP exposes the text transcript
only; call recordings are available through the REST API.

## Errors — route on the code

`device_offline` (the line's bridge is down — report upstream; another line means another key) · `device_busy` (includes blocking
call_id) · `bt_not_connected` (phone out of BT range — report upstream) ·
`dial_timeout` (retry once) · `not_found` · `invalid_cursor` / `invalid_types`
(malformed poll args) · `invalid_assistant_field` / `unknown_provider` (bad
inline assistant) · `parrot_unreachable` (operator problem).

## Operating expectations

- One call per device; configuration changes apply between calls (`steer_call`
  is the only mid-call lever).
- Calls are recorded server-side (audio + transcript) keyed by `call_id`.
- Honesty policy: the agent admits it's an automated assistant when asked;
  objectives requiring it to lie about that will not work.
