API

Custom tools

Let the AI call your API in the middle of a conversation

Overview

A custom tool is an endpoint of yours that the agent can call while talking to a customer: look up a loan by ID number, check stock, open a ticket. You describe when it applies and which parameters it needs; the AI decides when to call it, fills the parameters from the conversation and answers with what your API returned. Up to 15 tools per agent.

Definition

Each tool is one entry with these fields:

`name`	Technical name the AI calls it by: letters, digits and underscore (consultar_credito).
`description`	When to use it and what it returns. This is what the AI reads to decide; write it as an instruction (“Looks up a loan by ID number; returns balance and installments”).
`parameters`	List of {name, type (string \| number \| boolean \| enum), description, required, enum_values}. The AI fills them from what the customer said.
`method + endpoint`	GET, POST, PUT or DELETE and the full URL.
`auth`	NONE, BEARER (Authorization: Bearer <token>), API_KEY (a header name and value you choose) or BASIC (username and password).
`headers`	Extra headers sent on every call.
`body_template`	Optional JSON template with {{param}} placeholders. Without it, POST/PUT send the parameters as a JSON object.
`response_path`	Optional dotted path (data.results) to the part of the response the AI should read.

How the call is made

GET and DELETE append the parameters to the URL as a query string. POST and PUT send them as a JSON body: or the rendered body_template. Auth headers and extra headers go on every call. Answer 2xx with JSON: the AI receives the body (or the response_path part) as text and uses it to answer. A non-2xx status reaches the AI as “API returned <status>” and it tells the customer it could not check; there are no automatic retries.

How to create one

Canvas (newui.tbit.app): ask “what custom tools do I have?” → the list has “New tool…”; each row opens the tool with Edit. A form asks for everything above; secrets you leave empty on edit are kept.
MCP (Claude, ChatGPT…): list_custom_tools to read them, manage_custom_tool with action=create | update | delete. The change is proposed and you confirm it.
Platform app: Integrations → Custom API.

Example: create from the MCP

json

manage_custom_tool
{
  "action": "create",
  "name": "consultar_credito",
  "description": "Consulta el estado de un crédito por número de cédula; devuelve saldo, cuotas pendientes y próxima fecha de pago.",
  "method": "GET",
  "endpoint": "https://api.tunegocio.com/v1/creditos",
  "parameters": [
    { "name": "cedula", "type": "string", "description": "Cédula del cliente, solo dígitos", "required": true }
  ],
  "auth_type": "BEARER",
  "auth_token": "<tu token>",
  "response_path": "data"
}

What your endpoint receives

For the example above, when a customer asks about their loan the AI calls:

http

GET https://api.tunegocio.com/v1/creditos?cedula=1032456789
Authorization: Bearer <tu token>
Accept: application/json

→ 200 { "data": { "saldo": 1250000, "cuotas_pendientes": 3, "proximo_pago": "2026-10-05" } }

Good practices

Write the description for the AI, not for a developer: when to use it and what comes back.
Mark as required only what the AI must ask the customer for; give the rest a default on your side.
Keep GET calls idempotent: the AI may call the same tool twice in one conversation if the first attempt failed.
Return small, plain JSON. Use response_path if your API wraps results.