Docs/Concepts/Tools (Skills)

Tools (Skills)

Tools are the agent's hands. Without tools the agent can only talk. With tools it can check a calendar, write to your database, send an email, hand off to a human. The tool catalog is shared across all tenants; each tenant picks which subset is enabled.

The tool catalog

The current platform ships with skills across four categories: scheduling, knowledge, escalation, and lead capture.

Tool	Purpose
`book_slot`	Create a booking in the calendar after the user confirms time, service, and contact.
`check_availability`	Search free slots in a date range. Returns up to 3 candidates.
`cancel_interaction`	Cancel an existing booking by phone + approximate time.
`reschedule_interaction`	Move an existing booking to a new time.
`escalate_to_human`	Flag the conversation for operator pickup. Surfaces handoff CTA to the user.
`lookup_data`	Semantic search over the knowledge base for the current query.
`send_quote`	Generate and send a structured price quote to the user.
`collect_intake`	Collect a multi-field intake form (lead qualification).
`log_lead`	Record a lead in the CRM without booking.
`send_reminder`	Schedule an outbound reminder for the user (24h / 1h before slot).

Tool execution is rolled out per category; see Status for the channel and capability rollout schedule. Each enabled tool surfaces to the model as a structured function call with typed parameters and a server-side handler.

How tool calls flow

The pipeline for a tool call is:

The user sends a message.
The platform classifies the intent (FAQ, booking, cancel, ambiguous).
For booking-class intents, the platform calls Gemini with the enabled tools as function declarations.
Gemini either replies in natural language or emits a functionCall.
The platform dispatches the function call to the matching server-side executor. The executor runs (DB write, external API call, etc.) and returns a structured result.
The result is fed back to Gemini for one more turn — the model summarizes the action in natural language.
The summary is saved and emitted to the user.

Enabling tools per org

In the dashboard go to /dashboard/agent → Tools. Each tool has a toggle. Toggling on writes to organizations.tools_enabled (a JSONB array of { tool_id, intake_fields_override?, params?: {} } objects).

// Example tools_enabled value (from organizations.tools_enabled JSONB)
[
  { "tool_id": "book_slot" },
  { "tool_id": "check_availability" },
  { "tool_id": "cancel_interaction" },
  { "tool_id": "escalate_to_human" },
  { "tool_id": "lookup_data" }
]

Custom tool descriptions

Each tool ships with a default description that the platform renders into the system prompt with personality variables interpolated. The placeholders {{role}} and {{escalation_triggers_summary}} resolve from your personality, so a description like "Use when {{role}} should stop and hand off" reads naturally inside any tenant's prompt.

Intake fields per tool

Tools that collect user data (booking, intake) ship with a default field set: name, phone, email, service, preferred_time. You can override per-tool via intake_fields_override when enabling — e.g. add vehicle_make for an auto-repair agent.

Error handling

Every personality includes a standard tool error handling block: if a tool call fails, acknowledge → do not fabricate → retry once → after two failures, escalate (when escalate_to_human is enabled) or collect contact for callback (when it is not). The block is platform-controlled and identical for every tenant.