> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visitoai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Herramientas personalizadas de IA

> Registra acciones de backend que la IA de Visito puede consultar o ejecutar durante una conversación.

Las herramientas permiten consultar datos en tiempo real o ejecutar acciones aprobadas, como comprobar disponibilidad, crear un ticket o consultar un pedido.

## Endpoints

| Operación                    | Endpoint                                     |
| ---------------------------- | -------------------------------------------- |
| Listar / crear               | `GET /tools`, `POST /tools`                  |
| Leer / actualizar / eliminar | `GET`, `PATCH`, `DELETE /tools/{toolId}`     |
| Probar                       | `POST /tools/{toolId}/test`                  |
| Registros                    | `GET /tools/logs`, `GET /tools/logs/{logId}` |

Scopes: `tools:read`, `tools:write`, `tools:execute` y `tools:logs:read` según la operación.

## Definir una herramienta

Incluye:

* Nombre y descripción que indiquen cuándo debe usarla la IA.
* Método y endpoint HTTPS.
* Autenticación almacenada de forma segura.
* Parámetros definidos con JSON Schema.
* Estado inactivo hasta completar las pruebas.

## Requisitos del endpoint

* Valida todos los parámetros.
* Responde con JSON breve y estable.
* Usa timeouts y operaciones idempotentes cuando existan mutaciones.
* No registres tokens, contraseñas ni datos innecesarios.
* Devuelve errores claros sin filtrar información interna.

## Pruebas y registros

Usa `/test` antes de activar la herramienta. Revisa los logs para analizar entrada, salida, duración, estado y errores. Un intento de herramienta consume un crédito aunque no devuelva el resultado esperado.

<Warning>
  Mantén credenciales y lógica sensible en el servidor. Solicita aprobación humana antes de habilitar acciones con efectos importantes.
</Warning>