Tools
Create custom functions your agents can call during conversations — CRM lookups, order checks, ticket creation
Tools
An agent that can only talk is half an agent. Tools let it act — look up a customer's order, cancel a subscription, book an appointment, send a confirmation email — all during a live conversation.
A tool is a function defined as a JSON Schema input paired with an execution target. You define what the tool does, what parameters it accepts, and where to send the request. Chanl handles the rest: validation, execution, secret injection, error handling, and logging.
Tool Types
| Type | Execution Target | Best For |
|---|---|---|
| HTTP | Calls an external API endpoint | CRM lookups, payment processing, order management |
| System | Built-in platform functions | kb_search, memory_add, memory_search |
| JavaScript | Custom logic in a sandboxed runtime | Data transformation, calculations, conditional logic |
System tools (kb_search, memory_add, etc.) are pre-built and available in every workspace. You only need to create tools for your own APIs and business logic.
Creating Tools
Go to Build → Tools in the dashboard and click Create Tool.
Every tool needs:
- Name — what the agent calls it (e.g.,
lookup_order) - Description — what the agent should know about when to use it
- Parameters — JSON Schema defining the inputs
- Type — HTTP, JavaScript, or System
The tool builder UI lets you define parameters visually, set the HTTP endpoint, and test the tool before saving.
chanl tools create \
--name "lookup_order" \
--description "Look up a customer order by order ID" \
--type http \
--method GET \
--url "https://api.yourshop.com/orders/{{orderId}}" \
--headers '{"Authorization": "Bearer {{secret:shop_api_key}}"}'curl -X POST "https://api.chanl.ai/api/v1/tools" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"name": "lookup_order",
"description": "Look up a customer order by order ID",
"type": "http",
"config": {
"method": "GET",
"url": "https://api.yourshop.com/orders/{{orderId}}",
"headers": {
"Authorization": "Bearer {{secret:shop_api_key}}"
}
},
"parameters": {
"type": "object",
"properties": {
"orderId": {
"type": "string",
"description": "The order ID to look up"
}
},
"required": ["orderId"]
}
}'Tools don't do anything on their own — they need to be in a toolset that's connected to an agent via MCP.
chanl toolsets add-tool --toolset support-tools --tool <tool-id>Now any agent connected to acme.chanl.dev/support-tools can use lookup_order.
Run a test scenario where the persona asks about an order. Check the simulation transcript — you'll see the tool call, the parameters the agent passed, and the response it received.
HTTP Tools
The most common type. An HTTP tool calls an external API when the agent invokes it.
Template Variables
Use {{paramName}} in the URL, headers, or body to inject parameters from the agent's tool call:
URL: https://api.yourshop.com/orders/{{orderId}}
Headers: {"Authorization": "Bearer {{secret:shop_api_key}}"}
Body: {"email": "{{customerEmail}}"}Secrets
Never hardcode API keys in tool configs. Use the secret vault:
{{secret:shop_api_key}}This references an encrypted credential stored in Settings → Secrets. The actual value never appears in logs, tool configs, or MCP responses.
If you put an API key directly in a tool URL or header, it will be visible in logs and MCP tool descriptions. Always use {{secret:name}} references.
JavaScript Tools
For logic that doesn't map to a simple API call — data transformation, conditional routing, calculations:
// Tool: calculate_shipping
// Parameters: { weight: number, destination: string }
const rates = {
domestic: 0.5,
international: 2.0,
};
const type = destination.startsWith('US') ? 'domestic' : 'international';
const cost = weight * rates[type];
return { cost, currency: 'USD', estimatedDays: type === 'domestic' ? 3 : 10 };JavaScript tools run in a sandboxed environment with no network access. They're pure functions — input in, result out.
How Agents Use Tools
During a conversation, the agent decides when to use a tool based on the conversation context and the tool's description. Here's what happens:
The agent doesn't need to know the API URL, authentication, or response format. It just calls the tool by name and gets a result.