Define tools that your agent can call during the conversation.

​
Tool Types

​
1. Lookup Tools

Retrieve information (account balance, transaction history, eligibility).

​
2. Action Tools

Perform an action (schedule callback, create ticket, process payment).

​
3. Context Tools

Update agent state (set variable, change language, end call).

​
Define Each Tool

Tool Name: lookup_account_balance When to call: If the user disputes the amount, call this tool first to verify. Parameters:
  • account_id (required) — Customer account identifier
  • date (optional) — Balance as of this date
Expected response: Amount due, due date, payment status What to do with the response:
  • If balance matches agent’s knowledge: confirm with user.
  • If balance differs: acknowledge the discrepancy, explain the amount on file, and offer escalation.

​
Agent vs Internal Variables

Agent variables — accessible to the agent during the call. Example: [[ customer_name ]], [[ amount_due ]] Internal variables — system variables, not part of agent context. Reference these in your logic, not in conversations.

​
Message Patterns

​
message_to_user

What the user hears. Example: “Thank you for confirming. We’ll schedule the callback for Monday.”

​
message_to_llm

Internal context for the agent (what happened, next steps, flags). Example: “Callback scheduled for Monday 10 AM. Move to end_call state.”

​
Tool Definition Template

## Tool Name: [tool_name]

**Purpose:** [One sentence describing what this tool does]

**When to call:** [Conditions under which this tool should be invoked]

**Parameters:**
- `param1` (required) — Description
- `param2` (optional) — Description

**Expected response:** [What the tool returns]

**What to do with the response:**
- If [condition A]: [Action A]
- If [condition B]: [Action B]
- If error: [Fallback action]

​
Best Practices

  1. Call tools before deciding — Sequence: Call tool → wait for response → act on it.
  2. Name tools clearly — Use snake_case: lookup_product, create_ticket
  3. Handle tool failures — Always have a fallback if the tool returns an error.
  4. Minimize tool calls — Only call tools when necessary. Each call adds latency.
  5. Test tool responses — Verify that the tool returns what you expect before using it in production.