Les schémas d'outils

Notre fonction get_current_datetime existe, mais Claude n’en sait rien : le modèle ne voit pas votre code, il ne voit que ce que vous lui déclarez. Le schéma d’outil est cette déclaration — un document JSON envoyé avec chaque requête, qui décrit à Claude ce que fait la fonction, quels arguments elle attend et comment les remplir. C’est littéralement la fiche technique sur laquelle le modèle fonde deux décisions : dois-je utiliser cet outil pour cette question ? et avec quels arguments ?

Structure du schéma

Un schéma d’outil s’articule en trois parties, chacune répondant à une question de Claude :

• name : l’identifiant de la fonction — c’est lui qui reviendra dans les blocs tool_use pour le routage
• description : ce que fait l’outil et quand l’utiliser — c’est sur ce texte que le modèle décide d’appeler ou non
• input_schema : la description des arguments au format JSON Schema standard — types, descriptions, valeurs par défaut, champs requis

Rédiger de bonnes descriptions

De ces trois parties, la description est celle qui détermine la qualité des appels — et celle qu’on bâcle le plus souvent. Trois ou quatre phrases suffisent, mais elles doivent couvrir le triptyque complet : ce que fait l’outil, quand l’utiliser, et ce qu’il retourne. « Retourne la date et l’heure actuelles » dit le quoi ; ajouter « à utiliser dès qu’une question dépend de la date du jour » précise le quand, et « retourne une chaîne formatée » clôt le contrat. Chaque argument mérite le même soin : sa description doit indiquer son format attendu et donner un exemple si le format n’est pas évident — c’est ce texte, et lui seul, qui empêchera Claude d’inventer un format de date fantaisiste.

Exemple de schéma

get_current_datetime_schema = {
    "name": "get_current_datetime",
    "description": "Retourne la date et l'heure actuelles formatees selon le format specifie",
    "input_schema": {
        "type": "object",
        "properties": {
            "date_format": {
                "type": "string",
                "description": "Format de la date retournée. Utilise les codes strftime de Python.",
                "default": "%Y-%m-%d %H:%M:%S"
            }
        },
        "required": []
    }
}

Deux détails de cet exemple sont des choix, pas des automatismes. La mention « codes strftime de Python » dans la description de l’argument ancre Claude dans une convention qu’il connaît parfaitement — sans elle, il pourrait générer un format d’un autre langage. Et le tableau required vide déclare date_format optionnel : cohérent avec la valeur par défaut de notre fonction Python. Cette cohérence schéma-fonction est votre responsabilité — l’API ne vérifie pas que le schéma correspond au code, et un décalage (un paramètre requis dans le code mais optionnel dans le schéma) produit des erreurs d’exécution difficiles à diagnostiquer.

Laisser Claude écrire le schéma

Écrire ces schémas à la main devient vite fastidieux — et c’est une tâche où Claude excelle. Le procédé : copiez votre fonction Python dans une conversation, demandez « génère le schéma JSON de tool calling pour cette fonction », et joignez au besoin un extrait de la documentation Anthropic comme référence de format. Le modèle lit la signature, les valeurs par défaut et la docstring, et produit un schéma généralement correct du premier coup. Relisez surtout les descriptions générées : Claude décrit ce que la fonction fait, mais vous seul savez quand votre application veut qu’elle soit utilisée — cette nuance d’intention se rajoute à la main.

Typage optionnel

from anthropic.types import ToolParam

get_current_datetime_schema = ToolParam({
    # votre dictionnaire de schema
})

Envelopper le dictionnaire dans ToolParam n’est pas obligatoire — l’API accepte le dictionnaire nu — mais offre la vérification de types de votre éditeur : une clé mal orthographiée (descriptions au lieu de description) est signalée à l’écriture plutôt que découverte en production. Sur un projet qui accumule les outils, ce filet vaut la ligne d’import.

Points clés à retenir

• Claude ne voit jamais votre code : le schéma est la seule chose qu’il connaisse de l’outil
• Trois parties : name (routage), description (décision d’appel), input_schema (arguments)
• La description porte le triptyque quoi / quand / retour — c’est elle qui fait la qualité des appels
• La cohérence entre schéma et fonction est votre responsabilité : l’API ne la vérifie pas
• Faites générer les schémas par Claude à partir du code, puis affinez les descriptions d’intention