JSON-skemaer og beskrivelser
På denne side
Værktøjernes sprog: JSON-skema
For at Grok kan kalde dine funktioner, skal det vide hvad de gør, og hvilke parametre de forventer. Det er JSON-skemaernes rolle. Hvert værktøj beskrives af et struktureret objekt, der indeholder tre essentielle dele: et navn, en beskrivelse og et parameterskema.
Anatomien af en værktøjsdefinition
Her er den fulde struktur for et værktøj, som Grok API forventer det:
{
"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"]
}
}
Lad os gennemgå hvert felt:
Feltet type
Er altid "function" for brugerdefinerede funktioner. Andre typer findes til indbyggede værktøjer (web_search, code_interpreter), men til dine egne funktioner er det ufravigeligt "function".
Feltet name
Det tekniske navn på din funktion. Det skal være:
- Unikt blandt alle værktøjer i anmodningen
- Beskrivende:
get_weatherfrem forfn1 - I snake_case som konvention:
search_products,create_ticket - Kort men eksplicit: modellen bruger dette navn til at beslutte, hvilket værktøj den skal kalde
Feltet description
Dette er det vigtigste felt for kvaliteten af kaldet. Modellen baserer sig primært på beskrivelsen for at beslutte, hvornår og hvordan et værktøj skal bruges. En god beskrivelse:
- Forklarer hvad funktionen gør i én sætning
- Specificerer hvornår den skal bruges (hvis det ikke er indlysende)
- Nævner særlige tilfælde (edge cases), hvis nødvendigt
Sammenlign disse to beskrivelser:
❌ "Vejr"
✅ "Hent det aktuelle vejr for en by. Returnerer temperatur, luftfugtighed og vejrforhold."
Den anden giver modellen nok kontekst til præcist at vide, hvornår denne funktion skal kaldes, og hvad den får retur.
Blokken parameters
Parametre følger formatet JSON Schema. Understøttede typer inkluderer:
string— tekststrengernumber/integer— talboolean— sandt/falskarray— listerobject— nestede objekterenum— liste over tilladte værdier
Arrayet required lister obligatoriske parametre. Andre er valgfrie – modellen kan vælge at udelade dem.
Parameterbeskrivelser
Hver parameter bør have sin egen description. Det er dette, der gør det muligt for modellen at forstå hvilken værdi den skal sende:
{
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
}
}
Uden en beskrivelse skal modellen gætte det forventede format – hvilket fører til fejl.
Avancerede parametre
Enums til at begrænse værdier
{
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "critical"],
"description": "Ticket priority level"
}
}
Enums er særligt nyttige: de fortæller modellen de præcise værdier, den kan bruge, hvilket eliminerer formatfejl.
Standardværdier
{
"limit": {
"type": "integer",
"default": 10,
"description": "Maximum number of results to return"
}
}
Modellen forstår, at den kan udelade denne parameter, hvis standardværdien fungerer.
Nestede objekter
{
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"zip": { "type": "string" }
},
"required": ["city"]
}
}
Bedste praksis for beskrivelser
Beskrivelsen er den eneste kanal, hvorigennem modellen forstår dit værktøj – hvert ord tæller. Specificitet først: „Søg efter produkter efter navn eller kategori i kataloget” fortæller modellen præcist, hvornår dette værktøj finder anvendelse, hvorimod „Søg efter produkter” lader den gætte. Formater næst: angivelse af „Dato i ISO 8601-format (ÅÅÅÅ-MM-DD)” i en parameterbeskrivelse eliminerer halvdelen af argumentfejl, fordi modellen replikerer det format, du viser den. Grænser er en del af kontrakten: „Maksimalt 50 resultater pr. kald” forhindrer modellen i at love brugeren en fuldstændighed, som værktøjet ikke kan levere. Og beskrivelse af returværdien – „Returnerer et objekt med pris, tilgængelighed og beskrivelse” – hjælper modellen med at planlægge fremadrettet: den ved, hvad den har til rådighed, før den overhovedet kalder.
Vigtige pointer
- Hvert værktøj defineres af et
name, endescriptionogparameters - Beskrivelsen er faktor nr. 1 for kaldkvalitet – brug tid på den
- Navne skal være unikke og i snake_case
- Brug
enumtil at begrænse mulige værdier - Hver parameter bør have sin egen beskrivelse med det forventede format
- Arrayet
requiredskelner mellem obligatoriske og valgfrie parametre