Custom Tools

Extend your AI agents with custom tools that connect to external APIs, run code, or perform any action your business needs.

Overview

Custom tools let your AI agents do more than answer questions. When an agent determines it needs to perform an action, it calls a tool with structured parameters and uses the result in its response.

WhaleTools supports two execution types:

HTTP Tools

Call an external webhook URL with the tool parameters. Your server processes the request and returns a result.

JavaScript Tools

Run sandboxed JavaScript code on the platform. No external server needed. Great for data transformations and calculations.

Tool Definition Schema

Field	Type	Description
name	string	Unique identifier for the tool (snake_case).
description	string	Human-readable description. Shown to the AI agent to decide when to use it.
parameters	object	JSON Schema defining the tool's input parameters.
execution_type	string	How the tool runs: "http" (webhook) or "javascript" (sandboxed).
execution_config	object	Execution details: URL + method for HTTP, or code for JavaScript.
visibility	string	Who can see the tool: "private" (your store) or "public" (all stores).
requires_plan	string	Minimum plan required to use this tool (free, starter, pro, enterprise).

Create an HTTP Tool

HTTP tools forward the agent's parameters to your webhook URL. Your endpoint receives a POST request with the parameters as JSON and returns a result the agent can use.

curl -X POST https://vm.whaletools.cloud/v1/stores/{storeId}/tools \
  -H "x-api-key: wk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "check_shipping_rate",
    "description": "Look up shipping rates for a package based on weight, dimensions, and destination zip code.",
    "parameters": {
      "type": "object",
      "properties": {
        "weight_oz": { "type": "number", "description": "Package weight in ounces" },
        "zip_code": { "type": "string", "description": "Destination ZIP code" },
        "service": { "type": "string", "enum": ["standard", "express", "overnight"] }
      },
      "required": ["weight_oz", "zip_code"]
    },
    "execution_type": "http",
    "execution_config": {
      "url": "https://your-app.com/api/shipping-rates",
      "method": "POST",
      "headers": { "Authorization": "Bearer {{SHIPPING_API_KEY}}" }
    }
  }'

Create a JavaScript Tool

JavaScript tools run sandboxed code on the platform without needing an external server. The code receives the parameters as an object and must return a result.

curl -X POST https://vm.whaletools.cloud/v1/stores/{storeId}/tools \
  -H "x-api-key: wk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "calculate_discount",
    "description": "Calculate the discounted price given a base price and discount percentage.",
    "parameters": {
      "type": "object",
      "properties": {
        "price": { "type": "number", "description": "Original price in dollars" },
        "discount_percent": { "type": "number", "description": "Discount percentage (0-100)" }
      },
      "required": ["price", "discount_percent"]
    },
    "execution_type": "javascript",
    "execution_config": {
      "code": "const discounted = params.price * (1 - params.discount_percent / 100); return { original: params.price, discount: params.discount_percent, final_price: Math.round(discounted * 100) / 100 };"
    }
  }'

Tool Secrets

Use secret references in your HTTP tool headers and URLs to avoid hardcoding credentials. Secrets are stored encrypted and injected at execution time.

// Reference secrets with double curly braces
"headers": {
  "Authorization": "Bearer {{SHIPPING_API_KEY}}",
  "X-Custom-Header": "{{MY_SECRET}}"
}

// Manage secrets via the API
curl -X PUT https://vm.whaletools.cloud/v1/stores/{storeId}/tools/{toolId}/secrets \
  -H "x-api-key: wk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "SHIPPING_API_KEY": "sk_live_abc123...",
    "MY_SECRET": "custom-value"
  }'

Testing Tools

Test a tool with sample parameters before assigning it to an agent. The test endpoint executes the tool and returns the raw result.

curl -X POST https://vm.whaletools.cloud/v1/stores/{storeId}/tools/{toolId}/test \
  -H "x-api-key: wk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "price": 49.99,
      "discount_percent": 15
    }
  }'

// Response
{
  "success": true,
  "result": {
    "original": 49.99,
    "discount": 15,
    "final_price": 42.49
  },
  "execution_time_ms": 12
}

Assign Tools to Agents

Once created and tested, add the tool to an agent's configuration. The agent will automatically use it when relevant during conversations.

curl -X PATCH https://vm.whaletools.cloud/v1/stores/{storeId}/agents/{agentId} \
  -H "x-api-key: wk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tools": ["orders_list", "products_list", "check_shipping_rate", "calculate_discount"]
  }'