Linter de Definiciones de Tool/Function

¿Qué es un Linter de Definiciones de Herramientas de IA?

Un linter de definiciones de herramientas de IA valida las estructuras JSON que definen funciones y herramientas para APIs de modelos de lenguaje. Cuando usas function calling (también llamado tool use) con proveedores como OpenAI, Anthropic Claude, Google Gemini o Cohere, debes proporcionar definiciones JSON correctamente estructuradas que describan tus funciones — sus nombres, descripciones y schemas de parámetros.

Incluso pequeños errores en estas definiciones — un nombre de campo mal escrito, un tipo inválido o una propiedad requerida faltante — pueden causar que las llamadas a la API fallen silenciosamente o produzcan comportamiento inesperado. Un linter de definiciones de herramientas detecta estos errores antes del despliegue, ahorrando tiempo de depuración y previniendo problemas en producción.

Nuestro linter gratuito valida tus definiciones contra cuatro principales proveedores simultáneamente (OpenAI, Anthropic, Google y Cohere), te muestra exactamente dónde están los errores y proporciona sugerencias accionables para corregir cada problema. Mistral AI, xAI (Grok) y DeepSeek usan formato compatible con OpenAI, por lo que pasar la validación de OpenAI los cubre también. Se ejecuta completamente en tu navegador sin enviar datos a ningún servidor.

Cómo Usar Este Linter

Usar el Linter de Definiciones de Herramientas es sencillo — solo pega y listo:

1. Pega tu definición JSON — Copia tu definición de tool/function de tu código base y pégala en el editor. El linter acepta objetos de herramienta individuales, arrays de herramientas u objetos envolventes con un array `tools`.
2. Observa los resultados en tiempo real — El linter valida automáticamente mientras escribes (con un breve debounce). No necesitas hacer clic en un botón. Verás el formato detectado, el estado de compatibilidad con proveedores y cualquier problema inmediatamente.
3. Revisa la compatibilidad — Las cuatro tarjetas de proveedores muestran si tu definición es compatible con OpenAI, Anthropic, Google y Cohere. Verde significa compatible, rojo significa que hay problemas que necesitan corrección.
4. Corrige los problemas — Cada problema muestra la ruta del campo afectado, un mensaje de error claro y una sugerencia de cómo corregirlo. Los problemas se categorizan por gravedad: errores (deben corregirse), advertencias (deberían corregirse) e información (bueno tenerlo).
5. Copia el JSON corregido — Una vez satisfecho, usa el botón "Copiar JSON Corregido" para obtener una versión limpia y formateada con auto-correcciones básicas aplicadas.

Entendiendo los Formatos de Function Calling de IA

Cada proveedor de IA tiene su propio formato para definir funciones invocables, aunque comparten el mismo concepto subyacente: un nombre, una descripción y un JSON Schema para los parámetros.

Function Calling de OpenAI

OpenAI envuelve las definiciones de herramientas en una estructura `{ type: "function", function: { ... } }`. El objeto interno contiene `name`, `description` y `parameters` (un objeto JSON Schema). OpenAI también soporta un modo `strict` que habilita Structured Outputs — cuando se establece en true, el modelo siempre seguirá el schema exacto, pero requiere `additionalProperties: false`.

Tool Use de Anthropic

Anthropic usa una estructura plana sin wrapper. Cada herramienta se define con `name`, `description` e `input_schema` — nota el nombre de campo diferente comparado con `parameters` de OpenAI. Anthropic recomienda mantener las descripciones por debajo de 1024 caracteres para un rendimiento óptimo. El campo `cache_control` puede usarse opcionalmente para la caché de prompts.

Function Declarations de Google Gemini

Google Gemini usa una estructura plana similar a Anthropic pero con `parameters` como OpenAI. La diferencia clave es que el soporte de JSON Schema de Google es más limitado — no admite `$ref` para referencias de schema y tiene soporte limitado para palabras clave de composición como `oneOf`, `anyOf` y `allOf`.

Tool Use de Cohere

Cohere usa un formato único con `parameter_definitions` en lugar de JSON Schema. Cada parámetro se define como un objeto con `type`, `description` y opcionalmente campos `required`. Esto es estructuralmente diferente del enfoque de JSON Schema usado por otros proveedores. Cohere es particularmente fuerte para tool use basado en RAG y flujos de trabajo empresariales con cumplimiento SOC 2 y HIPAA.

Proveedores Compatibles con OpenAI

Varios proveedores — incluyendo Mistral AI, xAI (Grok) y DeepSeek — usan formatos de function calling compatibles con OpenAI. Si tu definición de herramienta pasa la validación de OpenAI, funcionará con estos proveedores directamente, facilitando el cambio entre ellos sin modificar tus definiciones de herramientas.

Errores Comunes en Definiciones de Herramientas

Basándonos en patrones comunes que observamos, estos son los errores más frecuentes en definiciones de herramientas de IA:

• Nombre incorrecto del campo de schema — Usar "parameters" cuando el proveedor espera "input_schema" (Anthropic) o viceversa. Este es el problema de compatibilidad entre proveedores #1.
• Estructura wrapper faltante — Olvidar el wrapper `{ type: "function", function: { ... } }` para OpenAI, o incluirlo cuando se apunta a Anthropic/Google.
• Nombres de función inválidos — Usar espacios, caracteres especiales o nombres de más de 64 caracteres. Todos los proveedores requieren solo caracteres alfanuméricos, guiones bajos y guiones.
• Campos requeridos que no están en properties — Listar un campo en el array "required" que no existe en el objeto "properties".
• Falta "type" en objetos de schema — Cada objeto JSON Schema necesita un campo "type". El schema raíz debería ser "type": "object".
• Descripciones de propiedades faltantes — Aunque técnicamente no siempre son requeridas, las descripciones de propiedades mejoran significativamente la comprensión del modelo y la precisión de las llamadas de herramientas.
• Violaciones del modo strict — Al usar el modo strict de OpenAI, olvidar establecer "additionalProperties": false o no listar todas las propiedades como requeridas.

Preguntas Frecuentes

Herramientas Relacionadas

Explora más herramientas para ayudarte a construir con APIs de IA:

• Generador de JSON Schema para IA — Genera JSON schemas a partir de datos de ejemplo optimizados para function calling
• OpenAPI a Function Calling de IA — Convierte especificaciones Swagger/OpenAPI en definiciones de herramientas
• Constructor de Mensajes de Conversación — Construye y prueba arrays de mensajes de chat completion visualmente