Tools: Complete User Guide

Tools are powerful extensions that allow your AI agents to interact with external systems and perform actions during conversations. This comprehensive guide explains how to create, configure, and manage both user tools and system tools effectively.

Types of Tools

User Tools

Custom tools you create that make HTTP requests to external APIs or services. These are fully customizable and specific to your business needs.

System Tools

Built-in platform tools that provide common functionality like ending calls or playing sounds. These are pre-configured and maintained by the platform.

Creating Your First User Tool

1. Navigate to Tools: Go to Dashboard → Tools → User Tools tab
2. Click "Create Tool"
3. Fill Basic Information:
   • Tool Name: Human-readable name (e.g., "Order Lookup")
   • Description: What the tool does
   • Model Tool Name: The name the AI uses (e.g., "lookupOrderStatus")

Tool Structure Deep Dive

Every user tool consists of:

• Basic Information: Name, description, model tool name
• HTTP Configuration: Method, base URL pattern
• Dynamic Parameters: Data extracted from conversation
• Automatic Parameters: System-provided values

Base URL Pattern

The endpoint your tool will call. Can include placeholders for dynamic values:

• https://api.yourstore.com/orders - Static endpoint
• https://api.yourstore.com/orders/{orderId} - With path parameter
• https://api.external-service.com/bookings - External service

Parameter Locations

Parameters can be placed in different parts of the HTTP request:

• PARAMETER_LOCATION_BODY - Request body (most common for POST/PUT)
• PARAMETER_LOCATION_PATH - URL path segment
• PARAMETER_LOCATION_QUERY - URL query string
• PARAMETER_LOCATION_HEADER - HTTP header

Dynamic Parameters Deep Dive

Dynamic parameters are extracted from conversation. The AI understands context and fills these automatically.

Simple String Parameter

[
  {
    "name": "customerMessage",
    "location": "PARAMETER_LOCATION_BODY",
    "schema": {
      "type": "string",
      "description": "Customer's message or request"
    },
    "required": true
  }
]

Enum Parameter (Limited Choices)

[
  {
    "name": "priority",
    "location": "PARAMETER_LOCATION_BODY", 
    "schema": {
      "type": "string",
      "enum": ["High", "Medium", "Low"],
      "description": "The urgency level of the issue"
    },
    "required": true
  }
]

Complex Object Parameter

[
  {
    "name": "supportTicket",
    "location": "PARAMETER_LOCATION_BODY",
    "schema": {
      "type": "object",
      "properties": {
        "customerName": {
          "type": "string",
          "description": "Name of the customer"
        },
        "priority": {
          "type": "string", 
          "enum": ["High", "Medium", "Low"],
          "description": "The urgency level of the issue"
        },
        "category": {
          "type": "string",
          "enum": ["Technical", "Billing", "General"],
          "description": "Type of support needed"
        },
        "description": {
          "type": "string",
          "description": "Detailed description of the issue"
        },
        "isUrgent": {
          "type": "boolean",
          "description": "Whether this requires immediate attention"
        }
      },
      "required": ["customerName", "priority", "category", "description"]
    },
    "required": true
  }
]

Nested Object with User Info

[
  {
    "name": "reservationData",
    "location": "PARAMETER_LOCATION_BODY",
    "schema": {
      "type": "object", 
      "properties": {
        "bookingId": {
          "type": "string",
          "description": "Booking reference from previous step"
        },
        "customerInfo": {
          "type": "object",
          "properties": {
            "firstName": {
              "type": "string",
              "description": "Customer's first name"
            },
            "lastName": {
              "type": "string", 
              "description": "Customer's last name"
            },
            "email": {
              "type": "string",
              "description": "Customer's email address"
            },
            "phone": {
              "type": "string",
              "description": "Customer's phone number"
            }
          },
          "required": ["firstName", "lastName", "email"]
        }
      },
      "required": ["bookingId", "customerInfo"]
    },
    "required": true
  }
]

Automatic Parameters

Values the system provides automatically (API keys, call context, etc.). These are added to the automaticParameters array in your tool configuration.

Known System Values

• KNOWN_PARAM_CALL_ID - Current call identifier
• KNOWN_PARAM_USER_EMAIL - User's email
• KNOWN_PARAM_PHONE_NUMBER - Caller's phone number

API Key in Header

"automaticParameters": [
  {
    "name": "authorization",
    "location": "PARAMETER_LOCATION_HEADER",
    "knownValue": "Bearer sk-your-secret-api-key"
  }
]

Call Context in Body

