Tools - Feather

What Are Tools?

Tools give your agents the ability to take actions and retrieve information during conversations. They are function calls that your agent can execute to interact with external systems, databases, APIs, and services. When an agent needs to accomplish a task beyond conversation, it can:

Call your APIs - Integrate with your CRM, database, or custom services
Retrieve information - Look up customer data, order status, or availability
Take actions - Create tickets, book appointments, or update records
Search knowledge bases - Find relevant information from your documents
Integrate with third-party services - Use pre-built integrations like Calendly

Tool Types

Custom Tools

Custom tools are API integrations you build to connect agents with your systems:

{
  name: "Look Up Customer Order",
  description: "Retrieve order status and details for a customer",
  slug: "lookup_customer_order",
  structure: {
    url: "https://api.yourcompany.com/orders/{{orderId}}",
    method: "GET",
    headers: {
      "Authorization": "Bearer {{apiKey}}",
      "Content-Type": "application/json"
    },
    timeout: 5000
  },
  speech: "I'm looking up your order information now"
}

Pre-Built Tools

Feather provides ready-to-use tools for common integrations:

Calendly - Schedule appointments directly in conversations
Knowledge Base - Search your uploaded documents for answers
Lead Management - Update lead information and conversation history
Call Transfer - Transfer calls to human agents
SMS - Send text messages during or after calls

Creating Custom Tools

Basic Tool Structure

const tool = {
  name: "Create Support Ticket",
  description: "Creates a new support ticket in the CRM system with customer issue details",
  slug: "create_support_ticket",
  speech: "I'm creating a support ticket for you right now",
  structure: {
    url: "https://api.yourcrm.com/tickets",
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: {
      "title": "{{issueTitle}}",
      "description": "{{issueDescription}}",
      "priority": "{{priority}}",
      "customerId": "{{customerId}}"
    },
    timeout: 10000,
    variables: [
      {
        name: "issueTitle",
        description: "Brief title of the customer's issue",
        type: "string",
        required: true
      },
      {
        name: "issueDescription",
        description: "Detailed description of the issue",
        type: "string",
        required: true
      },
      {
        name: "priority",
        description: "Priority level: low, medium, high, urgent",
        type: "string",
        required: false
      },
      {
        name: "customerId",
        description: "Customer ID in the CRM",
        type: "string",
        required: true
      }
    ]
  }
};

const response = await fetch('https://prod.featherhq.com/api/v1/tools', {
  method: 'POST',
  headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(tool)
});

Tool Properties

Core Fields:

name (required): Human-readable tool name
description (required): Clear description of what the tool does
slug (required): Unique identifier (lowercase, letters, numbers, underscores only)
speech (optional): What the agent says while executing the tool

Structure Configuration:

url (required): API endpoint to call
method (required): HTTP method (GET, POST, PUT, PATCH, DELETE)
headers: HTTP headers including authentication
body: Request payload for POST/PUT/PATCH requests
timeout: Maximum execution time in milliseconds (default: 5000)
variables: Parameters the agent needs to collect

Variable Definitions

Variables define what information the agent must gather before calling the tool:

{
  variables: [
    {
      name: "orderId",
      description: "The customer's order number",
      type: "string",
      required: true
    },
    {
      name: "quantity",
      description: "Number of items to reorder",
      type: "number",
      required: false
    },
    {
      name: "expedited",
      description: "Whether to use expedited shipping",
      type: "boolean",
      required: false
    }
  ]
}

Variable Types:

string: Text values
number: Numeric values
boolean: True/false values
array: Lists of values
object: Complex nested structures

Using Variables in Requests

Reference variables in URLs, headers, and body using {{variableName}}:

{
  "url": "https://api.example.com/users/{{userId}}/orders/{{orderId}}",
  "headers": {
    "Authorization": "Bearer {{apiKey}}",
    "X-User-Email": "{{userEmail}}"
  },
  "body": {
    "action": "{{action}}",
    "quantity": "{{quantity}}",
    "metadata": {
      "source": "voice_agent",
      "agentId": "{{agentId}}"
    }
  }
}

Attaching Tools to Agents

Once created, attach tools to agents in the agent version configuration:

const agentVersion = {
  mode: "PROMPT",
  prompt: {
    system: "You are a helpful support agent. Use the create_support_ticket tool when customers report issues.",
    tools: ["create_support_ticket", "lookup_customer_order"],
    preBuiltTools: ["knowledge-search", "calendly"]
  },
  // ... other configuration
};

const response = await fetch(`https://prod.featherhq.com/api/v1/agents/${agentId}`, {
  method: 'POST',
  headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(agentVersion)
});

Tool Execution Flow

When an agent uses a tool, here’s what happens:

Detection - Agent determines a tool is needed based on conversation
Parameter Collection - Agent gathers required variables from the customer
Validation - System validates all required variables are present
Speech - Agent says the speech text (if provided)
Execution - HTTP request is made to your API
Response - Agent receives and processes the response
Continuation - Agent continues conversation with the result

Common Tool Patterns

CRM Integration

{
  "name": "Update Contact in HubSpot",
  "slug": "update_hubspot_contact",
  "structure": {
    "url": "https://api.hubapi.com/crm/v3/objects/contacts/{{contactId}}",
    "method": "PATCH",
    "headers": {
      "Authorization": "Bearer YOUR_HUBSPOT_TOKEN",
      "Content-Type": "application/json"
    },
    "body": {
      "properties": {
        "phone": "{{phoneNumber}}",
        "last_contacted": "{{timestamp}}",
        "lead_status": "{{status}}",
        "notes": "{{conversationNotes}}"
      }
    }
  }
}

Database Lookup

