Tools

Tools let your agents call external APIs during live conversations: look up data, book appointments, update CRM records, and more. By connecting tools to an agent, you give it the ability to take real actions on behalf of the caller without any human intervention.

How Tools Work

When a caller says something that matches a tool's trigger criteria, the following sequence takes place:

1. Intent detection: The AI recognises that the caller's request matches a configured tool based on the tool's name and description.
2. Parameter extraction: The AI extracts the required parameters from the conversation context. For example, if the tool needs a phone number, the AI pulls it from what the caller has already said.
3. API call: Cloudax Connect sends an HTTP request to the tool's configured URL with the extracted parameters. While the request is in flight, the agent speaks the engagement message to keep the caller informed (e.g. "Let me look that up for you.").
4. Response handling: The API response is fed back to the AI, which uses the returned data to continue the conversation naturally.

Creating a Tool

Tool Name

A unique identifier for the tool. Use only lowercase letters and underscores: no spaces, hyphens, or special characters, and no consecutive double underscores. The name can be up to 20 characters long. Choose something descriptive so you can recognise the tool at a glance (e.g. crm_lookup, book_appointment).

API request

Choose the HTTP method and the full URL of the external API endpoint the tool will call. The URL must be a publicly accessible endpoint (HTTPS in production). For example: https://api.example.com/v1/customers/lookup.

The method dropdown supports GET, POST, PUT, PATCH and DELETE (defaults to POST). With GET, the extracted parameters are sent as the URL query string; with POST, PUT, PATCH and DELETE they are sent as a JSON request body.

Description

A short explanation of what the tool does and when the agent should use it. The description is the AI's primary signal for deciding when to invoke the tool, so be specific. Mention the kind of caller request that should trigger it, what data it returns, and any limitations. For example:

Looks up an existing customer record in the CRM by phone number. Use this when the caller asks about their account, order status, or wants to verify their identity. Returns the customer's name, email, and most recent order.

Engagement Message

The phrase the agent speaks aloud while the external API call is in progress. This keeps the conversation flowing and reassures the caller that something is happening. Examples:

• "Let me look that up for you."
• "One moment whilst I check your booking."
• "I'm pulling up your account now."

Headers

Custom HTTP headers sent with every request, defined as key/value pairs. Use this to pass static values like content type, identifying headers, or any authentication credentials your API expects (for example an Authorization bearer token, an X-Api-Key header, or a basic-auth header):

Content-Type: application/json
Authorization: Bearer sk_live_••••••••
X-Source: cloudax-connect

Headers are sent on every tool invocation. Use them to lock down your endpoint to requests that originate from Cloudax Connect.

Configuration Parameters

Each parameter you define tells the AI exactly which value to extract from the conversation and pass to your API. A parameter is a title (the field name your API expects) plus a description explaining what it represents.

For example, a CRM lookup tool that needs a phone number might define a single parameter:

The description is the AI's instruction for how to format the value, so be as specific as possible. Mentioning "E.164 format", for instance, tells the AI to normalise the number before sending it. You can add as many parameters as your API needs.

Request Payload

By default, the parameters above are sent to your endpoint as a JSON body (or as the query string for GET). If your API expects a specific shape, open the Payload editor to design the exact request body yourself. Write the JSON your endpoint wants and drop in variables wherever you need a live value. Type {{ inside any string to see the full list with autocomplete.

{
  "customer": {
    "phone": "{{parameters.phone_number}}",
    "source": "cloudax-connect"
  },
  "callId": "{{call.call_sid}}",
  "direction": "{{call.call_direction}}"
}

Common variables include {{parameters.<name>}} for each configuration parameter the AI fills in, and call context like {{call.from_number}}, {{call.to_number}}, {{call.call_direction}} and {{call.call_sid}}. You can also insert {{parameters}} or {{call}} to include the whole object. To send a value Base64-encoded, wrap it as {{base64(parameters.name)}}.

Use the format dropdown to pick how the body is sent:

• application/json: the template is sent as a JSON body (the default).
• application/x-www-form-urlencoded: the template is sent as form fields. Form payloads must use top-level scalar values or scalar lists.
• Custom Content-Type: the body is still JSON-serialised, but sent with a media type you specify (e.g. application/vnd.example+json).

Tool Execution Logs

Every time a tool is invoked during a call, Cloudax Connect records a detailed execution log. You can view these logs on the Actions page, where each entry shows:

• The tool name and the agent that triggered it
• The extracted parameters sent in the request
• The HTTP status code and response body
• Execution duration in milliseconds
• A timestamp and the associated call ID

Use these logs to debug tool behaviour, monitor API reliability, and understand how your agents are interacting with external services.

Example: CRM Lookup Tool

Below is a complete configuration for a tool that looks up a customer record in a CRM system using the caller's phone number.

Configuration Parameters: