​
What is a Custom Tool?

Custom tools are powerful extensions that enable voice and chat AI to perform tasks across the internet. They open opportunities for custom functionality, data retrieval, data extraction, and workflow automation while understanding and responding contextually to the task at hand.

​
How Does a Custom Tool Work?

A custom tool operates as an LLM function call wrapped in an API call. It specifies AI functionality through a description and parameters, while the endpoint URL facilitates a POST call with contextual awareness of the endpoint’s return data. This functionality is ideal for integrations like MLS systems, solar quoting, data fetching, and more.

​
Use Cases for Custom Tools

The potential applications of custom tools are as broad as your creativity or needs. Examples include:
  • Updating contact information: AI collects details and sends them to a webhook to update CRM records
  • Advanced workflows: Multi-stage tool calls can generate Stripe customer IDs and unique checkout links to send via SMS
  • Real estate integrations: MLS data retrieval for property listings
  • E-commerce automation: Order tracking and delivery date retrieval
  • Solar quoting systems: Custom pricing calculations based on user input
  • Data fetching: External API integrations for real-time information

​
Understanding Inputs

​
Name [Raw JSON Format]

This specifies the unique name of the tool call, triggered when the AI determines a condition matches. The name should reflect the tool’s function in plain raw text. Examples:
  • Updating contact information: update_contact
  • Retrieving a delivery date for an order: get_delivery_date
  • Fetching property listings: search_properties
Best Practices:
  • Use lowercase letters only
  • Replace spaces with underscores
  • Keep names descriptive but concise
  • Avoid special characters

​
Description [Conversational Text]

The description is crucial as it guides the AI on the tool’s purpose, how to use it, and when to trigger it. This should be written in clear, conversational language that explains the tool’s functionality. Example: For get_delivery_date, the description could be: 
"Retrieve the delivery date for a customer's order. Use this tool when a customer asks, 'Where is my package?' or similar delivery-related questions."
Writing Effective Descriptions:
  • Clearly state the tool’s purpose
  • Specify when the AI should trigger the tool
  • Include example user queries that should activate the tool
  • Be specific about the expected functionality

​
Endpoint URL [URL Format]

The Endpoint URL is where the AI sends a POST request, delivering data and expecting a response. This should be a complete, valid URL that can receive and process the tool’s parameters. Example: For retrieving real estate listings from an MLS: 
https://api.bridgedataoutput.com/api/v2/OData/dataset_id/Property?access_token=access_token&$expand=ListOffice
URL Requirements:
  • Must be a valid, accessible endpoint
  • Should accept POST requests
  • Can include query parameters as needed
  • Must be able to process JSON data

​
Authorization & Key [Toggle and Bearer Token]

Authorization is integrated into the API wrapper, enabling you to call API endpoints that require authentication or API keys. Use the Bearer Token format for this field. Format: 
Bearer your_api_key_here
Example: If API documentation specifies an authorization header, input your account’s API key to authenticate the call: 
Bearer sk_live_51234567890abcdef
Security Notes:
  • Always use secure API keys
  • Ensure keys have appropriate permissions
  • Regularly rotate authentication tokens
  • Store sensitive credentials securely

​
Parameters [Key/Value Pairs with Descriptions]

Parameters define the data being requested, including a detailed description of what information is needed and its expected format. The key should follow JSON naming conventions, while the value is a description that specifies the data and format required.

​
Parameter Key Requirements:

  • Lowercase letters only
  • No spaces (use underscores instead)
  • Avoid special characters
  • Follow JSON naming conventions

​
Parameter Value Requirements:

  • Clear description of the expected data
  • Specify format (number, text, date, etc.)
  • Include examples when helpful

​
Examples:

Simple Name Parameter:
  • Key: name
  • Value: “The first name of the user”
  • Output: {"name":"johnny"}
Revenue Parameter:
  • Key: revenue
  • Value: “The annualized revenue of the user in raw number format”
  • Output: {"revenue":123456}
Address Parameter:
  • Key: street_address
  • Value: “The complete street address including number, street name, and unit if applicable”
  • Output: {"street_address":"123 Main St, Apt 4B"}
Date Parameter:
  • Key: appointment_date
  • Value: “The preferred appointment date in YYYY-MM-DD format”
  • Output: {"appointment_date":"2025-06-18"}

​
Parameter Automation

AI automates the generation of the “value” field based on the input description, simplifying complex data handling. The AI interprets user input and formats it according to your parameter specifications. How It Works:
  1. User provides information in natural language
  2. AI matches the information to parameter descriptions
  3. AI formats the data according to specified requirements
  4. Formatted data is sent to the endpoint URL

​
Key Custom Tool Features

  • ✅ LLM function call integration with API wrapper functionality
  • ✅ Contextual awareness of endpoint responses
  • ✅ Authentication support with Bearer token integration
  • ✅ Flexible parameter handling with automatic data formatting
  • ✅ Real-time API calls for dynamic data retrieval
  • ✅ Multi-stage workflows for complex automation
  • ✅ Cross-platform compatibility for voice and chat AI

​
Best Practices

Tool Design:
  • Create specific, single-purpose tools rather than complex multi-function tools
  • Use clear, descriptive names and descriptions
  • Test thoroughly with various input scenarios
  • Document expected inputs and outputs
Parameter Configuration:
  • Provide detailed parameter descriptions
  • Specify exact data formats required
  • Include validation requirements
  • Consider edge cases and error handling
Security:
  • Use secure authentication methods
  • Limit API key permissions to necessary functions
  • Regularly audit and rotate credentials
  • Validate all incoming data at endpoints
Performance:
  • Optimize endpoint response times
  • Handle errors gracefully
  • Implement appropriate timeouts
  • Monitor tool usage and performance

​
Troubleshooting

Tool not triggering:
  • Review tool description for clarity
  • Ensure trigger conditions are specific
  • Test with various user input scenarios
Authentication errors:
  • Verify Bearer token format and validity
  • Check API key permissions
  • Confirm endpoint authentication requirements
Parameter issues:
  • Validate JSON naming conventions
  • Ensure parameter descriptions are clear
  • Test data formatting and validation
Endpoint problems:
  • Verify URL accessibility and format
  • Check POST request handling
  • Review response data structure