Copy page

Guides

Tool Variable Writes

When a function-calling tool runs mid-conversation, it can return new values for the agent's dynamic_variables. Subsequent turns then render the prompt template with the updated values — no out-of-band API calls needed. This is Neuratel's equivalent of ElevenLabs' assignments protocol.

When to use this

• Capture a value the user just spoke ("My booking ID is XYZ-123") and reference it in later prompts
• Store the result of a backend lookup so downstream turns can reason about it
• Track multi-step workflow state inside the agent itself (without an external state store)

Tool return shape

Tools normally return a JSON-serialisable value that the LLM gets back as the tool result. To also write to dynamic_variables, return a dict with two top-level keys:

Code
{
  "result": "Found 3 available appointment slots",
  "variable_updates": {
    "available_slots": "2026-05-08 10am, 2026-05-08 2pm, 2026-05-09 11am",
    "lookup_completed": "true"
  }
}

Key	Required	Meaning
result	yes	The value the LLM sees as the tool's output. Any JSON value.
variable_updates	no	Map of {variable_name: value}. Each value is coerced to string before injection (matches dynamic_variables semantics).

Reserved namespace: system__* keys are rejected. Those names are owned by the platform and auto-injected per the system variables catalog. Attempting to write a system__* key drops the write silently and emits a structured warning to the call log.

Reads work the same way they always have

Tools receive dynamic_variables as part of the agent context they call against — no special wire format. If your tool needs to read customer_name it just takes it as a function argument.

End-to-end example

Agent prompt:

Code
You are helping {{customer_name}} book an appointment. Available slots are:
{{available_slots}}

If no slots are listed yet, call lookup_slots(date_range) before proposing times.

Tool definition (your custom MCP server or HTTP tool):

Code
async def lookup_slots(date_range: str) -> dict:
    slots = await your_calendar_api.find_open(date_range)
    return {
        "result": f"Found {len(slots)} slots",
        "variable_updates": {
            "available_slots": ", ".join(slots),
            "lookup_completed": "true",
        },
    }

Initial call with empty slots:

Code
client.voice_sessions.outbound(
    agent_id="ag_...",
    to_number="+12125551234",
    number_id="num_...",
    dynamic_variables={
        "customer_name": "Alice",
        "available_slots": "",  # populated by the tool mid-call
        "lookup_completed": "false",
    },
)

What happens at runtime:

1. Worker renders prompt with empty available_slots. Agent reads the prompt, sees the conditional, calls lookup_slots.
2. Tool returns {"result": ..., "variable_updates": {...}}.
3. Worker merges variable_updates into the live conversation's dynamic_variables.
4. Next turn renders the prompt with the new available_slots. Agent proposes them to the user.

Persistence

Variable writes from tools land on the conversation's dynamic_variables dict (the same one exposed via PATCH /v1/conversations/{id}/dynamic_variables). They survive call boundaries — if the contact calls back tomorrow on the same conversation, the values still apply.

Compatibility with ElevenLabs

ElevenLabs Conversational AI exposes a similar feature called assignments. Tools written for ElevenLabs that return {"result": ..., "assignments": {...}} are accepted by the Neuratel worker as well, with assignments aliased to variable_updates. Migrating an existing ElevenLabs tool is usually a no-op at the tool layer — only your agent prompt template needs updating to match the destination platform's variable references.

Related

• Dynamic variables — caller-supplied per-call variables
• Inbound variable injection — webhook-driven variable population
• Tools and actions — defining custom function-calling tools