Herramientas (tools)

Define las herramientas que tu modelo puede llamar, identifícalas en tus conversaciones e inserta los tool calls en tus datos de entrenamiento.

Qué es una herramienta

Una herramienta es la definición de una función que un modelo puede llamar: nombre, descripción y parámetros en JSON Schema. Si es de tipo Function Tool, además guarda el endpoint HTTP que ejecuta la acción y su autenticación.

El modelo lee la descripción para decidir cuándo llamar a la herramienta. Escríbela clara: qué hace, cuándo usarla y qué devuelve.

En el menú lateral	Qué abre
Herramientas › Ver todas	La tabla con las herramientas de tu organización.
Herramientas › Crear	El asistente “Nueva herramienta MCP”.
Herramientas › Identificar herramientas	La página para identificar herramientas en tus conversaciones.
Herramientas › Servidores MCP	El constructor de servidores MCP.

Disponibilidad y límites

Identificar herramientas en tus conversaciones está en todos los planes. Crear, guardar, probar desde el servidor y generar servidores MCP requiere Starter+.

Plan	Crear y guardar	Herramientas nuevas por análisis	Conversaciones por análisis
Gratuito	No	3	50
Starter	Sí	10	200
Growth	Sí	25	500
Professional	Sí	Ilimitadas	Ilimitadas

Tope de 20 herramientas por organización

Sin importar tu plan, tu organización guarda hasta 20 herramientas. El contador aparece junto al título de la tabla y el botón Crear se desactiva al llegar al tope.

Abre el asistente y elige el tipo

Entra a Herramientas › Crear o haz clic en Crear en la tabla. Se abre el asistente Nueva herramienta MCP. Elige el tipo:

Tipo	Para qué sirve
Function Tool	Ejecuta una acción en tu API. Es el único tipo con endpoint y autenticación.
Prompt	Template de prompt reutilizable.
Resource	Recurso de datos accesible.

Prompt y Resource se saltan los pasos 3 y 4: guardan nombre, descripción y tipo.

Escribe nombre y descripción

Proyecto: el proyecto al que pertenece la herramienta.
Nombre: identificador único en snake_case, por ejemplo buscar_inventario o enviar_correo. Hasta 100 caracteres.
Descripción: lo que el modelo lee para decidir cuándo invocarla.

Configura el endpoint y los parámetros

Elige el método HTTP (GET, POST, PUT, PATCH o DELETE) y la URL completa de tu API, que debe empezar con http:// o https://. El botón Probar comprueba desde tu navegador que el endpoint responde.

Define los parámetros con el constructor visual (nombre, tipo, descripción, si es requerido y, para string, una lista de valores permitidos) o marca Pegar JSON y pega un JSON Schema. Los tipos disponibles son string, number, boolean, array y object.

parameters (JSON Schema)

{
  "type": "object",
  "properties": {
    "producto": {
      "type": "string",
      "description": "Nombre o SKU del producto"
    },
    "sucursal": {
      "type": "string",
      "description": "Sucursal a consultar",
      "enum": [
        "centro",
        "norte",
        "sur"
      ]
    }
  },
  "required": [
    "producto"
  ]
}

Configura la autenticación

Elige Sin autenticación, Bearer Token, API Key o Basic Auth, y el nombre del header (por ejemplo Authorization o X-API-Key). Aquí también agregas headers fijos que se envían en cada request.

El valor de la credencial no se escribe en este paso: se configura como variable de entorno al desplegar el servidor (ver Servidores MCP).

Revisa y guarda

Revisa el resumen y la vista previa MCP. Guarda con Guardar borrador (queda como Borrador) o con Guardar y crear.

Tabla de herramientas

Herramientas › Ver todas muestra las herramientas de tu organización con estas columnas:

Columna	Qué muestra
Nombre	El identificador de la herramienta.
Método	GET, POST, PUT, PATCH o DELETE.
Endpoint	La URL que llama la herramienta.
Deploy	Activo, Pendiente, Error o Borrador.
Estado	On u Off: si la herramienta está activa.
Creado	Fecha de creación.

Puedes buscar por nombre, descripción o endpoint, filtrar por método y por estado de despliegue (desplegados, borradores o con error) y ordenar por nombre, método o fecha. Selecciona varias filas para eliminarlas juntas.

Inspector

Haz clic en una herramienta para abrir su panel lateral, con tres pestañas:

Detalles

Edita nombre, descripción, endpoint y parámetros, y activa o desactiva la herramienta.

JSON

La definición completa de la herramienta, lista para copiar.

Test

Envía una petición con parámetros de prueba y muestra el status, la respuesta y la duración.

La prueba sale de tu navegador

Tanto Test como el botón Probar del asistente llaman a tu endpoint desde el navegador. Si falla, revisa la URL y que tu API permita CORS.

Editar una herramienta activa

Cuando una herramienta está activa (conmutador On), el agente ya la llama en producción. Por eso AstrApp protege sus parámetros al editarla, ya sea desde el asistente, desde el inspector o por la API.

Qué pasa al guardar

