Creating Tools

Custom tools let you connect your bots to any HTTP API. Once created, a tool can be called by name from any bot flow or invoked autonomously by the LLM during agentic conversations.

Step 1: Navigate to Tools

Open the Tools page from the left sidebar navigation. You will see two sections: System Tools (built-in, read-only) and Custom Tools (your tenant's tools).

Click Create Tool in the top-right corner to open the tool editor.

Step 2: Basic Information

Fill in the identification fields:

Field	Description	Example
Tool ID	A unique machine-readable identifier. Lowercase letters, numbers, and underscores only. Cannot match a system tool ID.	check_order_status
Name	A human-readable display name shown in the UI and to the LLM.	Check Order Status
Description	Explains what the tool does. The LLM reads this to decide when to call the tool, so be specific.	Look up the current status of an order using the order ID or tracking number.
Category	One of: routing, data, integration, or communication. Used for filtering in the tools list.	data

Write Good Descriptions

The description is included in the LLM's system prompt. A clear, specific description helps the LLM call the tool at the right time. Include what the tool does, when to use it, and any prerequisites (e.g., "Requires authentication").

imageTool creation form showing Tool ID, Name, Description, and Category fields filled in for a Check Order Status tool

The tool creation form with basic information

Step 3: Configure the HTTP Request

Set the action type to API Call and configure the request:

• Method -- Select GET, POST, PUT, PATCH, or DELETE.
• URL -- The endpoint URL. Use placeholders for dynamic segments:

  {{env.BACKEND_API}}/orders/{{param.order_id}}/status

• Headers -- Add request headers. Common headers include:

  Content-Type: application/json
  X-API-Key: {{env.API_KEY}}
  Authorization: Bearer {{auth_token.access_token}}

• Body (for POST/PUT/PATCH) -- A JSON template with parameter placeholders:

  {
    "account_id": "{{param.account_id}}",
    "amount": {{param.amount}},
    "payment_method": "{{param.payment_method}}"
  }

Placeholder Syntax

Prefix	Source	Example
{{param.name}}	Tool parameter value	{{param.order_id}}
{{env.NAME}}	Tenant environment variable	{{env.API_KEY}}
{{auth_token.field}}	SSO authentication token	{{auth_token.access_token}}
{{variable_name}}	Session variable	{{customer_lookup.account_id}}

Step 4: Define Parameters

Parameters describe the inputs the tool accepts. Each parameter has:

Property	Required	Description
Name	Yes	The parameter key (e.g., order_id)
Type	Yes	One of: string, number, boolean, or enum
Description	No	Explains the parameter to the LLM. Include format hints (e.g., "10-digit phone number").
Required	No	Whether the parameter must be provided. Defaults to false.
Enum Values	Only for enum	List of allowed values (e.g., ["email", "phone", "address"])

The LLM uses parameter names and descriptions to extract values from the conversation. For example, if a user says "Check order ABC-123", the LLM maps ABC-123 to the order_id parameter.

Step 5: Response Mapping

Configure how the API response is handled:

• Output Variable -- The session variable where the full response is stored (e.g., order_status).

Optionally, use JSONPath expressions to extract specific fields from the response into individual variables:

{
  "status": "$.data.status",
  "delivery_date": "$.data.estimated_delivery",
  "tracking_url": "$.data.tracking_url"
}

These extracted values become available as session variables (e.g., {{status}}, {{delivery_date}}) for use in subsequent nodes or LLM prompts.

imageResponse mapping configuration showing output variable field and JSONPath expression table mapping status, delivery_date, and tracking_url to their paths

Configuring response mapping with JSONPath expressions

Step 6: Save and Test

Optionally set an Icon (Material Icons name, e.g., local_shipping) and Color (hex, e.g., #10b981), then click Save. The tool immediately appears in your Custom Tools list and becomes available in all bot flows.

Before using the tool in a live bot, open the Test Panel to verify that the request is constructed correctly and the response mapping extracts the expected data.

WARNING

Tool IDs cannot be changed after creation. If you need a different ID, delete the tool and create a new one. Flows referencing the old tool ID will need to be updated.