JSON Schema pour les outils

Votre fonction outil existe ; Claude, lui, n’en sait rien — il ne voit pas votre code. Après avoir créé la fonction, l’étape suivante est d’écrire un schéma JSON pour la décrire : ce document indique à Claude les arguments attendus et comment les utiliser correctement. C’est la seule chose que le modèle connaîtra de votre outil — autant la soigner.

Comprendre le JSON Schema

Le JSON Schema n’a pas été inventé pour l’IA : il existe depuis des années comme standard de validation de données, et vos API REST le parlent probablement déjà. Pour un outil Claude, il comporte deux parties principales :

• Section haute : nom et description de l’outil (aide Claude à savoir quand l’utiliser)
• Section basse : le schéma proprement dit, décrivant les arguments de la fonction en détail

Les deux sections répondent à deux questions différentes du modèle : dois-je utiliser cet outil pour cette demande ? (la description tranche), et avec quels arguments ? (le schéma détaille).

Créer un schéma : étape par étape

Écrire un schéma de zéro est laborieux ; voici la méthode pragmatique en quatre temps.

Étape 1 : Écrire un dictionnaire avec des données d’exemple

Prenez votre fonction et créez un dictionnaire de tous les arguments avec des valeurs d’exemple :

def process_data(ids, profile, primary_id, value):
    pass

Pour cette signature, le dictionnaire d’exemple donnerait des valeurs plausibles à ids (une liste), profile (un objet), primary_id et value — l’idée est de matérialiser les types réels de chaque argument.

Étape 2 : Convertir en JSON

Convertissez votre dictionnaire Python en format JSON — la principale différence : True en Python devient true en JSON, et les guillemets deviennent doubles.

Étape 3 : Utiliser un convertisseur en ligne

Cherchez « JSON to JSON Schema converter » et utilisez un des nombreux outils gratuits en ligne : collez votre JSON d’exemple, et le générateur infère automatiquement le schéma — types, structure, imbrications. Supprimez les déclarations $schema du résultat, inutiles ici. En trente secondes, la partie mécanique du travail est faite.

Étape 4 : Ajouter les descriptions

Reste la partie que personne ne peut automatiser, et c’est l’étape la plus importante : ajoutez des descriptions détaillées à chaque propriété. Le convertisseur connaît les types ; vous seul connaissez l’intention — ce que chaque argument signifie, son format attendu, ses valeurs raisonnables. Ces descriptions sont ce qui sépare un outil que Claude utilise correctement d’un outil qu’il remplit au hasard.

Bonnes pratiques pour les descriptions

• Expliquer ce que l’outil fait, quand l’utiliser, et ce qu’il renvoie
• Viser 3 à 4 phrases dans la description de l’outil
• Fournir des descriptions détaillées pour chaque propriété
• Si vous bloquez, collez votre fonction dans Claude et demandez-lui d’écrire les descriptions

Le triptyque quoi/quand/retour de la première règle est le cœur du contrat : « quoi » cadre la capacité, « quand » guide la décision d’appel, « retour » permet à Claude d’anticiper ce qu’il recevra.

Assembler le tout

Sur Bedrock, le schéma s’emballe dans la structure toolSpec attendue par l’API Converse :

{
  "toolSpec": {
    "name": "get_current_datetime",
    "description": "Recupere la date et l'heure actuelles. Utilisez cet outil quand vous avez besoin de connaitre la date ou l'heure courante. Renvoie la date formatée selon le format specifie.",
    "inputSchema": {
      "json": {
        "type": "object",
        "properties": {
          "date_format": {
            "type": "string",
            "description": "Le format strftime pour la date. Par défaut : %Y-%m-%d %H:%M:%S"
          }
        }
      }
    }
  }
}

Relisez la description de date_format : elle nomme la convention (strftime) et donne la valeur par défaut — deux ancres qui empêchent Claude d’inventer un format fantaisiste. Le schéma agit comme un contrat entre votre code et Claude : quand le modèle décide d’utiliser votre outil, il sait exactement quelles informations fournir et dans quel format. Un contrat flou produit des appels flous — un contrat précis, des appels justes.

Points clés à retenir

• Claude ne voit pas votre code : le schéma JSON est tout ce qu’il connaît de l’outil
• Deux sections, deux questions : description (quand appeler ?) et inputSchema (avec quoi ?)
• Méthode rapide : dictionnaire d’exemple → JSON → convertisseur en ligne → descriptions à la main
• Les descriptions portent l’intention — quoi/quand/retour en 3-4 phrases, chaque propriété détaillée
• Sur Bedrock, le tout s’emballe dans toolSpec/inputSchema au format de l’API Converse