JSON Schema pour les outils

La fonction existe ; Claude, lui, n’en sait rien. L’étape suivante est d’écrire le schéma JSON qui la décrit : les arguments attendus et la façon de s’en servir. C’est la seule chose que le modèle connaîtra de votre outil, autant la soigner.

Deux parties, deux questions

Une définition d’outil a deux parties :

• le nom et la description de l’outil, qui répondent à la question « dois-je utiliser cet outil pour cette demande ? » ;
• le schéma des arguments, qui répond à « avec quels arguments ? ».

Écrire un schéma en quatre étapes

Écrire un schéma de zéro est laborieux. Le cours officiel propose une méthode pragmatique.

1. Un dictionnaire d’exemple. Pour une fonction process_data(ids, profile, primary_id, value), écrivez des valeurs plausibles pour chaque argument :

import json

exemple = {
    "ids": [12, 15, 19],
    "profile": {"name": "Ana", "admin": True},
    "primary_id": 12,
    "value": 4.5,
}
print(json.dumps(exemple))

2. Le JSON. json.dumps convertit le dictionnaire : True devient true, les guillemets deviennent doubles.

3. Un convertisseur. Un outil « JSON to JSON Schema » déduit le schéma de cet exemple : types, structure, imbrications. Retirez la déclaration $schema du résultat, inutile ici. Vous pouvez aussi demander le schéma à Claude.

4. Les descriptions. Reste l’étape que rien n’automatise, et la plus importante : décrire chaque propriété. Le convertisseur connaît les types ; vous seul connaissez l’intention, le sens de chaque argument, son format, ses valeurs raisonnables.

Bien décrire un outil

D’après le cours officiel :

• expliquez ce que fait l’outil, quand l’utiliser et ce qu’il renvoie ;
• visez trois ou quatre phrases pour la description de l’outil ;
• détaillez chaque propriété ;
• si vous bloquez, collez la fonction dans Claude et demandez-lui d’écrire les descriptions.

Ce triptyque quoi, quand, retour est le cœur du contrat : c’est sur la description que Claude décide d’appeler ou non l’outil. Une description vague produit des appels erratiques, quelle que soit la qualité du code derrière.

Le format de l’API Converse

Sur Bedrock, la définition s’emballe dans un bloc toolSpec, avec le schéma des arguments sous inputSchema.json :

get_current_datetime_schema = {
    "toolSpec": {
        "name": "get_current_datetime",
        "description": (
            "Renvoie la date et l'heure actuelles, au format demandé. "
            "Utilise cet outil dès que la réponse dépend du moment présent, "
            "par exemple pour connaître l'heure ou calculer une échéance à partir d'aujourd'hui. "
            "L'outil renvoie une chaîne formatée selon date_format."
        ),
        "inputSchema": {
            "json": {
                "type": "object",
                "properties": {
                    "date_format": {
                        "type": "string",
                        "description": (
                            "Format de la date avec les codes strftime de Python, "
                            "par exemple %Y-%m-%d %H:%M:%S (valeur par défaut) ou %d/%m/%Y."
                        ),
                    }
                },
                "additionalProperties": False,
            }
        },
    }
}

La description de date_format nomme la convention (strftime) et donne la valeur par défaut : deux repères qui empêchent Claude d’inventer un format fantaisiste. Le nom de l’outil doit respecter le motif [a-zA-Z0-9_-]+, 64 caractères au plus.

Des arguments garantis

Par défaut, Claude suit le schéma de très près, sans garantie formelle. Pour l’obtenir, Bedrock accepte "strict": True dans le toolSpec : les arguments produits respectent alors le schéma, comme les sorties structurées de la leçon 10, avec les mêmes règles, dont "additionalProperties": False sur chaque objet.

À vous de jouer

Votre schéma. Écrivez le toolSpec d’un des outils imaginés à la leçon 22, avec une description en trois ou quatre phrases (quoi, quand, retour) et une description pour chaque paramètre. Faites-le relire par Claude en lui demandant ce qui reste ambigu.

Sources officielles : JSON Schema for tools (Claude Academy) · API Converse et Get validated JSON results from models (documentation AWS)

Points clés à retenir

• Claude ne voit pas votre code : le schéma est tout ce qu’il connaît de l’outil.
• La description dit quand appeler l’outil ; le schéma des arguments dit avec quoi.
• Méthode rapide : un exemple, le JSON, un convertisseur, puis les descriptions écrites à la main.
• Sur Converse : toolSpec avec name, description et inputSchema.json.
• "strict": True garantit des arguments conformes au schéma.