Tools & Toolsets

Define what your agents can do. Create tools (HTTP endpoints, JS functions, system calls), group them into toolsets, and test everything from your terminal.

The Workflow

Tools let agents act -- look up orders, process refunds, book appointments. Toolsets group tools for specific agents. Each toolset gets its own MCP endpoint.

Step 1: Create a tool

chanl tools create --file lookup-order.json

lookup-order.json:

{
  "name": "lookup_order",
  "description": "Look up order details by order number",
  "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 number (e.g., ORDER-12345)"
      }
    },
    "required": ["orderId"]
  }
}

✓ Created tool: tool_abc123 (lookup_order)

Step 2: Create a toolset

chanl toolsets create --name "Support Tools" --slug "support-tools"

✓ Created toolset: toolset_abc123 (support-tools)
  Endpoint: https://acme.chanl.dev/support-tools

Step 3: Add the tool to the toolset

chanl toolsets add-tool --toolset support-tools --tool tool_abc123

✓ Added lookup_order to Support Tools

Step 4: Test it

chanl tools execute tool_abc123 --args '{"orderId": "ORDER-12345"}'

Tool Execution
─────────────────────────────
Tool:     lookup_order
Status:   success
Duration: 245ms

Output:
{
  "orderId": "ORDER-12345",
  "status": "shipped",
  "trackingNumber": "1Z999AA10123456784"
}

Tool Commands

List tools

chanl tools list

Tools
───────────────────────────────────────────────────────────────
ID              Name              Type   Description                  Status
tool_abc123     lookup_order      http   Look up order details        active
tool_def456     process_refund    http   Process customer refunds     active
tool_ghi789     calc_shipping     js     Calculate shipping cost      active

Option	Description
`--search <term>`	Filter by name
`--no-system`	Exclude built-in system tools
`--json`	Output as JSON

Create a tool

From a JSON file (recommended for complex tools):

chanl tools create --file tool.json

From CLI flags (simple tools):

chanl tools create \
  --name "lookup_order" \
  --description "Look up order details by order number" \
  --type http \
  --method GET \
  --url "https://api.yourshop.com/orders/{{orderId}}" \
  --headers '{"Authorization": "Bearer {{secret:shop_api_key}}"}'

✓ Created tool: tool_abc123 (lookup_order)

Get tool details

chanl tools get tool_abc123

Tool: lookup_order
────────────────────────────────────
ID:          tool_abc123
Type:        http
Status:      active
Method:      GET
URL:         https://api.yourshop.com/orders/{{orderId}}
Timeout:     30000ms

Parameters:
  orderId (string, required)
    The order number (e.g., ORDER-12345)

Toolsets:
  - Support Tools (toolset_abc123)

Execute a tool

chanl tools execute tool_abc123 --args '{"orderId": "ORDER-12345"}'

From a file:

chanl tools execute tool_abc123 --args-file request.json

Option	Description
`--args <json>`	Inline JSON arguments
`--args-file <path>`	JSON arguments from file
`--json`	Output as JSON

Update a tool

chanl tools update tool_abc123 \
  --description "Updated description" \
  --timeout 20000

Or from file:

chanl tools update tool_abc123 --file updates.json

Delete a tool

chanl tools delete tool_abc123

Are you sure you want to delete lookup_order? (y/N) y
✓ Deleted tool: tool_abc123

Option	Description
`--force`	Skip confirmation prompt
`--remove-from-toolsets`	Also remove from all toolsets

Toolset Commands

List toolsets

chanl toolsets list

Toolsets
───────────────────────────────────────────────────────────────
ID                Name                Slug              Tools
toolset_abc123    Support Tools       support-tools     4
toolset_def456    Sales Tools         sales-tools       3
(built-in)        Admin Tools         admin-tools       12

Create a toolset

chanl toolsets create \
  --name "Support Tools" \
  --slug "support-tools" \
  --description "Tools for customer support agents"

✓ Created toolset: toolset_abc123 (support-tools)
  Endpoint: https://acme.chanl.dev/support-tools

Create with tools already assigned:

chanl toolsets create \
  --name "Support Tools" \
  --slug "support-tools" \
  --tools tool_abc123,tool_def456,tool_ghi789

