Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Schemi JSON e descrizioni

Lezione 2 di 14 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Il linguaggio degli strumenti: lo schema JSON
  2. Anatomia di una definizione di strumento
  3. Descrizioni dei parametri
  4. Parametri avanzati
  5. Migliori pratiche per le descrizioni
  6. Punti chiave

Il linguaggio degli strumenti: lo schema JSON

Affinché Grok possa chiamare le tue funzioni, deve sapere cosa fanno e quali parametri si aspettano. È proprio questo il ruolo degli schemi JSON. Ogni strumento è descritto da un oggetto strutturato contenente tre elementi essenziali: un nome, una descrizione e uno schema dei parametri.

Anatomia di una definizione di strumento

Ecco la struttura completa di uno strumento così come prevista dall’API di 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"]
  }
}

Analizziamo ogni campo nel dettaglio:

Il campo type

Deve essere sempre "function" per le funzioni personalizzate. Esistono altri tipi per gli strumenti integrati (web_search, code_interpreter), ma per le tue funzioni è invariabilmente "function".

Il campo name

Il nome tecnico della tua funzione. Deve essere:

  • Unico tra tutti gli strumenti nella richiesta
  • Descrittivo: get_weather invece di fn1
  • In snake_case per convenzione: search_products, create_ticket
  • Breve ma esplicito: il modello usa questo nome per decidere quale strumento chiamare

Il campo description

Questo è il campo più importante per la qualità delle chiamate. Il modello si basa principalmente sulla descrizione per decidere quando e come usare uno strumento. Una buona descrizione:

  • Spiega cosa fa la funzione in una frase
  • Specifica quando usarla (se non è ovvio)
  • Menziona i casi limite se necessario

Confronta queste due descrizioni:

❌ "Meteo"
✅ "Ottieni il meteo attuale per una città. Restituisce temperatura, umidità e condizioni."

La seconda fornisce al modello contesto sufficiente per sapere esattamente quando chiamare questa funzione e cosa riceverà in cambio.

Il blocco parameters

I parametri seguono il formato JSON Schema. I tipi supportati includono:

  • string — stringhe di caratteri
  • number / integer — numeri
  • boolean — vero/falso
  • array — liste
  • object — oggetti nidificati
  • enum — lista di valori consentiti

L’array required elenca i parametri obbligatori. Gli altri sono opzionali: il modello può scegliere di ometterli.

Descrizioni dei parametri

Ogni parametro dovrebbe avere la propria description. È questo che permette al modello di capire quale valore passare:

{
  "date": {
    "type": "string",
    "description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
  }
}

Senza una descrizione, il modello deve indovinare il formato atteso, il che porta a errori.

Parametri avanzati

Enum per vincolare i valori

{
  "priority": {
    "type": "string",
    "enum": ["low", "medium", "high", "critical"],
    "description": "Ticket priority level"
  }
}

Gli enum sono particolarmente utili: indicano al modello i valori esatti che può utilizzare, eliminando gli errori di formato.

Valori predefiniti

{
  "limit": {
    "type": "integer",
    "default": 10,
    "description": "Maximum number of results to return"
  }
}

Il modello capisce che può omettere questo parametro se il valore predefinito è adeguato.

Oggetti nidificati

{
  "address": {
    "type": "object",
    "properties": {
      "street": { "type": "string" },
      "city": { "type": "string" },
      "zip": { "type": "string" }
    },
    "required": ["city"]
  }
}

Migliori pratiche per le descrizioni

La descrizione è l’unico canale attraverso cui il modello comprende il tuo strumento: ogni parola conta. Priorità alla specificità: «Cerca prodotti per nome o categoria nel catalogo» dice al modello esattamente quando applicare questo strumento, mentre «Cerca prodotti» lo lascia nell’incertezza. Poi i formati: specificare «Data in formato ISO 8601 (AAAA-MM-GG)» nella descrizione di un parametro elimina metà degli errori di argomento, perché il modello replica il formato che gli mostri. I limiti fanno parte del contratto: «Massimo 50 risultati per chiamata» impedisce al modello di promettere all’utente una completezza che lo strumento non può fornire. Infine, descrivere il ritorno — «Restituisce un oggetto con prezzo, disponibilità e descrizione» — aiuta il modello a pianificare in anticipo: sa già cosa avrà a disposizione prima ancora di effettuare la chiamata.

Punti chiave

  • Ogni strumento è definito da un name, una description e dei parameters
  • La descrizione è il fattore numero uno per la qualità delle chiamate: dedicaci tempo
  • I nomi devono essere unici e in snake_case
  • Usa enum per vincolare i valori possibili
  • Ogni parametro dovrebbe avere la propria descrizione con il formato atteso
  • L’array required distingue i parametri obbligatori da quelli opzionali