Agent Tools - RevRing AI Documentation

Tools enable your AI agents to take actions during phone calls beyond just conversation. RevRing provides built-in system tools and supports custom tools via webhooks.

System Tools

System tools are pre-built capabilities that agents can invoke during calls. These tools are configured in the Tools tab of your agent settings.

End Call

The End Call tool allows agents to automatically terminate calls based on configurable rules.

When to Use

Calls that have reached their natural conclusion
Customer explicitly ends the conversation
Maximum conversation time is reached
Call objective has been completed

Configuration

Navigate to the Tools tab
Locate End Call under System Tools
Toggle the switch to enable
Click Configure to customize behavior
Set End Call Rules Override to define when the agent should end calls:

End the call when:
- The customer says goodbye or indicates they're done
- The appointment has been confirmed
- The customer explicitly asks to end the call
- You've provided all requested information and there are no further questions
- The conversation has exceeded 5 minutes

Click Save

If you leave the rules override empty, RevRing uses sensible defaults. Custom rules give you more control over call termination behavior.

How It Works

When enabled, the agent has access to an end_call function. During the conversation, if the agent determines (based on the rules) that the call should end, it will:

Invoke the end_call function
Speak a brief closing message
Terminate the call gracefully

You can see end call invocations in the call transcript labeled as “Tool: end_call”.

Transfer

The Transfer tool enables agents to transfer calls to other phone numbers or departments based on conditions you define.

When to Use

Customer requests to speak with a human representative
Issue requires specialized expertise beyond the agent’s scope
Escalation to management or specific departments
Routing to on-call support staff

Configuration

Navigate to the Tools tab
Locate Transfer under System Tools
Toggle the switch to enable
Click Configure to set up transfer routes
Add transfer routes:

Transfer Description Override (optional):

Offer to transfer when:
- The customer requests to speak with a human
- The issue is complex and beyond your capabilities
- The customer is frustrated or dissatisfied
- Billing or payment questions arise

Transfer Routes:

To number: +12025559999 (destination phone number in E.164 format)
Condition: Transfer to sales team for pricing questions or to close deals

Click Add route to add multiple destinations.

Click Save

You can configure multiple transfer routes for different scenarios. The agent will choose the appropriate route based on the conversation context and conditions you define.

How It Works

When enabled, the agent can invoke the transfer_to_number function with the destination number. RevRing uses the SIP REFER method to transfer the call to the destination. Once the transfer is initiated:

The call is handed off to the destination number
RevRing’s involvement ends (billing stops and recording ends)
The caller continues their conversation with the transfer destination

The transfer appears in the call transcript showing:

Tool invocation: “Tool: transfer_to_number”
Destination number
Transfer status (success or failure)

Provider Setup Required: Ensure your SIP trunk provider supports SIP REFER and has call transfers enabled. Some providers like Twilio require enabling PSTN Transfer in your trunk settings. See the Telephony Setup guide for details.

Voicemail Detection

Voicemail Detection automatically identifies when an outbound call reaches an answering machine or voicemail system.

When to Use

Outbound calling campaigns where live conversations are preferred
Appointment reminders or confirmations
Sales or follow-up calls
Any scenario where leaving a message is optional

Configuration

Navigate to the Tools tab
Locate Voicemail Detection under System Tools
Toggle the switch to enable
Click Configure to set behavior
Choose Voicemail Action:
- Hangup: Immediately end the call when voicemail is detected (saves costs)
- Leave Message: Speak a pre-recorded message before hanging up
If you selected “Leave Message”, configure Voicemail Message:

Hi, this is a message from Acme Corp. We tried reaching you regarding your appointment. Please call us back at 1-800-555-0123. Thank you.

Click Save

Voicemail detection is most effective for outbound calls. For inbound calls, it’s typically not needed since customers are calling you.

How It Works

When an outbound call connects, RevRing analyzes the audio to detect voicemail systems. If detected:

Hangup action: Call ends immediately, marked as “voicemail” in logs
Leave message action: Agent speaks the configured message, then hangs up

Detection accuracy is typically very high but not perfect. Review call logs to monitor detection performance.

Custom Tools

Custom tools allow you to extend agent capabilities by integrating with your own systems via webhooks. When the agent invokes a custom tool, RevRing calls your webhook with the tool’s arguments and includes the response in the conversation.

Use Cases

CRM lookups: Fetch customer information during calls
Order status: Check order or shipment status
Appointment booking: Create or modify appointments in your calendar system
Payment processing: Initiate payments or check account balances
Inventory checks: Verify product availability
Custom business logic: Any operation specific to your workflow

Creating a Custom Tool

