Prompting guide

Effective prompts make the difference between a voice experience that feels natural and one that confuses users. This guide covers patterns that work well with Scenaro’s feature + tool architecture.

Core principles

One job per turn — ask one question or request one action at a time
Tool-aware instructions — tell the agent when to call each tool and what to say while waiting
Speakable output — write responses meant to be heard, not read
Feature context — reference what the user sees on screen when features are active

Structure your system prompt

## Role
You are a helpful shopping assistant for [Brand].

## Capabilities
- Search the product catalog
- Show product details
- Compare items
- Manage the shopping list

## Tool usage
- When the user asks to find products, call search_collection_items
- When showing a product, call display_collection_item
- Keep speaking while tools execute: "Let me look that up for you"

## Conversation style
- Short sentences, conversational tone
- Confirm understanding before complex actions
- Offer alternatives when search returns no results

Tool call narration

Users hear silence during tool execution unless the agent speaks. Instruct the agent to:

Announce what it’s doing: “I’m searching for red wines under 30 euros”
Summarize results concisely: “I found 5 options, the first is…”
Handle empty results gracefully: “I didn’t find an exact match — want me to broaden the search?”

Feature-aware prompts

When features render UI panels, tell the agent to reference them:

When search results appear on screen, refer to them as "the results I'm showing you"
rather than reading out every item. Highlight the top 2-3 verbally.

Language and locale

Set the scenario language in Cockpit and pass the same BCP-47 tag from the frontend:

const { start } = useScenaroSession({ scenario: PUBLICATION_UUID, language: 'fr-FR' });
// or pass language in start({ language: 'fr-FR' })

Keep prompt language consistent with the session language.

State restoration

If your experience uses state:update checkpoints, include restoration instructions:

If restore_state is provided, acknowledge what the user was doing:
"Welcome back — you were looking at the Bordeaux selection."

Testing prompts

Test in Cockpit live page with real feature registry
Verify tool calls trigger the correct frontend RPC
Check behavior on timeout (slow network, empty results)
Test interruption — user speaks while agent is talking

Anti-patterns

Avoid	Why
Long lists read aloud	Users can’t scan audio — use UI features
Calling tools without narration	Creates awkward silence
Assuming tool success	Always handle ERROR and empty results
Mixing languages	Mismatched STT/TTS/prompt languages degrade quality

​Core principles

​Structure your system prompt

​Tool call narration

​Feature-aware prompts

​Language and locale

​State restoration

​Testing prompts

​Anti-patterns