Voxta Actions & tools
The two ways the AI invokes something — a dedicated inference pass, or the character calling a tool mid-reply.
Actions and tools are the same object stored the same way. They differ only in who decides to call them:
| Decided by | Right for | |
|---|---|---|
| Action | A dedicated inference pass, at the timing you name | A classification of what just happened — a mood, a gesture, a room change. An answer is needed whether or not the model would volunteer one. |
| Tool | The character itself, while writing its reply | Something the character chooses to do: roll dice, search, open a door. It sees the result. |
The two are exclusive: an action offered both ways would have a pass and the reply deciding the same call, neither aware of the other.
Both live in the scenario's Interactions tab, alongside events, buttons and contexts.
Name
The name is what the model emits. Lowercase letters, numbers and underscores, and it should read as what it does — smile, sit_down, pick_up_phone, not act1.
Description
- Description — what the inference model sees. Say clearly when to pick it. For
sit_down:When {{ char }} wants to sit down or when {{ user }} instructs it. - Short description (optional) — exposed to the character itself so it knows the action exists. Useful for big ones:
move to another room. - Notes — designer notes, editor only, never sent to the AI.
Arguments
An action or tool can declare arguments the model fills in.
| Field | Notes |
|---|---|
name | Required. |
type | string, integer, double, boolean, array, void. |
description | What it means. |
required | Whether the model must supply it. |
choices | A closed set of allowed values, enforced by the schema rather than asked for in prose. |
items type | For array, what it holds. Defaults to strings. |
Prefer one action with a choices argument over six near-identical actions. It costs a fraction of the tokens and the model holds to it more reliably.
Read them in a script with e.arguments.name.
Layers (actions only)
Layers group mutually exclusive actions — only one action per layer fires per turn. Emotions in one, movement in another.
Each layer is a separate inference pass, so every extra layer costs an LLM call. Keep them few.
Final layer stops processing further layers when this action fires. Activates names other actions this one unlocks.
Timing
Actions are evaluated at one of: After user, Before char., After char., After any message, Manually (only via /trigger).
Tools have no timing — there is only the reply. They instead have a control for when what the tool sends the client — an app trigger, the action itself — reaches it:
| When the client is told | |
|---|---|
| With the speech (default) | When the voice reaches the words the tool was called from. |
| Immediately | As soon as the tool is called, while the character is still leading up to it. |
The tool itself always runs and answers at once, so a dice roll can sync: the number reaches the character while the reply is being written, and the clatter plays when the line is spoken.
Pair with the "insert" audio method for a sound that lands between two spoken lines — a dice clatter, a door.
Conditions
Filters that disqualify it even when it would otherwise be offered.
| Condition | Meaning |
|---|---|
| Flags | A flag condition, including $variable comparisons. |
| Match | A regex on the triggering message. Also a cheap way to skip a whole inference layer when nothing relevant was said. |
| Role | Which character may perform it. |
| Once | Sets a hidden _name flag on first fire and adds !_name, so it never fires again in this chat. |
| Chat styles | Only offer it in these chat styles. A roleplay character has no business running shell commands. |
| Disabled | Off without deleting it. |
Effects
- Set flags — same syntax as Flags.
- Note / Instructions / Secret / Event / Story — inject a message. Story takes max-tokens and max-sentences caps, and each has a narrate override.
- Trigger — fire another event by name.
- Contexts — add context entries while the action is active.
- Script — a JavaScript handler with the full
eobject. See Scripting.
Cancel reply drops the reply that was being generated.
Display (tools only)
How much of the call the transcript shows. A tool called every other turn is chrome around the word "ok", and a card for it breaks the scene.
| Display | Shows |
|---|---|
| Card (default) | The full card, with arguments and result. |
| Pill | An inline chip; clicking it opens the card. |
| Minimal | An inline glyph, so the call can be seen running. |
| Hidden | Nothing. Still recorded, still in the inspector. |
A failed call, or one waiting on an Allow / Deny answer, is always shown.
Answering a tool
A tool's script can hand a result back to the character by returning a string from an action:* listener:
chat.addEventListener('action:roll_dice', (e) => {
return `You rolled a ${1 + Math.floor(Math.random() * 20)}.`;
});Defining them from a script
chat.setActions(key, actions) registers actions or tools at runtime — useful when what's available depends on chat state. See Script API → Defining things at runtime.