Navigate to the Tools tab
Scroll to the Custom Tools section
Enter a Friendly Name for your tool (e.g., “Order Status Checker”)
Enter your Webhook URL (e.g., https://api.yourcompany.com/tools/check-order)
Click Add Tool

The tool will appear in the table below. Click Edit to define the tool’s schema.

The Friendly Name is just a label for the dashboard. The actual function name that the agent uses is defined in the name field of your JSON schema (e.g., check_order_status).

Defining the Tool Schema

The schema defines what parameters the tool accepts using OpenAI’s function calling format:

Click Edit on your custom tool
In the Schema JSON field, enter your tool definition:

{
  "type": "function",
  "name": "check_order_status",
  "description": "Check the status of a customer's order by order ID",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The unique order ID (e.g., ORD-12345)"
      }
    },
    "required": ["order_id"],
    "additionalProperties": false
  }
}

Toggle Enabled to activate the tool
Click Save

The description fields are critical - they tell the agent when and how to use the tool. Be clear and specific.

Schema Format Reference

Follow the OpenAI function calling format:

type: Always "function" at the root level (required)
name: Unique identifier for the tool (lowercase, underscores allowed) (required)
description: When the agent should use this tool (required)
parameters: Object defining the tool’s input parameters (required)
- type: Always "object" for the parameters root (required)
- properties: Each parameter with its type and description (use {} for tools with no inputs)
- required: Array of required parameter names (optional)

For tools without inputs: You must still include the parameters object with type: "object" and empty properties:

{
  "type": "function",
  "name": "get_current_weather",
  "description": "Get the current weather",
  "parameters": {
    "type": "object",
    "properties": {}
  }
}

Webhook Implementation

When the agent invokes your custom tool, RevRing POSTs to your webhook URL: Request:

{
  "callId": "dc582fd6-4e5c-4860-9ced-abc7390e62a9",
  "tool": "check_order_status",
  "arguments": {
    "order_id": "ORD-12345"
  }
}

Response Examples: You can return either JSON or plain text:

{
  "status": "out_for_delivery",
  "expected_delivery": "2025-11-24T17:00:00Z",
  "tracking_number": "1Z999AA10123456784"
}

Or:

Order ORD-12345 is currently out for delivery. Expected delivery today by 5 PM.

The agent will receive the response and incorporate it into the conversation naturally.

Response Format

Your webhook should return:

200 OK status code
JSON object or plain text response body
Response within 8 seconds (recommended: under 3 seconds for best user experience)

JSON Response Example:

{
  "appointments": [
    {
      "date": "2025-11-25",
      "time": "14:00",
      "type": "checkup"
    }
  ],
  "total_count": 3
}

Plain Text Response Example:

Customer has 3 active appointments. Next appointment is tomorrow at 2 PM.

The agent will interpret the response and communicate the information to the caller naturally.

Best Practices for Custom Tools

Clear Descriptions

The agent uses descriptions to decide when to invoke tools. Be specific: Good:

Check the status of a customer's order by order ID. Use this when the customer asks about their order, shipment, or delivery status.

Bad:

Check order

Error Handling

Handle errors gracefully in your webhook. You can return structured error data or error messages:

{
  "error": "order_not_found",
  "message": "Order number not found in system"
}

Or plain text:

I couldn't find that order number in our system. Could you verify the order number?

The agent will communicate the error to the caller appropriately.

Performance

Keep webhook response times under 3 seconds
Implement timeouts and retries in your webhook code
Cache frequently accessed data when possible
Use async processing for complex operations (return immediately with a status message)

Security

Validate requests are coming from RevRing (contact support for HMAC signing setup)
Sanitize and validate all input parameters
Use HTTPS for all webhook URLs
Implement rate limiting to prevent abuse

Testing Custom Tools

Create a simple test tool that returns static data
Use the Test Agent tab to make a call
During the call, prompt the agent to use the tool:
- “Can you check order ORD-12345 for me?”
Review the transcript to see:
- Tool invocation with arguments
- Your webhook’s response
- How the agent incorporated the result into conversation

Viewing Tool Invocations

All tool invocations appear in call transcripts with detailed information:

Tool name: Which tool was invoked
Arguments: What parameters were passed
Status: Success (ok) or error
Response: What your webhook returned

Navigate to Call Logs, select a call, and review the transcript pane.

Tool Limitations

System Tool Constraints

End Call: Once invoked, the call ends immediately - the agent cannot continue conversation
Transfer: After transfer, the agent disconnects - the call continues with the transfer destination
Voicemail Detection: Only works on outbound calls, not inbound calls

Custom Tool Constraints

Response time: 8 second timeout - webhooks must respond within this window
Concurrent invocations: Agents invoke tools sequentially, not in parallel

Managing Tools

Editing Tools

