How to fix an overloaded voice-agent prompt.

What actually went wrong on the call?

Find out before you shorten anything. “The prompt is too long” is too vague to fix; “said the booking worked when the tool timed out” isn’t. Name each failed turn that plainly, then find the instruction, missing state or tool that should have prevented it. If one rule appears in several contradictory forms, editing only the last one keeps the contradiction.

GET /v2/agents/{id}/logs helps. It lists tool runs and errors, each call’s variables, the post-call analysis, and a tool_missing warning when the model asked for a tool the agent doesn’t have, usually because the prompt names one you never added. /logs/summary counts problems by part.

What belongs in the prompt, and what doesn’t?

Prompt content	Better home
Role, speaking style and shared stop behaviour	A short, stable instruction core
The current goal and the next missing fact	The current task, or the current node’s prompt
Confirmed details and their revisions	Typed application state
Policy documents and large tool payloads	Retrieved on demand, or reduced to the fields needed
Permissions, idempotency and action prerequisites	Checks on your server

Your code enforces permissions, for example in a guarded transition, and the prompt only explains them. Tool output and retrieved text are data, even when they read like orders.

Some lines can go, because the engine already does the job: it plays the opening line, ends the call on a refusal when end_call is on, handles barge-in and silence, and fills placeholders. Our prompting guide has the list. “Wait for the user to finish speaking” only spends tokens.

How do I fix a prompt that contradicts itself?

Decide which rule wins, and write it down. Here’s a deliberately bad, made-up appointment prompt:

Always finish booking. Never end without an appointment.
Respect the caller if they want to stop.
Ask for the date, then ask for the time. Always follow that order.
Do not repeat questions. Confirm every detail repeatedly.
If booking times out, try again until it works.
Always sound confident and say the booking is handled.

A bigger context window won’t help. “Always finish” fights with stopping, a fixed question order ignores what the caller already said, and “try again until it works” ignores whether the first attempt went through. Replace it with something scoped:

Role: Help the caller arrange an appointment. Keep replies brief
and natural in the caller's language.

Priority: A request to stop or speak to a person overrides booking.
Never claim an action succeeded without a matching tool result.

Current task: Collect the missing appointment preference.
Use validated state for facts already provided. Ask one focused
question about what is missing. If the caller corrects a fact,
submit the correction before asking the next question.

Do not create an appointment in this step. The application will
offer available slots and collect confirmation in later steps.

That’s the shape of a fix, not a tested prompt; the workshop has the tests around it. Never let a prompt promise an action no tool performs. Transfer to a person isn’t available yet, so “the team will call you back” is the honest line.

What happens when the caller changes their mind?

Give the preference a revision number, and tie availability results and confirmations to it. When “Tuesday” becomes “Thursday”, bump the revision and drop what depended on Tuesday. A late tool response counts only if its revision still matches, and an interruption cancels stale audio. After a timeout, check whether the request failed or its result is unknown before you retry with the same operation key. The architecture guide shows where these checks go.

How do I know the rewrite helped?

Run old and new on the same scenarios and settings, and count tokens with the deployed tokenizer, tool definitions included. Keep two to four turns of the hardest moment done right, as our prompting guide suggests, because models copy tone from examples better than from adjectives.

Track task completion, false success claims, bad tool arguments, repeated questions, recovery turns, first useful output and call length. Caching is a separate effect; our context guide covers prompt layout.

What should my regression set look like?

Start with the 12 cases we wrote. Log each run’s starting state, input, reply, tools, resulting state and a reviewer’s verdict with a reason. Repeat runs, and test the state machine apart from the language.

Report critical failures one by one, with sample size and repeats, so a double booking can’t hide in a good average. Add real failures, without identifying details, from webhooks sent with final_results: true, which carry the transcript in one event.