Créer des outils que Claude choisit

La démonstration de cette vidéo a été enregistrée en septembre 2026. Elle a été exécutée sur Claude Sonnet 5 (claude-sonnet-5). Les résultats peuvent différer sur les modèles plus récents.

Supposons que votre boucle d'outils fonctionne, puis l'une de ces situations se produit :

• Claude appelle le mauvais outil.
• Il effectue trois appels d'outils pour un seul fait.
• Il transmet 0142 alors que votre code attend MEG-2026-0142.

Claude ne reçoit jamais la fonction qui exécute votre outil. Il ne voit que la définition que vous envoyez et les résultats que vous renvoyez. Ainsi, lorsque Claude utilise mal un outil, examinez d'abord la définition.

Meridian dispose d'un assistant interne pour répondre aux questions des employés sur les projets, les permis et la facturation. La réécriture de ses définitions d'outils a fait passer son score de 14 à 26 sur 30 questions de test, sur le même modèle.

Ce que Claude voit de votre outil

Une définition d'outil est un bloc JSON qui indique à Claude qu'un outil existe. Vous l'envoyez dans la liste tools de chaque requête.

Voici la définition réécrite de l'outil de projet de Meridian. Elle comporte quatre parties.

{
  "name": "lookup_project_status",
  "description": "Returns current facts about a single Meridian …",
  "input_schema": {
    "type": "object",
    "properties": {
      "project_id": {
        "type": "string",
        "description": "Full Meridian job number in the format MEG-YYYY-NNNN, e.g. MEG-2026-0142."
      },
      "fields": {
        "type": "array",
        "items": {
          "type": "string",
          "enum": ["phase", "status", "lead", "hours", "deadline", "site", "client"]
        },
        "description": "Which fields to return. Omit to return everything."
      }
    },
    "required": ["project_id"]
  },
  "input_examples": [
    {"project_id": "MEG-2026-0142", "fields": ["phase", "status"]},
    {"project_id": "MEG-2025-0417", "fields": ["lead", "hours"]},
    {"project_id": "MEG-2024-0233"}
  ]
}

• name est le nom par lequel Claude désigne l'outil.
• description est un texte brut que vous rédigez et que Claude lit. Il est raccourci ici et présenté en entier dans la section suivante.
• input_schema répertorie les paramètres de l'outil au format JSON Schema, chacun avec un nom, un type et sa propre description. required indique lesquels doivent obligatoirement être fournis.
• input_examples est facultatif. Il montre à Claude à quoi ressemble une bonne entrée, comme un numéro de dossier complet. Chaque exemple doit être valide par rapport à input_schema, sinon l'API renvoie une erreur 400.

Claude décide d'effectuer ou non un appel d'outil en lisant la requête de l'utilisateur et la description de chaque outil.

Rédigez une description détaillée

Des quatre parties, la description est celle qui compte le plus.

Visez au moins trois à quatre phrases, davantage si l'outil est complexe. Couvrez quatre aspects :

1. Ce que fait l'outil
2. Quand l'utiliser, et quand ne pas l'utiliser
3. Ce que signifie chaque paramètre
4. Ce qu'il ne renvoie pas

Voici la description complète de Meridian :

Returns current facts about a single Meridian project: phase,
schedule status, project lead, hours budgeted and consumed,
deadline, site city, and client. Use this only when the user asks
about a specific project by name or job number; if only a partial
number is given (e.g. 'the 0142 job'), normalize it to the full
MEG-YYYY-NNNN format before calling. Pass the fields parameter to
fetch just the fields the question needs instead of the whole
record. This tool does not return permit or invoicing information.
Use get_permit_status or get_billing_summary for those.



Indiquer quand utiliser l'outil, et quand ne pas l'utiliser, aide Claude à éviter d'appeler le mauvais outil. La description de Meridian limite l'outil aux questions portant sur un seul projet. Pour les permis et la facturation, elle nomme les outils à utiliser.

Combinez les outils qui se chevauchent en un seul

Une bonne description n'est pas d'une grande aide lorsque plusieurs outils font presque le même travail.

Le premier ensemble de Meridian comptait six outils minces, chacun doté d'une description d'une seule ligne. Quatre d'entre eux renvoyaient chacun un fait de projet. Ces quatre outils se chevauchaient, si bien que Claude devait deviner lesquels une question nécessitait.

La solution consiste à combiner les quatre en un seul outil, lookup_project_status, avec un paramètre fields qui indique quels faits renvoyer. Les deux autres, pour les permis et la facturation, remplissent des fonctions différentes, ils restent donc inchangés. Six outils deviennent trois.

Mesurez le changement à l'aide d'une évaluation

Une évaluation est un ensemble fixe de questions de test dont les bonnes réponses sont connues, exécuté sur Claude et noté. Elle montre si les nouvelles définitions sont meilleures.

L'évaluation de Meridian vérifie si Claude appelle les bons outils. Elle compte 30 questions qu'un employé pourrait poser, chacune associée aux bons appels d'outils. Meridian a exécuté les 30 questions à deux reprises sur claude-sonnet-5, une fois avec chaque ensemble d'outils.

Corrigez uniquement la partie fautive

Pour corriger un échec, trouvez la partie de la définition qui est en cause, modifiez uniquement cette partie, puis réexécutez votre évaluation.

Dépannage de l'utilisation d'outils répertorie davantage de symptômes et de corrections.

Points clés à retenir

• Rédigez des descriptions d'au moins trois à quatre phrases, et indiquez quand ne pas utiliser l'outil.
• Combinez les outils qui se chevauchent en un seul outil doté de paramètres.
• Mesurez les changements à l'aide d'une évaluation.
• Pour corriger un échec, modifiez uniquement la partie fautive.