Un parámetro con el mismo nombre nunca se duplica: se actualiza el existente.
Un parámetro nuevo entra como opcional, aunque lo marques requerido.
No puedes quitar un parámetro. Desactiva la herramienta primero (o marca Desactivar la herramienta al guardar en el asistente).
Si un parámetro pasa a requerido o cambia de tipo, AstrApp te pide confirmarlo.

En el inspector, la confirmación (Guardar de todos modos) aparece dentro del propio panel de edición, no en una notificación aparte. En el asistente, al editar una herramienta solo existe Guardar cambios: no hay "Guardar borrador" porque guardar un borrador no pausa una herramienta que ya existe (seguiría activa); para dejar de usarla, desactívala.

Respuestas de PATCH /api/v1/tools/{toolId}

Si parameters tiene una forma inválida (por ejemplo properties que no es un objeto, required que no es un arreglo de strings, una propiedad que no es un objeto, un type fuera de string, number, integer, boolean, array u object, una description que no es string o un enum que no es arreglo de strings) responde 400 con code: "INVALID_PARAMETERS". Un dato ya guardado con esa forma inválida (por ejemplo una herramienta identificada desde conversaciones) puedes reenviarlo sin cambios sin que esto falle.

Responde 409 con code: "BREAKING_CHANGE" si se quitaría un parámetro de una herramienta activa, o code: "COMPAT_WARNING" si un parámetro pasa a requerido o cambia de tipo. Para confirmar un COMPAT_WARNING, repite la petición con "acknowledge_breaking": true. En ambos casos, error.details lista cada parámetro con su motivo.

Responde 409 con code: "CONFLICT" si otro proceso cambió la herramienta mientras la editabas; recarga y vuelve a intentar. Un 200 exitoso incluye ajustes: los parámetros nuevos que pediste requeridos y se guardaron como opcionales por estar la herramienta activa.

La forma abreviada { "q": "string" } guardada antes de esta validación se conserva tal cual (equivale a { "q": { "type": "string" } }), pero no puedes enviar una forma abreviada nueva: cada propiedad debe ser un objeto.

Sincronizar parámetros desde Supabase

En el paso 3 del asistente (Configura el endpoint y los parámetros), el botón Sincronizar desde Supabase lee las columnas de una tabla con la service_role key de tu conector de Supabase (la configuras en Conectores; AstrApp la guarda cifrada y nunca la devuelve). Elige las columnas, revisa el diff que se agregaría o actualizaría y aplícalo. La sincronización solo agrega parámetros nuevos o actualiza el tipo y la descripción de los que ya tienes: nunca quita ninguno. Las columnas id, created_at y updated_at se omiten.

POST /api/v1/tools/introspect

Con { "connector_id": "<uuid>" } devuelve las tablas del proyecto de Supabase del conector. Con "table": "<nombre>" devuelve columns y los parameters equivalentes; acepta "include_system_columns": true para no omitir id, created_at y updated_at.

Tiene un límite de 10 peticiones por minuto por IP. Si Supabase rechaza la service_role key, responde con un mensaje que te dice revisarla en Conectores; un esquema de más de 20 MB se rechaza.

Simulador

El botón Simulador de la tabla abre una prueba rápida: escribes un mensaje como si fueras un usuario y ves, paso a paso, el mensaje, la herramienta elegida, los parámetros generados y la respuesta.

Es una simulación local

El simulador no llama a ningún modelo ni a tu endpoint. Elige la herramienta activa cuyo nombre y descripción comparten más palabras con el mensaje, llena parámetros de ejemplo y muestra una respuesta ficticia. Sirve para revisar que tus nombres y descripciones usen las palabras de tus usuarios; para probar el endpoint real usa la pestaña Test.

Servidores MCP

Entra a Herramientas › Servidores MCP o usa el botón Construir MCP de la tabla. El constructor agrupa hasta 20 herramientas en una sola Edge Function de Supabase, en cinco pasos:

Paso	Qué pasa
Seleccionar herramientas	Eliges las herramientas, el nombre del servidor y el rate limit (de 30 a 120 peticiones por minuto por IP; 60 por defecto).
Escaneo de seguridad	AstrApp revisa las herramientas. Los hallazgos críticos o altos bloquean el avance.
Preview del código	Ves y copias el código TypeScript (Deno) de la función.
Despliegue	AstrApp genera el código y guarda el registro del servidor.
Conexión MCP	URL de la función, JSON de configuración, ejemplo con cURL, comando de despliegue y variables de entorno necesarias.

Qué revisa el escaneo

Severidad	Qué detecta
Crítica	Un secreto en la URL (key, token, secret, password…) o una URL interna (localhost, 127.x, 10.x, 192.168.x, entre otras).
Alta	Patrones de SQL injection en nombres de parámetros, o parámetros sensibles sin autenticación.
Media	Endpoint con HTTP sin TLS.
Baja	El código generado permite CORS desde cualquier origen.

Despliega y llama a tu servidor

AstrApp no aloja el servidor

El paso Despliegue genera el código, pero no lo publica. Despliégalo en tu propio proyecto de Supabase con el comando del último paso y configura como variables de entorno las credenciales de cada herramienta: TOOL_<NOMBRE>_TOKEN, TOOL_<NOMBRE>_API_KEY o TOOL_<NOMBRE>_USER y TOOL_<NOMBRE>_PASS, según su autenticación.

