Donner au modèle une carte des outils, pas le manuel de l’API.
Relier l’intention métier à des noms stables, des schémas minimaux, des alias, des limites négatives et des résultats testables.
Réponse courte
Une bonne description d’outil est assez courte pour être comparée et assez précise pour écarter le mauvais appel. Donnez à chaque capacité un nom d’action stable, un objectif clair, ses conditions d’usage et d’exclusion, un schéma d’entrée minimal et des états de résultat explicites. Ajoutez comme alias les mots réellement employés par les utilisateurs, mais gardez le nom canonique. Les repères 5, 50 et 500 servent à raisonner : toute la carte autorisée à petite échelle, un filtre par rôle et parcours à l’échelle intermédiaire, puis une recherche avec reclassement pour un grand catalogue. L’exécuteur valide toujours l’opération choisie. Testez aussi les outils voisins et les cas sans outil.
À retenir
- 01
Le nom décrit une capacité stable ; les alias absorbent le vocabulaire des personnes et du produit.
- 02
Les limites négatives expliquent quand un outil proche ne doit pas être choisi.
- 03
Les tests couvrent les outils voisins, les paramètres manquants et les cas où aucun appel n’est approprié.
01 / SITUATION
Une documentation longue peut cacher la seule distinction dont le modèle a besoin
Les API internes sont documentées pour les développeurs. On y trouve le transport, des options historiques et du vocabulaire d’implémentation. Pour choisir une opération, le modèle a besoin d’une autre vue : ce que fait la capacité, quand elle s’applique, ce qu’elle exige et comment interpréter son résultat.
Copier le manuel de l’API dans le contexte ajoute du bruit sans créer un bon catalogue. La couche de correspondance transforme les interfaces techniques en capacités produit concises, tout en gardant un lien direct avec le schéma et l’exécuteur qui restent les références.
02 / MECHANISM
Un contrat de capacité concis
Chaque description doit permettre d’expliquer pourquoi cet outil a été choisi plutôt que son voisin le plus proche.
- 01Nommer la capacité
Employer un verbe stable et un objet métier comme get_work_order ou propose_invoice_correction. Éviter les noms de services internes et les verbes vagues comme handle.
- 02Dire quand l’utiliser et quand l’éviter
Écrire un objectif direct, les conditions d’usage et l’exclusion la plus proche. Distinguer les outils de lecture, de proposition et d’exécution dans leur nom et leur description.
- 03Réduire le schéma
Exiger seulement les entrées indispensables. Utiliser des énumérations et des descriptions de champs lorsqu’elles lèvent une ambiguïté ; déduire l’identité et le périmètre depuis l’application.
- 04Relier le langage des utilisateurs
Associer au nom canonique les libellés du produit, les abréviations courantes et le vocabulaire métier. Ne pas créer plusieurs outils seulement pour couvrir des synonymes.
- 05Définir le sens des résultats
Renvoyer si nécessaire des états typés : réussi, vide, refusé, invalide, partiel et échoué. Rendre la progression et les demandes d’accord visibles dans l’interface.
- 06Réduire, classer et tester
Présenter toutes les descriptions autorisées à petite échelle, filtrer par des règles lorsque le catalogue grandit, puis rechercher et reclasser à grande échelle. Exécuter les tests sur des données contrôlées.
03 / Dans le travail réel
Recherche d’un ordre de travail
get_work_order lit un dossier autorisé. search_work_orders trouve des candidats. Leurs descriptions précisent qu’aucun des deux ne crée ni ne modifie une intervention.
Correction d’une facture
propose_invoice_correction renvoie des champs modifiables et leurs preuves. post_invoice reste une opération séparée, limitée par ses propres contrôles et confirmations.
Entrée d’un ticket
prepare_support_ticket reçoit l’objectif et le contexte validé. submit_support_ticket exige une proposition confirmée et renvoie l’identifiant officiel de l’outil de suivi.
Pièges fréquents
- Transmettre la documentation brute d’un fournisseur comme catalogue d’outils.
- Employer des noms et descriptions qui ne diffèrent que par un substantif.
- Rendre tous les champs de l’API facultatifs et laisser le modèle deviner les exigences cachées.
- Renvoyer un texte libre qui ne distingue ni vide, ni refusé, ni échoué.
- Tester uniquement des demandes qui reprennent exactement le nom de l’outil.
Checklist d’implémentation
- Chaque description possède un nom de capacité stable.
- L’objectif, les conditions positives et les limites négatives sont explicites.
- Le schéma d’entrée est minimal et typé.
- L’identité, l’organisation et les droits viennent de l’application.
- Les alias reflètent le langage réel du produit et de ses utilisateurs.
- Les sorties distinguent les différents résultats opérationnels.
- Les tests de sélection couvrent les voisins, les reformulations et les cas sans outil.
- Toute sélection issue d’une recherche est revérifiée avant l’exécution.
Ce que cette approche ne promet pas
- Une description concise peut oublier un cas limite si le responsable de l’opération ne la relit pas.
- Les résultats de recherche sur les consignes d’outils ne garantissent pas le même gain sur un catalogue privé ou un autre modèle.
- Les plages cinq, cinquante et cinq cents servent à raisonner. Le recouvrement et la qualité des descriptions déterminent la difficulté réelle.
Sources et nature des références
- 01AI Elements documentationVercel · 2026Documentation officielle
- 02Tool Calling to Connect to External Data SourcesVercel Academy · 2026Documentation officielle
- 03EASYTOOL: Enhancing LLM-based Agents with Concise Tool InstructionYuan et al. · 2024Recherche
- 04ToolRet: Tool Retrieval for Large Language ModelsACL Findings · 2025Recherche
- 05ToolRerank: Adaptive and Hierarchy-Aware Reranking for Tool RetrievalLREC-COLING · 2024Recherche
Questions fréquentes
Faut-il mettre des exemples dans la description d’un outil ?
Quelques exemples peuvent clarifier une limite ou un paramètre. Les grands ensembles d’exemples appartiennent aux tests ou à la recherche, pas à chaque prompt.
Comment représenter les alias ?
Gardez une capacité canonique et rattachez les termes utilisés dans les écrans, la documentation et les demandes comme métadonnées ou exemples de recherche.
Quand versionner une description d’outil ?
Dès que son sens, son schéma, ses résultats ou ses conditions d’accès changent. Les évaluations de sélection et d’exécution doivent alors être relancées.