JSON-Schemas und Beschreibungen

Die Sprache der Werkzeuge: JSON-Schema

Damit Grok Ihre Funktionen aufrufen kann, muss es wissen, was diese tun und welche Parameter sie erwarten. Dies ist die Aufgabe von JSON-Schemas. Jedes Werkzeug wird durch ein strukturiertes Objekt beschrieben, das drei wesentliche Informationen enthält: einen Namen, eine Beschreibung und ein Parameterschema.

Anatomie einer Werkzeugdefinition

Hier ist die vollständige Struktur eines Werkzeugs, wie die Grok-API sie erwartet:

{
  "type": "function",
  "name": "get_weather",
  "description": "Holen Sie sich das aktuelle Wetter für eine gegebene Stadt",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "Der Name der Stadt (z. B. Paris, Lyon)"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "default": "celsius"
      }
    },
    "required": ["city"]
  }
}

Lassen Sie uns jedes Feld im Detail betrachten:

Das `type`-Feld

Für benutzerdefinierte Funktionen ist dies immer "function". Für andere Typen gibt es zwar eingebaute Werkzeuge (web_search, code_interpreter), doch für Ihre eigenen Funktionen ist es unweigerlich "function".

Das `name`-Feld

Der technische Name Ihrer Funktion. Er muss:

Einzigartig unter allen Werkzeugen in der Anforderung sein
Beschreibend sein: get_weather statt fn1
In snake_case konventionell sein: search_products, create_ticket
Kurz, aber explizit sein: Das Modell nutzt diesen Namen, um zu entscheiden, welches Werkzeug aufgerufen werden soll

Das `description`-Feld

Dies ist das wichtigste Feld für die Aufrufqualität. Das Modell stützt sich primär auf die Beschreibung, um zu entscheiden, wann und wie ein Werkzeug verwendet werden soll. Eine gute Beschreibung:

Erklärt was die Funktion tut in einem Satz
Spezifiziert wann sie verwendet werden soll (sofern dies nicht offensichtlich ist)
Erwähnt Randfälle, falls notwendig

Vergleichen Sie diese beiden Beschreibungen:

❌ "Wetter"
✅ "Holen Sie sich das aktuelle Wetter für eine Stadt. Gibt Temperatur, Luftfeuchtigkeit und Bedingungen zurück."

Die zweite gibt dem Modell genügend Kontext, um genau zu wissen, wann diese Funktion aufgerufen werden soll und was sie im Gegenzug liefert.

Der `parameters`-Block

Parameter folgen dem JSON-Schema-Format. Unterstützte Typen umfassen:

string — Zeichenketten
number / integer — Zahlen
boolean — wahr/falsch
array — Listen
object — verschachtelte Objekte
enum — Liste erlaubter Werte

Das required-Array listet obligatorische Parameter auf. Die anderen sind optional — das Modell kann sich entscheiden, sie wegzulassen.

Parameterbeschreibungen

Jeder Parameter sollte eine eigene description besitzen. Dies ist es, was dem Modell ermöglicht zu verstehen, welchen Wert zu übergeben:

{
  "date": {
    "type": "string",
    "description": "Datum im Format YYYY-MM-DD. Wenn nicht angegeben, wird das heutige Datum verwendet."
  }
}

Ohne eine Beschreibung muss das Modell das erwartete Format erraten — was zu Fehlern führt.

Erweiterte Parameter

Enums zur Einschränkung von Werten

{
  "priority": {
    "type": "string",
    "enum": ["low", "medium", "high", "critical"],
    "description": "Prioritätsstufe des Tickets"
  }
}

Enums sind besonders nützlich: Sie sagen dem Modell die genauen Werte, die es verwenden kann, und eliminieren Formatfehler.

Standardwerte

{
  "limit": {
    "type": "integer",
    "default": 10,
    "description": "Maximale Anzahl der zurückzugebenden Ergebnisse"
  }
}

Das Modell versteht, dass es diesen Parameter weglassen kann, wenn der Standardwert funktioniert.

Verschachtelte Objekte

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

Best Practices für Beschreibungen

Die Beschreibung ist der einzige Kanal, durch den das Modell Ihr Werkzeug versteht — jedes Wort zählt dort. Spezifität geht vor: “Suchen Sie nach Produkten nach Name oder Kategorie im Katalog” sagt dem Modell genau, wann dieses Werkzeug gilt, wohingegen “Suchen Sie nach Produkten” es raten lässt. Formate folgen: Die Angabe “Datum im ISO-8601-Format (YYYY-MM-DD)” in einer Parameterbeschreibung halbiert die Anzahl der Argumentfehler, da das Modell das Format wiederholt, das Sie ihm zeigen. Grenzen sind Teil des Vertrags: “Maximal 50 Ergebnisse pro Aufruf” verhindert, dass das Modell dem Nutzer Vollständigkeit verspricht, die das Werkzeug nicht liefern kann. Und die Beschreibung der Rückgabe — “Gibt ein Objekt mit Preis, Verfügbarkeit und Beschreibung zurück” — hilft dem Modell, vorausschauend zu planen: Es weiß, worüber es verfügt, noch bevor es aufruft.

Kernaussagen

Jedes Werkzeug wird durch einen name, eine description und parameters definiert
Die Beschreibung ist der wichtigste Faktor für die Aufrufqualität — investieren Sie Zeit darin
Namen müssen eindeutig und in snake_case sein
Verwenden Sie enum, um mögliche Werte einzuschränken
Jeder Parameter sollte eine eigene Beschreibung mit dem erwarteten Format haben
Das required-Array unterscheidet obligatorische von optionalen Parametern