JSON-schema's en beschrijvingen
Op deze pagina
De taal van tools: JSON-schema
Opdat Grok uw functies kan aanroepen, moet het weten wat ze doen en welke parameters ze verwachten. Dat is de rol van JSON-schema’s. Elke tool wordt beschreven door een gestructureerd object dat drie essentiële onderdelen bevat: een naam, een beschrijving en een parameterschema.
Anatomie van een tooldefinitie
Hier ziet u de volledige structuur van een tool zoals de Grok API deze verwacht:
{
"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"]
}
}
Laten we elk veld ontleden:
Het veld type
Voor aangepaste functies is dit altijd "function". Er bestaan andere typen voor ingebouwde tools (web_search, code_interpreter), maar voor uw eigen functies is het steevast "function".
Het veld name
De technische naam van uw functie. Deze moet:
- Uniek zijn tussen alle tools in het verzoek
- Beschrijvend zijn:
get_weatherin plaats vanfn1 - Conform de conventie in snake_case staan:
search_products,create_ticket - Kort maar expliciet zijn: het model gebruikt deze naam om te beslissen welke tool het moet aanroepen
Het veld description
Dit is het belangrijkste veld voor de kwaliteit van de aanroep. Het model baseert zich primair op de beschrijving om te beslissen wanneer en hoe het een tool moet gebruiken. Een goede beschrijving:
- Legt in één zin uit wat de functie doet
- Specificeert wanneer u deze moet gebruiken (als dit niet voor de hand ligt)
- Noemt indien nodig randgevallen
Vergelijk deze twee beschrijvingen:
❌ "Weather"
✅ "Get the current weather for a city. Returns temperature, humidity, and conditions."
De tweede geeft het model voldoende context om precies te weten wanneer het deze functie moet aanroepen en wat het terugkrijgt.
Het blok parameters
Parameters volgen het formaat JSON Schema. Ondersteunde typen zijn onder meer:
string— tekenreeksennumber/integer— getallenboolean— waar/onwaararray— lijstenobject— geneste objectenenum— lijst met toegestane waarden
De array required somt de verplichte parameters op. Andere zijn optioneel; het model kan kiezen om deze weg te laten.
Parameterbeschrijvingen
Elke parameter moet zijn eigen description hebben. Hierdoor begrijpt het model welke waarde het moet doorgeven:
{
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
}
}
Zonder beschrijving moet het model het verwachte formaat raden, wat leidt tot fouten.
Geavanceerde parameters
Enums om waarden te beperken
{
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "critical"],
"description": "Ticket priority level"
}
}
Enums zijn bijzonder nuttig: ze vertellen het model precies welke waarden het mag gebruiken, waardoor formaatfouten worden geëlimineerd.
Standaardwaarden
{
"limit": {
"type": "integer",
"default": 10,
"description": "Maximum number of results to return"
}
}
Het model begrijpt dat het deze parameter kan weglaten als de standaardwaarde volstaat.
Geneste objecten
{
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"zip": { "type": "string" }
},
"required": ["city"]
}
}
Best practices voor beschrijvingen
De beschrijving is het enige kanaal waardoor het model uw tool begrijpt; elk woord telt hier. Specificiteit komt eerst: “Search for products by name or category in the catalog” vertelt het model precies wanneer deze tool van toepassing is, terwijl “Search for products” het laat raden. Formaten komen daarna: het specificeren van “Date in ISO 8601 format (YYYY-MM-DD)” in een parameterbeschrijving elimineert de helft van de argumentatiefouten, omdat het model het formaat overneemt dat u toont. Limieten maken deel uit van het contract: “Maximum 50 results per call” voorkomt dat het model de gebruiker volledigheid belooft die de tool niet kan leveren. En het beschrijven van de return — “Returns an object with price, availability, and description” — helpt het model vooruit te plannen: het weet wat het tot zijn beschikking heeft voordat het zelfs maar aanroept.
Belangrijkste punten
- Elke tool wordt gedefinieerd door een
name, eendescriptionenparameters - De beschrijving is factor nummer één voor de kwaliteit van de aanroep — investeer hier tijd in
- Namen moeten uniek zijn en in snake_case staan
- Gebruik
enumom mogelijke waarden te beperken - Elke parameter moet zijn eigen beschrijving hebben met het verwachte formaat
- De array
requiredmaakt onderscheid tussen verplichte en optionele parameters