Schémas JSON et descriptions

Le langage des outils : JSON Schema

Pour que Grok puisse appeler vos fonctions, il doit savoir ce qu’elles font et quels paramètres elles attendent. C’est le rôle des schémas JSON. Chaque outil est décrit par un objet structuré qui contient trois informations essentielles : un nom, une description et un schéma de paramètres.

Anatomie d’une définition d’outil

Voici la structure complète d’un outil tel que l’API Grok l’attend :

{
  "type": "function",
  "name": "get_weather",
  "description": "Obtenir la météo actuelle d'une ville donnée",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "Le nom de la ville (ex: Paris, Lyon)"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "default": "celsius"
      }
    },
    "required": ["city"]
  }
}

Analysons chaque champ :

Le champ `type`

Toujours "function" pour les fonctions personnalisées. D’autres types existent pour les outils intégrés (web_search, code_interpreter), mais pour vos propres fonctions, c’est invariablement "function".

Le champ `name`

Le nom technique de votre fonction. Il doit être :

Unique parmi tous les outils de la requête
Descriptif : get_weather plutôt que fn1
En snake_case par convention : search_products, create_ticket
Court mais explicite : le modèle utilise ce nom pour décider quel outil appeler

Le champ `description`

C’est le champ le plus important pour la qualité des appels. Le modèle se base principalement sur la description pour décider quand et comment utiliser un outil. Une bonne description :

Explique ce que fait la fonction en une phrase
Précise quand l’utiliser (si ce n’est pas évident)
Mentionne les cas limites si nécessaire

Comparez ces deux descriptions :

❌ "Météo"
✅ "Obtenir la météo actuelle d'une ville. Retourne température, humidité et conditions."

La seconde donne au modèle suffisamment de contexte pour savoir exactement quand appeler cette fonction et ce qu’il obtiendra en retour.

Le bloc `parameters`

Les paramètres suivent le format JSON Schema. Les types supportés incluent :

string — chaînes de caractères
number / integer — nombres
boolean — vrai/faux
array — listes
object — objets imbriqués
enum — liste de valeurs autorisées

Le tableau required liste les paramètres obligatoires. Les autres sont optionnels — le modèle peut choisir de les omettre.

Descriptions des paramètres

Chaque paramètre devrait avoir sa propre description. C’est ce qui permet au modèle de comprendre quoi passer comme valeur :

{
  "date": {
    "type": "string",
    "description": "Date au format YYYY-MM-DD. Si omise, utilise la date du jour."
  }
}

Sans description, le modèle doit deviner le format attendu — ce qui mène à des erreurs.

Paramètres avancés

Enums pour contraindre les valeurs

{
  "priority": {
    "type": "string",
    "enum": ["low", "medium", "high", "critical"],
    "description": "Niveau de priorité du ticket"
  }
}

Les enums sont particulièrement utiles : elles indiquent au modèle les valeurs exactes qu’il peut utiliser, éliminant les erreurs de format.

Valeurs par défaut

{
  "limit": {
    "type": "integer",
    "default": 10,
    "description": "Nombre maximum de résultats à retourner"
  }
}

Le modèle comprend qu’il peut omettre ce paramètre si la valeur par défaut convient.

Objets imbriqués

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

Bonnes pratiques pour les descriptions

Voici les règles que vous devriez suivre systématiquement :

Soyez spécifique : « Rechercher des produits par nom ou catégorie dans le catalogue » plutôt que « Chercher des produits »
Indiquez le format : « Date au format ISO 8601 (YYYY-MM-DD) »
Mentionnez les limites : « Maximum 50 résultats par appel »
Précisez le retour : « Retourne un objet avec prix, disponibilité et description »

Points clés à retenir

Chaque outil est défini par un name, une description et des parameters
La description est le facteur n°1 de qualité des appels — investissez du temps dessus
Les noms doivent être uniques et en snake_case
Utilisez les enum pour contraindre les valeurs possibles
Chaque paramètre devrait avoir sa propre description avec le format attendu
Le tableau required distingue les paramètres obligatoires des optionnels