"automaticParameters": [
  {
    "name": "callId",
    "location": "PARAMETER_LOCATION_BODY", 
    "knownValue": "KNOWN_PARAM_CALL_ID"
  },
  {
    "name": "userEmail",
    "location": "PARAMETER_LOCATION_BODY",
    "knownValue": "KNOWN_PARAM_USER_EMAIL"
  }
]

API Authentication Methods

Query Parameter Authentication

"automaticParameters": [
  {
    "name": "api_key",
    "location": "PARAMETER_LOCATION_QUERY",
    "knownValue": "your-api-key-here"
  }
]

HTTP Basic Authentication

"automaticParameters": [
  {
    "name": "authorization",
    "location": "PARAMETER_LOCATION_HEADER",
    "knownValue": "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
  }
]

Custom Header Authentication

"automaticParameters": [
  {
    "name": "X-API-Key",
    "location": "PARAMETER_LOCATION_HEADER",
    "knownValue": "your-custom-api-key"
  }
]

Static Values

You can also use automatic parameters to pass static values that don't change between calls:

"automaticParameters": [
  {
    "name": "source",
    "location": "PARAMETER_LOCATION_BODY",
    "knownValue": "voice-agent"
  },
  {
    "name": "version",
    "location": "PARAMETER_LOCATION_HEADER",
    "knownValue": "v1.0"
  }
]

System Tools

Available System Tools

1. Hang Up (hangUp)

• Purpose: Ends the current call immediately
• When to use: When conversation is complete or needs to be terminated
• Usage: Agent can say "I'll end the call now" and use this tool

2. Play DTMF Sounds (playDtmfSounds)

• Purpose: Sends touch-tone signals during calls
• When to use: Navigating phone trees, entering codes
• Usage: Agent can input numbers/codes into automated systems

Assigning Tools to Agents

User Tools Assignment

1. Go to Tools → User Tools tab
2. Find your tool and click "Assign"
3. Select which agents should have access
4. Tools are immediately available to assigned agents

System Tools Assignment

1. Go to Tools → System Tools tab
2. Click "Assign" on the desired system tool
3. Select agents from your list
4. System tools are immediately available during calls

Best Practices

Tool Design

• Clear Names: Use descriptive model tool names (e.g., checkOrderStatus not tool1)
• Specific Purpose: Each tool should have one clear responsibility
• Good Descriptions: Help the AI understand when to use the tool

Parameter Configuration

• Required Fields: Mark essential parameters as required
• Clear Descriptions: Explain what each parameter does
• Validation: Use proper schema types (string, number, boolean)

Complete Example Tools

Here are educational examples showing different patterns and use cases:

Example 1: Order Status Lookup

Use Case: Check order status for customers

{
  "temporaryTool": {
    "modelToolName": "checkOrderStatus",
    "automaticParameters": [
      {
        "name": "apiKey",
        "location": "PARAMETER_LOCATION_HEADER",
        "knownValue": "Bearer sk-your-api-key"
      }
    ],
    "dynamicParameters": [
      {
        "name": "orderId",
        "location": "PARAMETER_LOCATION_PATH",
        "schema": {
          "type": "string",
          "description": "Customer's order number or ID"
        },
        "required": true
      }
    ],
    "http": {
      "baseUrlPattern": "https://api.yourstore.com/orders/{orderId}",
      "httpMethod": "GET"
    },
    "description": "Retrieves order status and tracking information"
  }
}

Example 2: Support Ticket Creation

Use Case: Create support tickets for customer issues

{
  "temporaryTool": {
    "modelToolName": "createSupportTicket",
    "automaticParameters": [
      {
        "name": "authorization",
        "location": "PARAMETER_LOCATION_HEADER",
        "knownValue": "Bearer sk-support-api-key"
      },
      {
        "name": "source",
        "location": "PARAMETER_LOCATION_BODY",
        "knownValue": "voice-agent"
      }
    ],
    "dynamicParameters": [
      {
        "name": "ticketData",
        "location": "PARAMETER_LOCATION_BODY",
        "schema": {
          "type": "object",
          "properties": {
            "customerName": {
              "type": "string",
              "description": "Name of the customer reporting the issue"
            },
            "priority": {
              "type": "string",
              "enum": ["High", "Medium", "Low"],
              "description": "Priority level based on issue severity"
            },
            "category": {
              "type": "string",
              "enum": ["Technical", "Billing", "Account", "General"],
              "description": "Type of issue being reported"
            },
            "subject": {
              "type": "string",
              "description": "Brief summary of the issue"
            },
            "description": {
              "type": "string", 
              "description": "Detailed description of the problem"
            },
            "affectsMultipleUsers": {
              "type": "boolean",
              "description": "Whether this issue affects multiple customers"
            }
          },
          "required": ["customerName", "priority", "category", "subject", "description"]
        },
        "required": true
      }
    ],
    "http": {
      "baseUrlPattern": "https://api.yoursupport.com/tickets",
      "httpMethod": "POST"
    },
    "description": "Creates a support ticket for customer issues"
  }
}

