Tools

A tool is one of your HTTP APIs that an agent can call during a conversation: fetch an order, check a balance, create a booking. The AI decides when to call a tool from its name and description, fills the parameters from the conversation, and uses the response to answer.

Open the tools of an agent

Open the agent in Communication > AI Agents and go to its API Connectors tab.

Add a tool

Name: unique, in snake_case, for example get_order or confirm_payment.
State: whether the agent may use the tool. Disable it while your API is under maintenance.
Description: what the tool does and when to use it. The AI relies on it to decide, so be explicit:

Returns the status and the delivery date of an order from its reference (for example A-1042).
Use it when the customer asks where their order is.

Define the endpoint and headers

Method: GET, POST, PUT, DELETE…
URL: the full URL of your API, for example https://api.example.com/orders/{reference}.
Headers: authentication and content type, for example Authorization: Bearer ....

Secrets stored in headers are encrypted.

Define the parameters

Each parameter has:

a name, unique within the tool, for example reference;
a type: STRING, INTEGER or BOOLEAN; a STRING can be limited to a list of possible values;
a mandatory flag;
a description telling the AI how to fill it, for example “The order reference, such as A-1042”.

Return responses the AI understands

Return JSON or plain text whose meaning is clear without your internal documentation:

{
  "success": true,
  "message": "Order found",
  "body": {
    "reference": "A-1042",
    "status": "shipped",
    "estimated_delivery": "2026-10-28"
  }
}

Prefer explicit field names and short messages; on errors, return a sentence the AI can relay, such as “No order found with this reference”.

Test a tool

Use Debug on an endpoint to call it with sample parameters and see the response before the agent uses it.

Monitor the calls

The Connectors Logs of the agent list every call: time, parameters, response status and duration, and errors.

A tool that fails often makes the agent’s answers worse. Check the logs after each change of your API.

Examples

Use	Tool	Endpoint
Look up a customer	`get_customer`	`GET /customers/{phone}`
Track an order	`get_order`	`GET /orders/{reference}`
Confirm a payment	`confirm_payment`	`POST /payments/verify`
Open a request in your system	`create_request`	`POST /requests`

Introduction

Getting started

Agents

Integrators

Channels

Inbox

Open the tools of an agent

Add a tool

Define the endpoint and headers

Define the parameters

Return responses the AI understands

Test a tool

Monitor the calls

Examples

​Open the tools of an agent

​Add a tool

​Define the endpoint and headers

​Define the parameters

​Return responses the AI understands

​Test a tool

​Monitor the calls

​Examples

Open the tools of an agent

Add a tool

Define the endpoint and headers

Define the parameters

Return responses the AI understands

Test a tool

Monitor the calls

Examples