La función recibe un POST con el nombre de la herramienta y sus parámetros, valida los requeridos y reenvía la llamada al endpoint de esa herramienta:

bash

# Despliega la función en tu proyecto de Supabase
supabase functions deploy mcp-inventario --project-ref <PROJECT_REF>

# Llama a una herramienta
curl -X POST https://<PROJECT_REF>.supabase.co/functions/v1/mcp-inventario \
  -H "Content-Type: application/json" \
  -d '{"tool": "consultar_inventario", "params": {"producto": "SKU-123"}}'

La función no verifica quién la llama: cualquiera con la URL puede usarla, hasta el rate limit por IP.

El botón Desplegar, que aparece con el inspector abierto, hace lo mismo para una sola herramienta: genera su código y la marca como Activo en la columna Deploy.

Identificar herramientas en tus conversaciones

Hay dos caminos. Los dos usan un modelo (Gemini 2.5 Flash, Claude Haiku 4.5 o ChatGPT-4o) y cobran créditos, salvo que hayas conectado tu propia API key de ese proveedor.

Página Identificar herramientas

En Herramientas › Identificar herramientas recorres cuatro pestañas: Importar, Configurar, Resultados y Generar (aparece cuando se identificaron herramientas).

Está en todos los planes, con los topes por análisis de la tabla de arriba. Guardar las herramientas encontradas requiere Starter+.

Desde Conversaciones

Selecciona conversaciones y haz clic en Identificar herramientas en la barra de acciones. Requiere Starter+.

Analiza hasta 30 de las conversaciones seleccionadas y propone un catálogo.
Revisas y editas el catálogo, y eliges el formato de los tool calls.
Ves una vista previa con 5 conversaciones.
Inserta los tool calls en las conversaciones y guarda las herramientas.

Formato de los tool calls

Al insertar tool calls en tus conversaciones eliges uno de estos dos formatos. Usa el que espere el modelo que vas a entrenar.

OpenAI Structured

El mensaje del asistente lleva tool_calls con arguments como string JSON, seguido de un mensaje con rol tool.

messages (OpenAI)

[
  {
    "role": "user",
    "content": "¿Tienen el SKU-123 en la sucursal centro?"
  },
  {
    "role": "assistant",
    "content": null,
    "tool_calls": [
      {
        "id": "call_1",
        "type": "function",
        "function": {
          "name": "consultar_inventario",
          "arguments": "{\"producto\":\"SKU-123\",\"sucursal\":\"centro\"}"
        }
      }
    ]
  },
  {
    "role": "tool",
    "name": "consultar_inventario",
    "content": "{\"disponibles\":4}"
  },
  {
    "role": "assistant",
    "content": "Sí, hay 4 piezas en la sucursal centro."
  }
]

Qwen ChatML

La llamada va dentro del content del asistente entre <tool_call>, y la respuesta en un mensaje tool entre <tool_response>.

messages (Qwen ChatML)

[
  {
    "role": "user",
    "content": "¿Tienen el SKU-123 en la sucursal centro?"
  },
  {
    "role": "assistant",
    "content": "<tool_call>{\"name\":\"consultar_inventario\",\"arguments\":{\"producto\":\"SKU-123\",\"sucursal\":\"centro\"}}</tool_call>"
  },
  {
    "role": "tool",
    "content": "<tool_response>{\"disponibles\":4}</tool_response>"
  },
  {
    "role": "assistant",
    "content": "Sí, hay 4 piezas en la sucursal centro."
  }
]

API

Estas rutas aceptan tu sesión o una API key (API Keys) y trabajan sobre las herramientas de tu organización.

GET/api/v1/tools

Lista tus herramientas

POST/api/v1/tools

Crea una herramienta (Starter+, máx. 20)

PATCH/api/v1/tools/{toolId}

Actualiza una herramienta con edición segura de parámetros

DELETE/api/v1/tools/{toolId}

Elimina una herramienta

POST/api/v1/tools/{toolId}/test

Ejecuta la herramienta desde el servidor (Starter+, 30 s máx.)

GET/api/v1/tools/schemas

Herramientas activas en formato function calling

POST/api/v1/tools/mcp-deploy

Genera el código de un servidor MCP (Starter+)

POST/api/v1/tools/introspect

Lee tablas y columnas de un conector de Supabase (10 req/min por IP)

GET /api/v1/tools/schemas devuelve tus herramientas activas listas para pasarlas como tools a un modelo con function calling:

Respuesta

{
  "data": [
    {
      "type": "function",
      "function": {
        "name": "consultar_inventario",
        "description": "Consulta las piezas disponibles de un producto en una sucursal",
        "parameters": {
          "type": "object",
          "properties": {
            "producto": {
              "type": "string",
              "description": "Nombre o SKU del producto"
            }
          },
          "required": [
            "producto"
          ]
        }
      }
    }
  ]
}

La prueba desde el servidor rechaza endpoints en direcciones internas o privadas y la herramienta debe estar activa.