Schemi JSON e descrizioni
In questa pagina
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_weatherinvece difn1 - 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 caratterinumber/integer— numeriboolean— vero/falsoarray— listeobject— oggetti nidificatienum— 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, unadescriptione deiparameters - La descrizione è il fattore numero uno per la qualità delle chiamate: dedicaci tempo
- I nomi devono essere unici e in snake_case
- Usa
enumper vincolare i valori possibili - Ogni parametro dovrebbe avere la propria descrizione con il formato atteso
- L’array
requireddistingue i parametri obbligatori da quelli opzionali