Schémas d'outils

Après avoir écrit votre fonction d’outil, l’étape suivante est de créer un schéma JSON qui explique à Claude quels arguments votre fonction attend et comment l’utiliser. Ce schéma sert de documentation que Claude lit pour savoir quand et comment appeler vos outils.

Comprendre le JSON Schema

JSON Schema n’est pas spécifique à l’IA ou aux appels d’outils — c’est une spécification de validation de données largement utilisée depuis des années. La communauté IA l’a adopté parce que c’est un moyen pratique de décrire les paramètres d’une fonction et de valider les données.

La spécification complète d’un outil comporte trois parties principales :

Écrire des descriptions efficaces

Il faut bien voir le renversement que cela implique : la description n’est pas de la documentation, c’est du code exécutable par le modèle. Personne ne la lira jamais, mais c’est elle — et elle seule — qui décide si l’outil est appelé au bon moment. Une fonction parfaitement écrite avec une description vague ne sera jamais invoquée, et vous chercherez l’erreur dans votre code.

D’où les bonnes pratiques ci-dessous, qui reviennent toutes à la même exigence : décrire les situations d’usage, pas l’implémentation.

• Visez 3-4 phrases expliquant ce que l’outil fait
• Décrivez quand Claude devrait l’utiliser
• Expliquez quel type de données il retourne
• Fournissez des descriptions détaillées pour chaque argument

L’astuce : utiliser Claude pour générer les schémas

L’écriture manuelle d’un schéma est fastidieuse et sujette aux oublis — un type manquant, un champ absent de required, une énumération non contrainte. La déléguer fonctionne bien, à une condition : relisez le résultat. Le schéma généré est syntaxiquement correct dans l’immense majorité des cas, mais c’est vous qui savez lesquels de vos paramètres sont réellement obligatoires et quelles valeurs ils acceptent.

1. Copiez le code de votre fonction d’outil
2. Demandez à Claude d’écrire un schéma JSON pour l’appel d’outil
3. Incluez la documentation Anthropic sur l’utilisation d’outils comme contexte
4. Laissez Claude générer un schéma correctement formaté

Le prompt pourrait ressembler à : “Écris un schéma JSON valide pour l’appel d’outils de cette fonction. Suis les bonnes pratiques listées dans la documentation jointe.”

Implémenter le schéma dans le code

Une fois le schéma généré, copiez-le dans votre fichier de code. Voici un bon patron de nommage à suivre :

from datetime import datetime

def get_current_datetime(date_format="%Y-%m-%d %H:%M:%S"):
    if not date_format:
        raise ValueError("date_format cannot be empty")
    return datetime.now().strftime(date_format)

# Schema associe : meme nom + _schema
get_current_datetime_schema = {
    "name": "get_current_datetime",
    "description": "Returns the current date and time formatted according to the specified format",
    "input_schema": {
        "type": "object",
        "properties": {
            "date_format": {
                "type": "string",
                "description": "A string specifying the format of the returned datetime. Uses Python's strftime format codes.",
                "default": "%Y-%m-%d %H:%M:%S"
            }
        },
        "required": []
    }
}

La convention nom_de_fonction suivie de nom_de_fonction_schema permet de garder vos schémas organisés et faciles à associer avec leurs fonctions correspondantes.

Ajouter la sécurité de typage

Typer le schéma déplace la détection d’erreur du moment de l’exécution vers celui de l’écriture. Sans typage, une clé mal orthographiée passe inaperçue jusqu’à ce que Claude appelle l’outil avec des arguments inattendus — un symptôme qui ressemble à un problème de modèle alors que c’est une faute de frappe.

from anthropic.types import ToolParam

get_current_datetime_schema = ToolParam({
    "name": "get_current_datetime",
    "description": "Returns the current date and time formatted according to the specified format",
    # ... reste du schema
})

Bien que ce ne soit pas strictement nécessaire au fonctionnement, cela prévient les erreurs de typage quand vous utilisez le schéma avec l’API de Claude et rend votre code plus robuste.

def get_weather(location, unit="celsius"):
    if not location:
        raise ValueError("location cannot be empty")
    # ... appel API meteo

get_weather_schema = {
    "name": "get_weather",
    "description": "Retrieves the current weather for a given location. Use when the user asks about weather conditions. Returns temperature and conditions.",
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The city and country, e.g. 'Paris, France'"
            },
            "unit": {
                "type": "string",
                "description": "Temperature unit: 'celsius' or 'fahrenheit'",
                "default": "celsius",
                "enum": ["celsius", "fahrenheit"]
            }
        },
        "required": ["location"]
    }
}