JSON-scheman och beskrivningar
På denna sida
Verktygens språk: JSON-schema
För att Grok ska kunna anropa dina funktioner måste det veta vad de gör och vilka parametrar de förväntar sig. Det är JSON-schemans roll. Varje verktyg beskrivs av ett strukturerat objekt som innehåller tre väsentliga delar: ett namn, en beskrivning och ett parameterschema.
Anatomin av en verktygsdefinition
Här är den kompletta strukturen för ett verktyg så som Grok API förväntar sig 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"]
}
}
Låt oss bryta ner varje fält:
Fältet type
Alltid "function" för anpassade funktioner. Andra typer finns för inbyggda verktyg (web_search, code_interpreter), men för dina egna funktioner är det alltid "function".
Fältet name
Det tekniska namnet på din funktion. Det måste vara:
- Unikt bland alla verktyg i begäran
- Beskrivande:
get_weathersnarare änfn1 - I snake_case enligt konvention:
search_products,create_ticket - Kort men tydligt: modellen använder detta namn för att avgöra vilket verktyg som ska anropas
Fältet description
Detta är det viktigaste fältet för anropskvaliteten. Modellen förlitar sig främst på beskrivningen för att avgöra när och hur ett verktyg ska användas. En bra beskrivning:
- Förklarar vad funktionen gör i en mening
- Specificerar när den ska användas (om det inte är uppenbart)
- Nämner kantfall om det behövs
Jämför dessa två beskrivningar:
❌ "Väder"
✅ "Hämtar aktuellt väder för en stad. Returnerar temperatur, luftfuktighet och väderförhållanden."
Den andra ger modellen tillräcklig kontext för att veta exakt när denna funktion ska anropas och vad den får tillbaka.
Blocket parameters
Parametrar följer formatet JSON Schema. Typer som stöds inkluderar:
string— teckensträngarnumber/integer— talboolean— sant/falsktarray— listorobject— nästlade objektenum— lista över tillåtna värden
Arrayen required listar obligatoriska parametrar. Andra är valfria – modellen kan välja att utelämna dem.
Parameterbeskrivningar
Varje parameter bör ha sin egen description. Det är detta som låter modellen förstå vilket värde som ska skickas:
{
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
}
}
Utan en beskrivning måste modellen gissa det förväntade formatet – vilket leder till fel.
Avancerade parametrar
Enums för att begränsa värden
{
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "critical"],
"description": "Ticket priority level"
}
}
Enums är särskilt användbara: de talar om för modellen exakt vilka värden den kan använda, vilket eliminerar formatfel.
Standardvärden
{
"limit": {
"type": "integer",
"default": 10,
"description": "Maximum number of results to return"
}
}
Modellen förstår att den kan utelämna denna parameter om standardvärdet fungerar.
Nästlade objekt
{
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"zip": { "type": "string" }
},
"required": ["city"]
}
}
Bästa praxis för beskrivningar
Beskrivningen är den enda kanal genom vilken modellen förstår ditt verktyg – varje ord räknas. Specificitet först: “Sök efter produkter efter namn eller kategori i katalogen” talar om för modellen exakt när detta verktyg gäller, medan “Sök efter produkter” lämnar den att gissa. Format därefter: att specificera “Datum i ISO 8601-format (ÅÅÅÅ-MM-DD)” i en parameterbeskrivning eliminerar hälften av argumentfelen, eftersom modellen replikerar formatet du visar den. Gränser är en del av kontraktet: “Maximalt 50 resultat per anrop” hindrar modellen från att lova användaren fullständighet som verktyget inte kan leverera. Och att beskriva returvärdet – “Returnerar ett objekt med pris, tillgänglighet och beskrivning” – hjälper modellen att planera framåt: den vet vad den kommer att ha till hands innan den ens anropar.
Viktiga punkter
- Varje verktyg definieras av ett
name, endescriptionochparameters - Beskrivningen är faktor nummer ett för anropskvaliteten – lägg tid på den
- Namn måste vara unika och i snake_case
- Använd
enumför att begränsa möjliga värden - Varje parameter bör ha sin egen beskrivning med det förväntade formatet
- Arrayen
requiredskiljer obligatoriska parametrar från valfria