Les schémas d'outils

Claude ne voit jamais le code de vos fonctions. Il ne connaît un outil que par sa définition : un nom, une description et un schéma JSON des arguments. Cette leçon écrit la définition de get_current_datetime et montre ce qui fait une bonne description.

Les parties d’une définition d’outil

D’autres propriétés facultatives existent, dont strict, qui garantit des arguments conformes au schéma (leçon 31). JSON Schema n’a rien de propre à l’IA : c’est une spécification de validation de données utilisée depuis des années, adoptée parce qu’elle décrit bien des paramètres de fonction.

Pourquoi la description compte autant

À chaque requête qui contient des outils, l’API construit un prompt système spécial à partir de leurs définitions. La description est donc lue par Claude à chaque fois : c’est elle qui décide si l’outil est appelé au bon moment. Une fonction parfaite avec une description vague ne sera pas appelée quand il le faut, et vous chercherez l’erreur dans votre code.

La documentation en fait le premier facteur de performance des outils, et recommande au moins trois à quatre phrases par description, davantage pour un outil complexe :

• ce que fait l’outil ;
• quand l’utiliser, et quand ne pas l’utiliser ;
• ce que signifie chaque paramètre et son effet ;
• les limites : ce que l’outil ne renvoie pas, les cas qu’il ne couvre pas.

La définition de get_current_datetime

from anthropic.types import ToolParam

get_current_datetime_schema = ToolParam({
    "name": "get_current_datetime",
    "description": (
        "Renvoie la date et l'heure actuelles du serveur, mises en forme selon un format strftime de Python. "
        "Utilisez cet outil dès que la réponse dépend de la date ou de l'heure du jour, par exemple pour savoir "
        "quel jour on est ou pour partir de maintenant dans un calcul d'échéance. "
        "L'heure est l'heure locale du serveur, sans fuseau horaire. "
        "L'outil ne fait aucun calcul de dates : utilisez add_duration_to_datetime pour cela."
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "date_format": {
                "type": "string",
                "description": "Format strftime de la valeur renvoyée, par exemple '%Y-%m-%d %H:%M:%S' ou '%H:%M'.",
                "default": "%Y-%m-%d %H:%M:%S",
            }
        },
        "required": [],
    },
})

Deux habitudes rendent le code plus sûr. La convention de nommage nom_de_la_fonction_schema associe chaque définition à sa fonction d’un coup d’œil. Le type ToolParam du SDK permet à votre éditeur et à un vérificateur de types de signaler une clé mal orthographiée dès l’écriture, au lieu d’un comportement étrange à l’exécution.

La dernière phrase de la description mentionne un outil qui n’existe pas encore : add_duration_to_datetime arrive à la leçon 29. Dire à Claude quel outil employer à la place évite qu’il détourne celui-ci pour un usage qui n’est pas le sien.

Faire rédiger le schéma par Claude, puis le relire

Écrire un schéma à la main est fastidieux et propice aux oublis : un type manquant, un champ absent de required, une liste de valeurs non contrainte. Le cours officiel propose de le déléguer à Claude :

1. copiez le code de la fonction ;
2. demandez un schéma d’outil valide, par exemple : « Écris la définition d’outil pour cette fonction, en suivant les bonnes pratiques de la documentation jointe » ;
3. joignez la page de documentation sur la définition des outils ;
4. relisez le résultat.

La relecture n’est pas facultative. Le schéma généré est presque toujours syntaxiquement correct, mais vous seul savez quels paramètres sont vraiment obligatoires, quelles valeurs ils acceptent, et quand l’outil ne doit pas servir.

Des exemples d’arguments, pour les outils complexes

Pour un outil aux entrées imbriquées ou au format sensible, le champ input_examples montre à Claude des appels bien formés. Chaque exemple doit être valide selon input_schema, sinon la requête échoue avec une erreur 400. Les exemples ajoutent des jetons au prompt, de 20 à 50 environ pour un exemple simple et de 100 à 200 pour un objet imbriqué. Pour get_current_datetime, une bonne description suffit.

À vous de jouer

Le schéma d’un outil météo. Écrivez la définition de cette fonction, puis comparez avec la solution.

def get_weather(location, unit="celsius"):
    if not location:
        raise ValueError("location ne peut pas être vide, exemple : 'Lyon, France'")
    ...  # appel à une API météo

get_weather_schema = ToolParam({
    "name": "get_weather",
    "description": (
        "Renvoie la météo actuelle d'une ville : température et conditions (ensoleillé, pluie, etc.). "
        "Utilisez cet outil quand l'utilisateur demande le temps qu'il fait maintenant dans un lieu précis. "
        "Il ne fournit pas de prévisions pour les jours suivants. "
        "Si le lieu est ambigu, demandez à l'utilisateur de préciser le pays."
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "Ville et pays, par exemple 'Lyon, France'.",
            },
            "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"],
                "description": "Unité de la température renvoyée.",
                "default": "celsius",
            },
        },
        "required": ["location"],
    },
})

Sources officielles : Tool schemas (Claude Academy) · Define tools (documentation Claude : spécification, bonnes pratiques, input_examples)

Points clés à retenir

• Une définition d’outil : name, description, input_schema, et en option input_examples ou strict.
• La description est le premier facteur de performance : au moins trois à quatre phrases, dont quand ne pas utiliser l’outil.
• L’API construit à chaque requête un prompt système à partir des définitions.
• Faites rédiger le schéma par Claude si vous voulez, mais relisez-le toujours.
• ToolParam fait repérer les fautes de frappe dès l’écriture.