Esquemas JSON y descripciones
En esta página
El lenguaje de las herramientas: esquema JSON
Para que Grok pueda llamar a tus funciones, necesita saber qué hacen y qué parámetros esperan. Esa es la función de los esquemas JSON. Cada herramienta se describe mediante un objeto estructurado que contiene tres elementos esenciales: un nombre, una descripción y un esquema de parámetros.
Anatomía de una definición de herramienta
Esta es la estructura completa de una herramienta tal como la espera la API de Grok:
{
"type": "function",
"name": "get_weather",
"description": "Get the current weather for a given city",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "The city name (e.g., Paris, Lyon)"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"default": "celsius"
}
},
"required": ["city"]
}
}
Analicemos cada campo:
El campo type
Siempre debe ser "function" para funciones personalizadas. Existen otros tipos para herramientas integradas (web_search, code_interpreter), pero para tus propias funciones, invariablemente será "function".
El campo name
El nombre técnico de tu función. Debe cumplir lo siguiente:
- Ser único entre todas las herramientas de la solicitud.
- Ser descriptivo:
get_weatheren lugar defn1. - Usar snake_case por convención:
search_products,create_ticket. - Ser breve pero explícito: el modelo utiliza este nombre para decidir qué herramienta llamar.
El campo description
Este es el campo más importante para la calidad de la llamada. El modelo se basa principalmente en la descripción para decidir cuándo y cómo utilizar una herramienta. Una buena descripción:
- Explica qué hace la función en una frase.
- Especifica cuándo debe usarse (si no es obvio).
- Menciona casos límite si es necesario.
Compara estas dos descripciones:
❌ "Weather"
✅ "Get the current weather for a city. Returns temperature, humidity, and conditions."
La segunda ofrece al modelo suficiente contexto para saber exactamente cuándo llamar a esta función y qué recibirá a cambio.
El bloque parameters
Los parámetros siguen el formato JSON Schema. Los tipos admitidos incluyen:
string— cadenas de caracteres.number/integer— números.boolean— verdadero/falso.array— listas.object— objetos anidados.enum— lista de valores permitidos.
El array required enumera los parámetros obligatorios. Los demás son opcionales; el modelo puede decidir omitirlos.
Descripciones de parámetros
Cada parámetro debe tener su propia description. Esto es lo que permite al modelo entender qué valor debe pasar:
{
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
}
}
Sin una descripción, el modelo tiene que adivinar el formato esperado, lo que conduce a errores.
Parámetros avanzados
Enums para restringir valores
{
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "critical"],
"description": "Ticket priority level"
}
}
Los enums son especialmente útiles: indican al modelo los valores exactos que puede utilizar, eliminando errores de formato.
Valores por defecto
{
"limit": {
"type": "integer",
"default": 10,
"description": "Maximum number of results to return"
}
}
El modelo entiende que puede omitir este parámetro si el valor por defecto es válido.
Objetos anidados
{
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"zip": { "type": "string" }
},
"required": ["city"]
}
}
Mejores prácticas para las descripciones
La descripción es el único canal mediante el cual el modelo entiende tu herramienta; cada palabra cuenta. Prioriza la especificidad: «Search for products by name or category in the catalog» indica al modelo exactamente cuándo aplica esta herramienta, mientras que «Search for products» le deja adivinar. A continuación, define los formatos: especificar «Date in ISO 8601 format (YYYY-MM-DD)» en la descripción de un parámetro elimina la mitad de los errores de argumentos, porque el modelo replica el formato que le muestras. Los límites forman parte del contrato: «Maximum 50 results per call» evita que el modelo prometa al usuario una exhaustividad que la herramienta no puede ofrecer. Y describir la respuesta —«Returns an object with price, availability, and description»— ayuda al modelo a planificar con antelación: sabe de qué dispondrá antes incluso de realizar la llamada.
Puntos clave
- Cada herramienta se define mediante un
name, unadescriptiony unosparameters. - La descripción es el factor nº 1 en la calidad de la llamada: invierte tiempo en ella.
- Los nombres deben ser únicos y estar en snake_case.
- Utiliza
enumpara restringir los valores posibles. - Cada parámetro debe tener su propia descripción con el formato esperado.
- El array
requireddistingue los parámetros obligatorios de los opcionales.