To modify a custom tool:

Navigate to the Tools tab
Click Edit on the tool in the table
Update friendly name, webhook URL, schema, or enabled status
Click Save

Changes take effect immediately for new calls.

Deleting Tools

To remove a custom tool:

Navigate to the Tools tab
Click Delete on the tool in the table
Confirm the deletion

Deleting a tool that’s actively referenced in your agent’s behavior may cause unexpected results. Update your prompt to remove references to deleted tools.

Disabling Tools Temporarily

Instead of deleting, you can disable tools:

Click Edit on the tool
Toggle Enabled to off
Click Save

The agent will not have access to disabled tools, but the configuration is preserved for future re-enabling.

Advanced Tool Patterns

Chaining Tools

Agents can invoke multiple tools in sequence to accomplish complex tasks:

Customer asks: “What’s my balance and when is my next payment due?”
Agent invokes get_account_balance → receives balance
Agent invokes get_next_payment_date → receives date
Agent combines both results in response

Design tools to be focused and composable rather than monolithic.

Conditional Tool Usage

Guide the agent to use tools conditionally based on conversation context:

Use the transfer_to_billing tool only when:
- Customer has billing questions you cannot answer
- Customer disputes a charge
- Customer wants to discuss payment plans

Do NOT transfer for simple balance inquiries - use the check_balance tool instead.

Tool Results in Follow-Up

Agents can reference previous tool results later in the conversation:

Agent: “I checked your order ORD-12345, and it’s out for delivery today.” Customer: “Great! And what about my other order?” Agent: “Let me check that for you…” [invokes tool again with new order ID]

Troubleshooting

Custom tool not being invoked

Verify the tool is enabled (toggle is on)
Check that the description clearly indicates when to use the tool
Ensure your prompt doesn’t contradict or override the tool’s purpose
Test by explicitly asking the agent to use the tool during a test call
Review the schema - overly complex parameters may confuse the agent

Webhook not receiving requests

Confirm the webhook URL is correct and publicly accessible
Check that your server is running and responding to POST requests
Test the endpoint independently with curl or Postman
Review your server logs for incoming requests

Tool returns error in transcript

Verify webhook responds within 8 seconds
Ensure response is valid JSON or plain text
Check HTTP status code (should be 200)
Review your webhook logs for errors or exceptions
Test the webhook endpoint independently with sample data

Agent misuses the tool

Refine the tool’s description to be more specific about usage
Update your prompt to provide clearer guidance on when to use tools
Adjust parameter descriptions to clarify expected formats
Consider splitting complex tools into simpler, focused tools

Transfer doesn't work

Verify the destination number is in valid E.164 format
Ensure your SIP trunk supports call transfers
Check that the destination number is reachable
Review call logs for specific transfer error messages

Next Steps

Webhooks

Learn about pre-call and post-call webhooks

API Reference

Manage custom tools programmatically via API

Inbound Calls

Configure agents for handling inbound calls

Outbound Calls

Send outbound calls with your agents

Getting started

Platform

​System Tools

​End Call

​When to Use

​Configuration

​How It Works

​Transfer

​When to Use

​Configuration

​How It Works

​Voicemail Detection

​When to Use

​Configuration

​How It Works

​Custom Tools

​Use Cases

​Creating a Custom Tool

​Defining the Tool Schema

​Schema Format Reference

​Webhook Implementation

​Response Format

​Best Practices for Custom Tools

​Clear Descriptions

​Error Handling

​Performance

​Security

​Testing Custom Tools

​Viewing Tool Invocations

​Tool Limitations

​System Tool Constraints

​Custom Tool Constraints

​Managing Tools

​Editing Tools

​Deleting Tools

​Disabling Tools Temporarily

​Advanced Tool Patterns

​Chaining Tools

​Conditional Tool Usage

​Tool Results in Follow-Up

​Troubleshooting

​Next Steps

Webhooks

API Reference

Inbound Calls

Outbound Calls

System Tools

End Call

When to Use

Configuration

How It Works

Transfer

When to Use

Configuration

How It Works

Voicemail Detection

When to Use

Configuration

How It Works

Custom Tools

Use Cases

Creating a Custom Tool

Defining the Tool Schema

Schema Format Reference

Webhook Implementation

Response Format

Best Practices for Custom Tools

Clear Descriptions

Error Handling

Performance

Security

Testing Custom Tools

Viewing Tool Invocations

Tool Limitations

System Tool Constraints

Custom Tool Constraints

Managing Tools

Editing Tools

Deleting Tools

Disabling Tools Temporarily

Advanced Tool Patterns

Chaining Tools

Conditional Tool Usage

Tool Results in Follow-Up

Troubleshooting

Next Steps