# Designing a voice configuration ## From sources to a flow Build a compact table: intent → source/section → prerequisites → known/missing slots → decision nodes → branch outcomes → tool/knowledge dependency → stop or handoff. Separate approved policy from diagrams, proposed behavior and demo copy. A workflow diagram is evidence of structure, not proof that its numeric thresholds, SLA or backend action exists. Resolve conflicts explicitly; don't silently turn a guessed value into policy. Test every branch and terminal node of a multi-step workflow. A large FAQ set can still miss entire steps. Preserve node order and determine the **next** action from the user's current state, rather than replaying the whole checklist. ## Instructions versus runtime Skills When a demo intentionally collects only a fixed set of fields, state that set and the completion condition explicitly; otherwise the model may invent extra intake questions. Global instructions: identity, supported scope, priority of urgent requests, brief oral language, one missing question at a time, reuse corrected/known fields, no spoken tool names/JSON/XML, truthful tool results, direct ending after an explicit final goodbye. Runtime Skill: one coherent intent or procedure; description makes routing distinguishable, body contains preconditions, next step rules, branching, stop conditions, relevant facts and exact tool dependencies. Prefer coherent units over one huge prompt or many overlapping fragments. If several intents are active, define priority and return to unfinished work after resolving the urgent one. Template: ```markdown --- name: service-booking description: Handle requests to arrange a service visit, including corrections and cancellation before submission. --- ## Source and scope Use the supplied approved booking policy; unknown locations or times must be checked. ## Flow Collect only missing service type and preferred time. Reuse confirmed fields. Before a write, summarize the action and obtain the required user confirmation. Use the actual available booking tool; say booked only after its confirmed success. If no execution tool exists, explain that a booking has not been submitted. ## Exceptions On timeout, say status is unconfirmed and query status before retrying a write. On cancellation, stop the pending action. Do not invent refund or cancellation policies. ``` No executable scripts in runtime Skill Markdown. `preload:true` reduces Skill-read round trips but increases prompt context; on-demand reading can help larger libraries. Compare on your actual case mix. Don't claim guaranteed cache hits or a fixed latency improvement. ## Tool and MCP contracts For each real tool capture: exact name, input schema, required/optional fields, read/write nature, confirmation, tenant/user authorization, success fields, failure/timeout behavior, idempotency and status-query capability. Use the actual service schema, not a made-up function that appears executable. A read result grounds the reply. A write requires real authorization and confirmed success. Pending/timeout is not failure or success; avoid blind retries that duplicate a booking/message. Speak a short natural acknowledgement only if needed; don't read implementation names. Unavailable handoff/SMS/dispatch cannot be described as completed. MCP registration is optional. Direct session.tools remote MCP is possible; allowlist the needed tools and preserve approval policy. A URL without successful tool discovery does not establish usability. For native client function tools, the application executes and returns the result; the model itself doesn't execute business actions. ## Voice-specific decisions - Keep opening greeting separate from system instructions where the channel supports it. Without a configured greeting, first audio can wait for an idle reminder. - One concise question per turn; don't reread long policy unless requested. Split a long procedure into the next actionable step. - Spoken ambiguity, correction and interruption must preserve slots and avoid duplicate execution. - Noise/partial recognition should trigger a short clarification, not a destructive action or hangup. - Respect a clear final goodbye without forced “anything else?” loops. Actual hangup needs a supported channel action, not merely words in a prompt. - VAD silence threshold, idle reminders and model timeout are different controls. Change one variable at a time, with the same recording/case set. Lower VAD can clip pauses; longer VAD increases turn delay. - Don't claim prompt edits fix media packet loss or TTS chunk gaps. Diagnose the layer before tuning. ## Version and apply First build: concise full config. Revision: smallest supported patch or client-side merge into fetched config, preserving unrelated values. Do not assume the server supports RFC7396 PATCH: follow its actual PUT/revision contract. Record old/new revision, changed behavior and rollback target. Validate then publish a new version if needed; update telephone bindings only when explicitly in scope.