Ir al contenido principal
Español— Elegir un idioma
Menú

Esquemas JSON y descripciones

Lección 2 de 14 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. El lenguaje de las herramientas: esquema JSON
  2. Anatomía de una definición de herramienta
  3. Descripciones de parámetros
  4. Parámetros avanzados
  5. Mejores prácticas para las descripciones
  6. Puntos clave

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_weather en lugar de fn1.
  • 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, una description y unos parameters.
  • 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 enum para restringir los valores posibles.
  • Cada parámetro debe tener su propia descripción con el formato esperado.
  • El array required distingue los parámetros obligatorios de los opcionales.