# Custom tools

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

- Page: https://tbit.app/docs/api/custom-tools
- Base URL: `https://rest-api.tbit.app/v1`
- Authentication: `X-API-Key` header with your key on every request (the examples read it from the `TBIT_API_KEY` environment variable)

## 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.