{
  "name": "Get Account Balance",
  "slug": "get_account_balance",
  "structure": {
    "url": "https://api.yourbank.com/accounts/{{accountId}}/balance",
    "method": "GET",
    "headers": {
      "Authorization": "Bearer {{apiKey}}",
      "X-Customer-ID": "{{customerId}}"
    },
    "timeout": 3000
  }
}

Webhook Trigger

{
  "name": "Send to Slack",
  "slug": "send_slack_notification",
  "structure": {
    "url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {
      "text": "New call from {{customerName}}: {{callSummary}}",
      "channel": "#sales-alerts"
    }
  }
}

Order Management

{
  "name": "Process Refund",
  "slug": "process_refund",
  "structure": {
    "url": "https://api.yourstore.com/orders/{{orderId}}/refund",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer {{apiKey}}",
      "Content-Type": "application/json"
    },
    "body": {
      "orderId": "{{orderId}}",
      "amount": "{{refundAmount}}",
      "reason": "{{refundReason}}",
      "notifyCustomer": true
    },
    "variables": [
      {
        "name": "orderId",
        "description": "Order ID to refund",
        "type": "string",
        "required": true
      },
      {
        "name": "refundAmount",
        "description": "Amount to refund in dollars",
        "type": "number",
        "required": true
      },
      {
        "name": "refundReason",
        "description": "Reason for the refund",
        "type": "string",
        "required": true
      }
    ]
  }
}

Best Practices

Tool Design

Single responsibility - Each tool should do one thing well
Clear descriptions - Help the agent understand when to use the tool
Descriptive variables - Make it obvious what information is needed
Appropriate timeouts - Set realistic timeouts based on your API speed
Error handling - Ensure your API returns helpful error messages

Security

Secure credentials - Never expose API keys in tool definitions
Use environment variables - Store sensitive data securely
Validate inputs - Ensure your API validates all parameters
Rate limiting - Implement rate limits on your APIs
Audit tool usage - Monitor tool calls for suspicious activity

Performance

Optimize API speed - Fast APIs create better call experiences
Cache when possible - Cache frequently accessed data
Set appropriate timeouts - Balance speed vs. reliability
Handle failures gracefully - Provide fallback responses
Monitor tool latency - Track tool execution times

Agent Integration

Provide context in prompts - Explain when and how to use tools
Include tool descriptions - Help agents understand tool purposes
Test tool flows - Verify tools work in conversation context
Handle tool failures - Train agents to handle errors gracefully
Give feedback to users - Use speech to keep customers informed

Testing Tools

Test Tool Configuration

curl -X POST "https://prod.featherhq.com/api/v1/tools/test" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toolId": "tool-123",
    "variables": {
      "orderId": "TEST-12345",
      "customerId": "CUST-67890"
    }
  }'

Debugging Tool Calls

Monitor tool execution in call logs:

View call details in dashboard
Check tool execution timeline
Review request/response payloads
Identify errors and timeouts
Optimize based on performance data

Common Use Cases

CRM Integration

Sync customer data between conversations and your CRM

Order Management

Look up orders, process returns, and update shipping information

Appointment Booking

Check availability and schedule appointments in your calendar

Ticket Creation

Create support tickets with conversation context

Payment Processing

Process payments, refunds, and billing updates

Inventory Check

Check product availability and stock levels

Notifications

Trigger alerts to Slack, email, or other channels

Data Enrichment

Enrich lead data with third-party information

Troubleshooting

Tool Not Executing

Check:

Tool is attached to agent version
All required variables are defined
Agent prompt mentions the tool
Tool slug matches exactly

Timeout Errors

Solutions:

Increase timeout value
Optimize your API performance
Add caching to your endpoint
Use async processing for long operations

Variable Collection Issues

Solutions:

Make variable descriptions very clear
Provide examples in the description
Update agent prompt with guidance
Mark optional variables correctly

Authentication Failures

Solutions:

Verify API credentials are current
Check token expiration
Ensure headers are formatted correctly
Test endpoint independently

Next Steps

Agents

Learn how to configure agents to use your tools

Knowledge Base

Set up knowledge base for pre-built search tool

Integrations

Explore third-party integration options

API Reference

View the complete tools API reference

Getting Started

Core Concepts

​What Are Tools?

​Tool Types

​Custom Tools

​Pre-Built Tools

​Creating Custom Tools

​Basic Tool Structure

​Tool Properties

​Variable Definitions

​Using Variables in Requests

​Attaching Tools to Agents

​Tool Execution Flow

​Common Tool Patterns

​CRM Integration

​Database Lookup

​Webhook Trigger

​Order Management

​Best Practices

​Tool Design

​Security

​Performance

​Agent Integration

​Testing Tools

​Test Tool Configuration

​Debugging Tool Calls

​Common Use Cases

CRM Integration

Order Management

Appointment Booking

Ticket Creation

Payment Processing

Inventory Check

Notifications

Data Enrichment

​Troubleshooting

​Tool Not Executing

​Timeout Errors

​Variable Collection Issues

​Authentication Failures

​Next Steps

Agents

Knowledge Base

Integrations

API Reference

What Are Tools?

Tool Types

Custom Tools

Pre-Built Tools

Creating Custom Tools

Basic Tool Structure

Tool Properties

Variable Definitions

Using Variables in Requests

Attaching Tools to Agents

Tool Execution Flow

Common Tool Patterns

CRM Integration

Database Lookup

Webhook Trigger

Order Management

Best Practices

Tool Design

Security

Performance

Agent Integration

Testing Tools

Test Tool Configuration

Debugging Tool Calls

Common Use Cases

Troubleshooting

Tool Not Executing

Timeout Errors

Variable Collection Issues

Authentication Failures

Next Steps