Des outils que Claude choisit bien

Deuxième partie du cours — Les leçons 7 à 16 suivent le programme du cours officiel « Tool use with the Messages API » de Claude Academy, l’académie d’Anthropic ; leur contenu, rédigé en français par Corsen, s’appuie sur la documentation officielle de l’API Claude citée à chaque leçon. Elles partent d’une boucle d’outils qui fonctionne, comme celle construite aux leçons 3 et 4, pour la rendre fiable, rapide et économique. L’entreprise Ingénova qui illustre les exemples est fictive.

Objectifs

À l’issue de cette leçon, vous serez capable de :

• Rédiger une définition d’outil que Claude sait quand utiliser, et quand ne pas utiliser
• Regrouper des outils qui se chevauchent
• Mesurer l’effet d’une réécriture avec une petite évaluation

Quand Claude se trompe d’outil, regardez d’abord la définition

Votre boucle d’outils fonctionne, puis surviennent des symptômes familiers : Claude appelle le mauvais outil, fait trois appels pour obtenir un seul fait, ou envoie 0142 là où votre code attend ING-2026-0142. Dans la plupart des cas, la cause est dans la définition de l’outil : Claude décide d’appeler un outil en lisant la demande de l’utilisateur et la description de chaque outil. Une définition d’outil est un prompt ; écrivez-la comme tel.

Une définition compte quatre parties :

• name : le nom par lequel Claude appelle l’outil ;
• description : le texte que Claude lit pour décider ;
• input_schema : les paramètres, en JSON Schema, chacun avec son type et sa propre description, et la liste required ;
• input_examples (facultatif) : des exemples d’entrées valides, validés par l’API contre le schéma.

Une description de trois ou quatre phrases au minimum

La documentation officielle recommande au moins trois ou quatre phrases par description, davantage pour un outil complexe, en couvrant : ce que fait l’outil et ce qu’il renvoie, quand l’utiliser et quand ne pas l’utiliser, ce que signifie chaque paramètre, et ce qu’il ne renvoie pas. Soyez précis sur le moment de l’appel, sans forcer le ton. La documentation note que les modèles récents suivent de près le prompt système : une consigne martelée comme « CRITIQUE : utilise TOUJOURS cet outil » les pousse à l’appeler à tort, et « Utilise cet outil quand… » suffit. Le réglage effort joue aussi : à un effort bas, Claude fait moins d’appels d’outils et en regroupe davantage.

{
  "name": "consulter_projet",
  "description": "Renvoie l'état actuel d'un projet Ingénova : phase, respect du planning, chef de projet, heures budgétées et consommées, échéance, ville du site et client. À utiliser uniquement quand l'utilisateur parle d'un projet précis, par son nom ou son numéro ; si le numéro est partiel (« le dossier 0142 »), complète-le au format ING-AAAA-NNNN avant l'appel. Passe le paramètre fields pour ne demander que les champs utiles à la question. Cet outil ne renvoie ni les permis ni la facturation : utilise consulter_permis ou synthese_facturation pour cela.",
  "input_schema": {
    "type": "object",
    "properties": {
      "project_id": {"type": "string", "description": "Numéro complet au format ING-AAAA-NNNN, par exemple ING-2026-0142."},
      "fields": {
        "type": "array",
        "items": {"type": "string", "enum": ["phase", "planning", "chef", "heures", "echeance", "site", "client"]},
        "description": "Champs à renvoyer. Omettre pour tout renvoyer."
      }
    },
    "required": ["project_id"]
  },
  "input_examples": [
    {"project_id": "ING-2026-0142", "fields": ["phase", "planning"]},
    {"project_id": "ING-2025-0417"}
  ]
}

La dernière phrase de la description, sur ce que l’outil ne renvoie pas, évite que Claude l’appelle pour une question de facturation.

Moins d’outils, mieux définis

Cinq outils minces, chacun avec une ligne de description, se font concurrence : Claude doit deviner lequel répond à une question qui en touche plusieurs. La documentation recommande de regrouper les opérations liées dans moins d’outils, par exemple un seul outil avec un paramètre fields, ou un paramètre d’action, plutôt qu’un outil par verbe. Quand la surface grandit, préfixez les noms par service (github_list_prs, slack_send_message). Au-delà de ce que le nommage permet de gérer — des dizaines d’outils dont les définitions encombrent le contexte —, l’outil de recherche d’outils (tool search) charge les définitions à la demande : vous marquez les outils defer_loading: true, et Claude ne découvre que ceux dont il a besoin.

Pour les entrées imbriquées ou sensibles au format, ajoutez des input_examples : chaque exemple doit être valide au regard du schéma, sinon l’API renvoie une erreur 400.

Vos messages d’erreur sont aussi des prompts

« Erreur 404 » n’apprend rien à Claude. « Numéro de projet introuvable : vérifiez le format ING-AAAA-NNNN » lui dit exactement quoi corriger, et il se corrige généralement à l’appel suivant. Renvoyez l’erreur comme un résultat d’outil, avec is_error: true et un message qui explique la marche à suivre.

Mesurer avec une évaluation

Une évaluation est un jeu fixe de questions dont la bonne réponse est connue, que l’on soumet à Claude et que l’on note. Pour le choix d’outil, il suffit d’une trentaine de questions réalistes, chacune étiquetée avec l’outil qui devrait être appelé. Faites tourner le jeu avant et après la réécriture, sur le même modèle : seule la définition change, et la différence de taux de bons choix mesure l’effet de votre travail. Les erreurs se concentrent souvent là où deux outils se chevauchaient ; après regroupement, ce chevauchement disparaît.

À vous de jouer

Réécrire votre outil le plus mal choisi.

1. Prenez l’outil que Claude choisit le plus souvent à tort.
2. Réécrivez sa description : ce qu’il renvoie, quand l’utiliser et quand ne pas l’utiliser, ses paramètres, ce qu’il ne renvoie pas.
3. Regroupez-le avec ses voisins s’ils se chevauchent ; ajoutez un input_examples si son format est piégeux.
4. Écrivez quinze à trente questions étiquetées, et comparez le taux de bons choix avant et après.

Sources officielles : Define tools — Best practices for tool definitions (documentation Claude : descriptions, regroupement, input_examples) · Tool search tool · Prompting best practices (documentation Claude : ton des consignes d’outils) · Effort (documentation Claude : effort et appels d’outils)

Points clés à retenir

• Claude choisit un outil en lisant sa description : trois ou quatre phrases au minimum, avec quand l’utiliser et quand ne pas l’utiliser
• Regroupez les outils qui se chevauchent dans un outil paramétré ; préfixez les noms quand la surface grandit
• input_examples pour les formats piégeux ; l’outil de recherche d’outils pour les très grandes bibliothèques
• Des messages d’erreur qui disent comment corriger, et une évaluation avant/après pour mesurer