Get toolset details

chanl toolsets get support-tools

Toolset: Support Tools
────────────────────────────────────
ID:          toolset_abc123
Slug:        support-tools
Endpoint:    https://acme.chanl.dev/support-tools

Tools (4):
  - lookup_order (tool_abc123)
  - process_refund (tool_def456)
  - check_inventory (tool_ghi789)
  - schedule_callback (tool_jkl012)

Add a tool to a toolset

chanl toolsets add-tool --toolset support-tools --tool tool_abc123

✓ Added lookup_order to Support Tools

Remove a tool from a toolset

chanl toolsets remove-tool --toolset support-tools --tool tool_abc123

✓ Removed lookup_order from Support Tools

Delete a toolset

chanl toolsets delete toolset_abc123 --force

✓ Deleted toolset: toolset_abc123

Tool Types

HTTP tools

Call external APIs. Use {{paramName}} for template variables and {{secret:name}} for encrypted credentials.

{
  "name": "process_refund",
  "description": "Process a refund for an order",
  "type": "http",
  "config": {
    "method": "POST",
    "url": "https://api.yourshop.com/refunds",
    "headers": {
      "Authorization": "Bearer {{secret:shop_api_key}}"
    },
    "body": {
      "orderId": "{{orderId}}",
      "amount": "{{amount}}",
      "reason": "{{reason}}"
    }
  },
  "parameters": {
    "type": "object",
    "properties": {
      "orderId": { "type": "string", "description": "Order to refund" },
      "amount": { "type": "number", "description": "Refund amount (omit for full)" },
      "reason": { "type": "string", "enum": ["damaged", "wrong_item", "not_satisfied"] }
    },
    "required": ["orderId", "reason"]
  }
}

JavaScript tools

Run custom logic in a sandboxed environment. No network access -- pure functions.

{
  "name": "calc_shipping",
  "description": "Calculate shipping cost based on weight and destination",
  "type": "javascript",
  "config": {
    "code": "const rates = { domestic: 0.5, international: 2.0 }; const type = destination.startsWith('US') ? 'domestic' : 'international'; return { cost: weight * rates[type], currency: 'USD' };"
  },
  "parameters": {
    "type": "object",
    "properties": {
      "weight": { "type": "number", "description": "Package weight in lbs" },
      "destination": { "type": "string", "description": "Country code" }
    },
    "required": ["weight", "destination"]
  }
}

System tools

Built-in to every workspace. No creation needed.

Tool	Description
`kb_search`	Search the knowledge base
`kb_add`	Add a knowledge base entry
`memory_search`	Find customer memories
`memory_add`	Store a memory
`prompt_list`	List prompt templates
`prompt_get`	Get a prompt with resolved variables

System tools can be added to any custom toolset:

chanl toolsets add-tool --toolset support-tools --tool kb_search

Scripting Examples

Create tools from a directory

for file in ./tools/*.json; do
  chanl tools create --file "$file"
done

Test all tools in a toolset

chanl toolsets get support-tools --json | \
  jq -r '.tools[].id' | \
  while read tool_id; do
    echo "Testing $tool_id..."
    chanl tools execute "$tool_id" --args '{}' --json | jq '.success'
  done

Export tool definitions

chanl tools list --json | \
  jq -r '.tools[].id' | \
  while read id; do
    chanl tools get "$id" --json > "tools/${id}.json"
  done

Migrate tools between workspaces

CHANL_WORKSPACE_ID=ws_source chanl tools get tool_abc123 --json > tool.json
CHANL_WORKSPACE_ID=ws_target chanl tools create --file tool.json

Troubleshooting

MCP Integration

Connect toolsets to Claude, Cursor, and other AI clients

Platform: Tools

Tool concepts, types, and secret vault

Platform: Toolsets

Toolset strategy and MCP endpoints

SDK: Automate Tools

Use tools programmatically from the SDK

Tool creation fails with validation error

Tool execution times out

Secret not found during execution

Tool not appearing in MCP

MCP Integration

Platform: Tools

Platform: Toolsets

SDK: Automate Tools

On this page