Tool Configuration

Configure custom tools that your AI agent can call to take actions on behalf of your brand. Examples: check order status, create refund, lookup inventory.

List Tools

Retrieve all configured tools for your tenant.

GET /api/tenants/me/tools

Response

{
  "data": [
    {
      "id": "tool_ulid",
      "name": "check_order_status",
      "description": "Check the status of a customer's order",
      "apiEndpoint": "https://oms.yody.vn/api/orders/status",
      "httpMethod": "POST",
      "paramSchema": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string", "description": "Order ID to check" }
        },
        "required": ["order_id"]
      },
      "isActive": true,
      "createdAt": "2026-03-01T00:00:00Z"
    }
  ]
}

---

Create Tool

Register a new tool that the AI agent can call.

POST /api/tenants/me/tools

Request

{
  "name": "check_order_status",
  "description": "Check the status of a customer's order",
  "apiEndpoint": "https://oms.yody.vn/api/orders/status",
  "httpMethod": "POST",
  "paramSchema": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The order ID to check"
      }
    },
    "required": ["order_id"]
  },
  "authHeader": "Bearer your_api_key_here"
}

Field Descriptions

Field	Type	Required	Notes
name	string	✓	Unique tool name (lowercase, underscores)
description	string	✓	What the tool does (sent to LLM)
apiEndpoint	URL	✓	Your backend endpoint
httpMethod	enum	✓	GET, POST, PUT
paramSchema	JSON	✓	JSON Schema defining parameters
authHeader	string		Authorization header if needed

Response

{
  "id": "tool_ulid",
  "name": "check_order_status",
  "description": "Check the status of a customer's order",
  "apiEndpoint": "https://oms.yody.vn/api/orders/status",
  "httpMethod": "POST",
  "paramSchema": { ... },
  "isActive": true,
  "createdAt": "2026-03-12T00:00:00Z"
}

---

Update Tool

Modify an existing tool configuration.

PUT /api/tenants/me/tools/:toolId

Request

{
  "description": "Check the status of a customer's order (updated)",
  "apiEndpoint": "https://oms.yody.vn/v2/orders/status",
  "isActive": true
}

Response

{
  "success": true,
  "tool": { ... }
}

---

Delete Tool

Remove a tool from your configuration.

DELETE /api/tenants/me/tools/:toolId

Response

{
  "success": true,
  "message": "Tool deleted"
}

---

Tool Execution Flow

When a customer message arrives, the AI agent may decide to call a tool:

1. Decision — Haiku LLM decides if a tool call is needed
2. Extraction — Tool name + parameters extracted from Haiku response
3. Validation — Parameters validated against your JSON Schema
4. Execution — HTTP request sent to your apiEndpoint
5. Injection — Tool result injected into conversation context
6. Generation — Haiku generates final response using tool result

Max 1 tool call per turn. After tool result is injected, Haiku generates the response (no chaining).

---

Example: Order Status Tool

Tool Definition

{
  "name": "check_order_status",
  "description": "Check the status and tracking info of a customer's order",
  "apiEndpoint": "https://oms.yody.vn/api/orders/status",
  "httpMethod": "POST",
  "paramSchema": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The Yody order ID (e.g., YD-20260312-001)"
      }
    },
    "required": ["order_id"]
  }
}

Haiku Call (from your API logs)

TOOL_CALL: check_order_status
PARAMS: { "order_id": "YD-20260312-001" }

Your Backend Response

{
  "order_id": "YD-20260312-001",
  "status": "shipped",
  "carrier": "VNPost",
  "tracking_number": "VNP123456789",
  "eta": "2026-03-14"
}

AI Response (to customer)

Đơn hàng YD-20260312-001 của bạn đã được gửi đi! 
📦 Vận chuyển bằng VNPost (VNP123456789), dự kiến nhận ngày 14/03. 

Bạn có thể theo dõi hàng tại https://tracking.vnpost.vn

---

Parameter Schema Format

Use JSON Schema to define tool parameters. Examples:

Simple String Parameter

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "Order ID to check"
    }
  },
  "required": ["order_id"]
}

Multiple Parameters

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "description": "Customer ID"
    },
    "action": {
      "type": "string",
      "enum": ["refund", "exchange", "cancel"],
      "description": "Action to perform"
    },
    "amount": {
      "type": "number",
      "description": "Refund amount in VND"
    }
  },
  "required": ["customer_id", "action"]
}

---

Error Handling

If your tool endpoint returns an error or timeout:

• Timeout (>10s) → Hard stop. Haiku receives {"error": "tool_timeout"} injected into context and generates a graceful response: "I'll check on that and get back to you" (no async waiting). Customer doesn't see timeout error — the AI acknowledges and commits to follow-up.
• HTTP error (4xx/5xx) → Error message injected, Haiku acknowledges the issue to customer
• Invalid params → Haiku retried with corrected params (up to 1 additional attempt)

Important: Tool execution is always synchronous. No background retries or async follow-up. If the tool doesn't respond in 10 seconds, the request terminates gracefully.

---

Best Practices

1. Keep it simple — One action per tool. Don't build a god-tool.
2. Authenticate — Use authHeader to secure your endpoint or IP-whitelist Dolly's servers.
3. SSRF Protection — Dolly validates all endpoints (no internal IPs, localhost blocked).
4. Response Size — Keep responses under 4KB (truncated otherwise).
5. Timeout — Design for <5s response time (10s hard limit).
6. Logging — Log all tool calls for debugging and audit.

---

Error Responses

Error	HTTP	Cause
INVALID_REQUEST	400	Invalid tool name, missing paramSchema
NOT_FOUND	404	Tool does not exist
CONFLICT	409	Tool name already exists
INTERNAL_ERROR	500	Server error