# Tools personalizadas

> Deja que la IA llame a tu API en medio de una conversación

- Página: https://tbit.app/es/docs/api/custom-tools
- URL base: `https://rest-api.tbit.app/v1`
- Autenticación: encabezado `X-API-Key` con tu clave en cada solicitud (los ejemplos la leen de la variable de entorno `TBIT_API_KEY`)

## Descripción general

Una tool personalizada es un endpoint tuyo que el agente puede llamar mientras habla con un cliente: consultar un crédito por cédula, revisar stock, abrir un ticket. Tú describes cuándo aplica y qué parámetros necesita; la IA decide cuándo llamarla, llena los parámetros con lo que dijo el cliente y responde con lo que devolvió tu API. Hasta 15 tools por agente.

## Definición

Cada tool es una entrada con estos campos:

|  |
|  |
| `name` | Nombre técnico con el que la IA la llama: letras, números y guión bajo (consultar_credito). |
| `description` | Cuándo usarla y qué devuelve. Es lo que la IA lee para decidir; escríbela como instrucción («Consulta un crédito por cédula; devuelve saldo y cuotas»). |
| `parameters` | Lista de {name, type (string \| number \| boolean \| enum), description, required, enum_values}. La IA los llena con lo que dijo el cliente. |
| `method + endpoint` | GET, POST, PUT o DELETE y la URL completa. |
| `auth` | NONE, BEARER (Authorization: Bearer <token>), API_KEY (nombre y valor de header que tú eliges) o BASIC (usuario y contraseña). |
| `headers` | Headers extra que van en cada llamada. |
| `body_template` | Plantilla JSON opcional con {{param}}. Sin ella, POST/PUT mandan los parámetros como objeto JSON. |
| `response_path` | Ruta con puntos opcional (data.results) a la parte de la respuesta que la IA debe leer. |

## Cómo se hace la llamada

GET y DELETE agregan los parámetros a la URL como query string. POST y PUT los mandan como body JSON: o el body_template ya rellenado. Los headers de auth y los extra van en cada llamada. Responde 2xx con JSON: la IA recibe el body (o la parte de response_path) como texto y lo usa para contestar. Un código distinto de 2xx le llega a la IA como «API returned <status>» y le dice al cliente que no pudo consultar; no hay reintentos automáticos.

## Cómo crear una

- Canvas (newui.tbit.app): pregunta «¿qué tools personalizadas tengo?» → la lista tiene «Nueva tool…»; cada fila abre la tool con Editar. Un formulario pide todo lo de arriba; los secretos que dejes vacíos al editar se conservan.
- MCP (Claude, ChatGPT…): list_custom_tools para leerlas, manage_custom_tool con action=create | update | delete. El cambio se propone y tú lo confirmas.
- App de la plataforma: Integraciones → API personalizada.

## Ejemplo: crear desde el 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"
}
```

## Qué recibe tu endpoint

Con el ejemplo de arriba, cuando un cliente pregunta por su crédito la IA llama:

```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" } }
```

## Buenas prácticas

- Escribe la descripción para la IA, no para un desarrollador: cuándo usarla y qué vuelve.
- Marca como obligatorio solo lo que la IA debe pedirle al cliente; lo demás dale un valor por defecto de tu lado.
- Mantén los GET idempotentes: la IA puede llamar la misma tool dos veces en una conversación si el primer intento falló.
- Devuelve JSON pequeño y plano. Usa response_path si tu API envuelve los resultados.