# The call brief

`voice_engine.brief()` builds one document per call — the persona, the line's purpose, the contact's facts and standing instructions, knowledge, the hard rules and any supervisor guidance — and hands it to the model once. Its size is recorded as `session.instructions_chars`, because size is measurably latency: 7,500 characters gave a 1.2–1.8 second first token and 9,600 gave 2.3–3.4.

- **Status:** Available
- **Audience:** both
- **Channels:** phone
- **In the app:** #/calls
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/phone/call-context/

## One document, built once, in one place

The voice worker carries audio and posts events. It holds no business logic, knows no rules and looks nothing up. Everything it needs is rendered by the engine before the call and delivered as instructions, which is what makes the same behaviour reachable from the carrier path, the realtime path and a test call in the Lab without three implementations of it.

- **Persona** — who the voice is, including a [human voice profile](/docs/phone/human-voice-profiles/) if one is assigned.
- **The line's purpose** — inbound, service, transactional or promotional. There is no campaign object; purpose is the axis.
- **Contact facts and standing instructions** — what is known about this person and what somebody has told Connect to do about them.
- **Knowledge** — grounding drawn from the workspace's own sources.
- **The language rule** — two or three lines written by `voice_region.plan` from what is known about this caller: which language to reply in, what evidence moves it, and how to sound like a courteous local professional when it is not English.
- **The hard rules** — the boundaries that do not bend, including what must never be said.
- **Supervisor guidance** — anything a colleague has already added for this call.

The behaviour texts around those — role, goal, tone, style, what to ask and never ask, objections, escalation, opening, closing, proactiveness, switching, memory use — come from the Voice Lab's `behaviour_block`, and the speaking directions from `style_block`.

## The budgets

| Part | Budget |
|---|---|
| Knowledge | 4 facts / 2,000 characters |
| Memory | 700 characters |
| Contact block | 600 characters |
| Human voice profile block | under about 2,500 characters |

These are not style guidance. Instruction size is on the record for every session precisely so the relationship between size and first token stays visible, and the two measured points — 1.2–1.8 s at 7,500 characters, 2.3–3.4 s at 9,600 — are what the budgets were set against. A caller pays that difference on every single reply.

> **Careful** The parts that grow quietly are knowledge and contact facts. Neither has a person watching it, both feel free to add to, and the symptom of overspending is not an error — it is a line that has become slightly slow, on every call, for reasons nobody connects to a document they edited last month.

## Changing something mid-call

The brief is rendered once, so anything added later has to travel another way, and there are two with very different costs.

**`agent.update_chat_ctx`** — A user-role turn taken without generating a reply. Small, cheap, and how a steering note, a read-back note and the 12-turn anchor note all arrive.
**`update_instructions`** — Resends the **whole** prompt. Kept for supervisor guidance only, because re-sending several thousand characters mid-call is exactly the cost the budgets exist to control.

On Gemini 3.1 Flash Live neither is available: the SDK marks the session immutable, notes come back undelivered and guidance is recorded as `guidance_undeliverable`. On that model the brief is the whole conversation's instruction set, which raises the stakes on getting it right before the call rather than steering during it.

## What the brief is not

- It is **not** a transcript store. What has been said accumulates in the session's context, and that context is re-billed on every turn — production calls run at about 92% carried context by input token.
- It is **not** a retrieval loop. Knowledge is selected before the call, not fetched mid-sentence, which is why the four-fact cap is a real constraint rather than a first page of results.
- It is **not** where the greeting lives. That is deterministic text, pre-synthesised as audio; the instructions merely say the opening has already been spoken.

This page was reconciled on 2026-09-10 against `backend/app/voice_region.plan` at `f5ea518`. The structure, the budgets and the delivery mechanisms are unchanged. The contact-facing language lines are the part that moved: they now carry a different evidence bar depending on what is known — nothing moves a pinned call, a whole sentence moves a remembered or unknown one, and two or three words move one where the contact's city or state made a language likely. Nothing in the brief offers a language or quotes a sample phrase, because on a production call an earlier brief's sample was read out to the caller word for word.

## Questions

### Can I see the brief that was used on a particular call?

Its size is recorded per session as `instructions_chars`, and the resolved voice settings are snapshotted on `call.quality` so the review judges what actually ran. Those two together answer most questions about why a given call behaved as it did.

### Why cap knowledge at four facts when the workspace has hundreds?

Because they would all be paid for on every reply, and because a model given twenty facts about a subject answers less precisely than one given the four that matter. The cap forces the selection to be good rather than generous.

### Is the brief different for the Owner and for a customer workspace?

No. It is one renderer with two routes into it, which is the general shape of the phone system — the seam is one body and two doors, not two implementations that have to be kept in step.

## Related

- [A returning caller](https://connectbyjbrh.com/docs/phone/returning-caller/)
- [Reply latency on a call](https://connectbyjbrh.com/docs/phone/latency/)
- [The Voice Lab](https://connectbyjbrh.com/docs/phone/voice-lab/)
- [Steering a live call](https://connectbyjbrh.com/docs/phone/supervisor/)
- [What every character of a prompt costs on a live call](https://connectbyjbrh.com/research/prompt-size-and-first-token/)

## What this page is based on

- Reconciled 2026-09-10 against `f5ea518` — `backend/app/voice_region.plan`, read from the code rather than its docstring
- Connect phone source pack — `docs-source/sources/PHONE.md` §3, what `brief()` renders
- Connect phone source pack — `docs-source/sources/PHONE.md` §6 and §7, behaviour blocks, budgets and note delivery
- Connect capability registry — `docs-source/facts.py` (`MEASURED`, `realtime_voice`)