---
summary: "Configure how the bot talks \u2014 formality, verbosity, empathy, vocabulary,\
  \ scope \u2014 without writing a system prompt."
title: Tone
path: concepts/tone
status: published
---

# Tone

The bot's "voice" comes from a small set of structured fields. ScaiBot compiles those into the system prompt; you never write one directly.

## Fields

```json
{
  "persona_name": "Sam",
  "persona_description": "A friendly product support specialist at Acme.",
  "formality": "casual",
  "verbosity": "concise",
  "empathy_level": "high",
  "language": "en",
  "terminology": ["Acme", "Widgets", "Acme Cloud"],
  "topics_in_scope": ["product features", "pricing", "account management"],
  "topics_out_of_scope": ["legal advice", "competitor comparisons"],
  "custom_instructions": "Always offer to escalate if the user mentions billing issues."
}
```

| Field | Type | Effect |
|---|---|---|
| `persona_name` | string | The name the bot uses for itself ("I'm Sam from Acme Support"). |
| `persona_description` | string | A one-sentence role; sets context. |
| `formality` | `formal` / `neutral` / `casual` | Word choice and sentence rhythm. |
| `verbosity` | `terse` / `concise` / `verbose` | How much it elaborates. Default `concise`. |
| `empathy_level` | `low` / `medium` / `high` | How much it acknowledges feeling. |
| `language` | ISO 639-1 / locale | Primary response language. |
| `terminology` | string[] | Words it prefers (and won't paraphrase away). |
| `topics_in_scope` | string[] | Reinforces what the bot is for. |
| `topics_out_of_scope` | string[] | Things to deflect. |
| `custom_instructions` | string | Anything else, plain English. |

## How it's applied

Every time the bot is about to call inference, ScaiBot assembles:

1. A skeleton derived from the persona, formality, and verbosity (the "voice").
2. The terminology and scope as constraints.
3. The `custom_instructions` verbatim.
4. The retrieved knowledge chunks (if RAG is on).
5. The conversation history (recent turns, capped by `max_context_messages`).
6. The current visitor message.

That's the system prompt. It's not visible to you in the API by default — pass `?include_system_prompt=true` to chat-completions if you want to see it for debugging.

## Previewing a tone change

You can preview a tone before saving it:

```bash
curl -X POST "$SCAIGRID_HOST/v1/modules/scaibot/bots/$BOT_ID/tone/preview" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tone": { "formality": "formal", "verbosity": "verbose" },
    "sample_message": "What are your refund terms?"
  }'
```

Returns a single non-streamed response generated with the proposed tone, against the bot's current knowledge. Good for A/B testing voice changes before deploying them to live visitors.

## Languages

The bot's primary `language` is what it defaults to. If a visitor writes in a different language, the bot usually follows them — set `strict_language: true` on the tone if you want it to insist on the configured language regardless.

For multi-language deployments, prefer one bot per language with its own tone and knowledge base. Cross-language retrieval is supported (embeddings are multilingual) but tone tuning suffers when the bot constantly code-switches.

## When to use `custom_instructions`

`custom_instructions` is the escape hatch. Use it for:

- Brand-specific rules ("Never say the word 'cheap'.")
- Process anchors ("If the user mentions a contract number, ask which product line it's for before answering.")
- Disclaimer requirements ("End every response that mentions pricing with 'Prices subject to change.'")

Don't use it for things the structured fields already cover — `formality: "casual"` reads more reliably than "be casual" in `custom_instructions`.

## What you can't override here

- The model — set on the bot itself, not in tone.
- Token limits — set on the bot (`max_tokens_per_response`).
- Retrieval behaviour — set under `knowledge_settings`.
- Escalation — separate rules.

This is intentional: tone is the bot's voice, not its mechanics.