Skip to main content
A tool is an action the agent can invoke mid-conversation. The LLM decides when to call a tool based on its name, description, and the parameter schema you provide. Tools are configured in the Abilities section of the agent editor.

​
Tool anatomy

Every tool has:
FieldPurpose
nameIdentifier the LLM uses (e.g. transfer_to_billing)
descriptionWhat the tool does and when to use it — the LLM reads this
propertiesJSON Schema of parameters the LLM must fill
requiredWhich properties are mandatory
actionsThe concrete actions taken when the tool fires
actions_on_errorFallback actions if the primary actions fail
The description field is the most important. The LLM only invokes the tool when the description matches the conversation context. Be explicit: ✅ "Use this when the caller asks to speak with a human, mentions a billing dispute, or asks a question outside the scheduling scope." ❌ "Transfers the call."

​
Built-in actions

When a tool fires, it runs one or more actions in sequence. Available actions:
ActionWhat it does
play_messageSpeak a fixed message before continuing
play_audioPlay a pre-recorded audio file
cold_transferTransfer to another number, hang up
warm_transferTransfer with the agent staying on the line briefly
conferenceAdd a third party to the call
dtmfSend DTMF tones (for IVR navigation)
waitPause for N seconds
hangupEnd the call
leave_roomDrop the agent from a multi-party call
stop_audioStop audio started by play_audio
update_endpointingChange the turn-detection endpointing delay mid-call
workflowInvoke an Anyreach workflow
knowledge_baseRun an explicit KB query
Each action can carry a condition expression so it only runs when the condition holds. In the async text and email engine only workflow, knowledge_base, and play_message run; the telephony and audio actions are skipped. For the full field-by-field reference see Abilities and actions; transfers have their own page in Call transfers and conference. You can chain actions. For example, a “transfer to billing” tool might be: play_message("Connecting you to billing now") → cold_transfer("+15551234567").

​
Workflow tools

Exposing a workflow as a tool is the most powerful pattern in Anyreach. The workflow can do anything — call APIs, run code, branch on AI — and return a result the agent uses.
1

Build and publish a workflow

See the workflow builder tour. The workflow’s input schema becomes the tool’s parameter schema.
2

Add it to the agent

Abilities → Add tool → Workflow. Pick the workflow and a published version (or “latest published”).
3

Map parameters

The workflow’s input fields appear as tool parameters. Edit names and descriptions if you want them to read better to the LLM.
4

Decide on output handling

The workflow’s output is returned to the agent. Decide whether the agent should speak the result verbatim, summarize it, or use it silently to inform the next turn.

​
Example: look up an order

Workflow input: order_number: string → HTTP step calls your order API → Output step returns { status, ship_date, items }. In the agent prompt, instruct: “When a caller asks about their order, ask for their order number, then call lookup_order. Tell them the status and shipping date.” The LLM will fill order_number from the conversation, invoke the tool, get the result, and weave it into a natural response.

​
Knowledge base tools

Even though knowledge bases are queried implicitly when attached to an agent, an explicit knowledge_base tool is useful when:
  • You have multiple KBs and want the LLM to choose between them
  • You want the agent to announce it’s looking something up (“Let me check on that…”)
  • You want different top_n values for different question types
Configuration:
FieldPurpose
dataset_idWhich KB to query
queryExpression that builds the search query (often ${last user utterance})
top_nHow many chunks to retrieve. Default 5

​
Error handling

Set actions_on_error for any tool that can fail. A common pattern: 
actions: [workflow → lookup_crm_record]
actions_on_error: [play_message("I'm having trouble looking that up — let me get a human.")]
                  [cold_transfer("+1555...")]
Without this, a workflow failure produces an awkward silence.

​
Limits

  • An agent can have many tools, but each tool’s description is in the system prompt at every turn. More than ~15 tools tends to dilute selection accuracy.
  • Workflow tools have a soft latency budget of ~2-3 seconds before the caller notices a pause. Use play_message to fill silence on slower workflows.