Example 3: Appointment Booking System

Use Case: Multi-step appointment booking workflow

Step 1: Check Availability

{
  "temporaryTool": {
    "modelToolName": "checkAvailability",
    "automaticParameters": [
      {
        "name": "apiKey",
        "location": "PARAMETER_LOCATION_HEADER",
        "knownValue": "Bearer sk-booking-api-key"
      }
    ],
    "dynamicParameters": [
      {
        "name": "searchCriteria",
        "location": "PARAMETER_LOCATION_BODY",
        "schema": {
          "type": "object",
          "properties": {
            "serviceType": {
              "type": "string",
              "description": "Type of service needed (e.g., 'consultation', 'checkup')"
            },
            "preferredLocation": {
              "type": "string", 
              "description": "Preferred location or clinic name"
            },
            "timeframe": {
              "type": "string",
              "enum": ["This Week", "Next Week", "This Month", "Next Month"],
              "description": "When the customer wants to schedule"
            },
            "duration": {
              "type": "integer",
              "description": "Expected duration in minutes"
            }
          },
          "required": ["serviceType", "preferredLocation", "timeframe"]
        },
        "required": true
      }
    ],
    "http": {
      "baseUrlPattern": "https://api.booking-system.com/availability",
      "httpMethod": "POST"
    },
    "description": "Finds available appointment slots"
  }
}

Step 2: Confirm Booking

{
  "temporaryTool": {
    "modelToolName": "confirmBooking",
    "automaticParameters": [
      {
        "name": "apiKey",
        "location": "PARAMETER_LOCATION_HEADER",
        "knownValue": "Bearer sk-booking-api-key"
      }
    ],
    "dynamicParameters": [
      {
        "name": "bookingDetails",
        "location": "PARAMETER_LOCATION_BODY", 
        "schema": {
          "type": "object",
          "properties": {
            "slotId": {
              "type": "string",
              "description": "Available slot ID from previous search"
            },
            "appointmentDate": {
              "type": "string",
              "description": "Selected date in YYYY-MM-DD format"
            },
            "appointmentTime": {
              "type": "string",
              "description": "Selected time in HH:MM format" 
            },
            "customerDetails": {
              "type": "object",
              "properties": {
                "firstName": {
                  "type": "string",
                  "description": "Customer's first name"
                },
                "lastName": {
                  "type": "string",
                  "description": "Customer's last name"
                },
                "email": {
                  "type": "string",
                  "description": "Customer's email for confirmation"
                },
                "phone": {
                  "type": "string",
                  "description": "Customer's phone number"
                }
              },
              "required": ["firstName", "lastName", "email", "phone"]
            },
            "notes": {
              "type": "string",
              "description": "Any special requests or notes"
            }
          },
          "required": ["slotId", "appointmentDate", "appointmentTime", "customerDetails"]
        },
        "required": true
      }
    ],
    "http": {
      "baseUrlPattern": "https://api.booking-system.com/bookings",
      "httpMethod": "POST"
    },
    "description": "Confirms and books the appointment"
  }
}

How Tools Work During Calls

When an agent handles a live call, the tool execution follows this workflow:

1. Context Recognition: AI recognizes when customer needs require tool usage
2. Information Extraction: AI extracts required parameters from conversation
3. Validation: Parameters are validated against schema requirements
4. HTTP Request: Tool makes API call with proper formatting
5. Response Processing: API response is interpreted by AI
6. Natural Response: AI provides human-friendly response to customer

Example Conversation Flow

Tool Management Best Practices

Security & Authentication

• Use Automatic Parameters: Store API keys in automatic parameters, not dynamic ones
• Header Authentication: Place API keys in headers using PARAMETER_LOCATION_HEADER
• Known Values: Use system values like KNOWN_PARAM_CALL_ID for context
• Multiple Auth Methods: Support Bearer tokens, Basic auth, query parameters, and custom headers
• Static Values: Use automatic parameters for unchanging values like source identifiers

Schema Design

• Clear Descriptions: Help AI understand when and how to use each parameter
• Required Fields: Mark essential parameters as required
• Enums for Choices: Use enum for limited option sets
• Nested Objects: Group related data logically

Testing & Deployment

• Start Simple: Begin with basic GET requests
• Test Incrementally: Add complexity gradually
• Monitor Logs: Check call logs for tool execution
• Error Handling: Ensure your APIs return clear error messages