Vous avez donné deux outils à l’agent : updateUser et deactivateUser. Un ticket indique « fermer ce compte ». L’agent appelle deactivateUser, alors qu’un ticket presque identique l’avait récemment conduit à appeler updateUser avec status: "closed". Votre API acceptait cette valeur, mais elle déclenchait un comportement différent en aval.
Essayez Apidog dès aujourd'hui
Rien n’était cassé : le modèle devait choisir entre deux options plausibles, sans indication claire sur celle qui s’appliquait. La sélection d’outils est souvent attribuée au modèle, alors que le schéma est généralement la seule source d’information dont il dispose.
Ce guide montre comment :
- rédiger des noms et descriptions qui différencient réellement les outils ;
- concevoir des paramètres qui rendent les erreurs difficiles ;
- expliciter les prérequis et l’ordre d’exécution ;
- tester la sélection d’outils sans toucher aux données de production ;
- maintenir ces descriptions dans une spécification partagée.
Si vos outils sont générés à partir d’une spécification, comme dans ce guide sur la transformation d’une spécification OpenAPI en outils d’agent, ces décisions doivent être prises directement dans la spécification.
Ce que le modèle voit réellement
Au moment de choisir un outil, le modèle dispose de :
- la conversation ;
- l’invite système ;
- la liste des définitions d’outils.
Chaque définition contient un nom, une description et un schéma de paramètres. Le modèle ne voit pas votre documentation d’API, vos commentaires de code ni la connaissance interne qui fait de updateUser un outil obsolète.
Toute désambiguïsation doit donc figurer dans la définition elle-même. Le guide d’appel de fonctions d’OpenAI et la documentation Anthropic sur l’utilisation des outils insistent sur le même point : la description est l’élément le plus important de la définition. Elle doit être suffisamment détaillée, même si elle est plus longue.
Les erreurs de sélection se répartissent généralement en quatre catégories :
- Outil similaire sélectionné : les descriptions se chevauchent. Indiquez quand chaque outil ne doit pas être utilisé.
- Aucun outil sélectionné : le vocabulaire de la tâche ne correspond pas à celui de la description. Reprenez les mots employés par les utilisateurs.
- Bon outil, mauvais arguments : les paramètres sont ambigus. Ajoutez des types, des énumérations, des unités et des exemples.
- Mauvais ordre d’exécution : une étape dépend d’une autre, mais le prérequis n’est pas explicite. Mentionnez-le dans la description.
Nommez les outils selon leur action
Les noms véhiculent beaucoup de signal : le modèle les lit avant le reste de la définition.
Utilisez une convention cohérente, par exemple verbeNom :
createOrder
refundOrder
getOrderStatus
Évitez de mélanger order_create, getOrder et refund. La cohérence rend tout l’ensemble plus lisible.
Soyez précis sur la ressource et l’action :
searchCustomersByEmail
est préférable à :
search
Le premier nom indique ce qui est recherché et le critère utilisé.
Évitez également le jargon interne. Si votre API appelle un client une « entité » et un abonnement un « instrument », le modèle ne fera pas forcément le lien avec un ticket parlant de « client » et de « plan ». Nommez les outils dans le langage de la tâche.
Enfin, ne réutilisez jamais le même nom dans plusieurs contextes. Deux outils appelés list, même dans des espaces de noms différents, deviennent ambigus dès qu’ils sont exposés dans une même liste.
Rédigez des descriptions discriminantes
Une bonne description répond à quatre questions :
- Que fait l’outil ?
- Que modifie-t-il ?
- Quand faut-il l’utiliser ?
- Quand ne faut-il pas l’utiliser ?
Une paire ambiguë
{ "name": "updateUser", "description": "Met à jour un utilisateur." }
{ "name": "deactivateUser", "description": "Désactive un utilisateur." }
Une paire qui sépare les cas
{
"name": "updateUser",
"description": "Met à jour les champs de profil d'un utilisateur actif, tels que le nom, l'e-mail ou le fuseau horaire. À utiliser pour les corrections et les modifications de profil demandées par l'utilisateur. NE modifie PAS le statut du compte. Pour désactiver un compte, utilisez deactivateUser à la place. Ne pas utiliser pour fermer ou annuler un compte."
}
{
"name": "deactivateUser",
"description": "Désactive un compte utilisateur, révoquant toutes les sessions et bloquant la connexion. Réversible avec reactivateUser. À utiliser lorsqu'un client demande de fermer, annuler, mettre en pause ou suspendre son compte. NE supprime PAS les données. Pour une suppression permanente, utilisez deleteUser, qui ne peut être annulée."
}
Ces descriptions utilisent quatre techniques efficaces :
-
Nommer l’outil concurrent : « utilisez
deactivateUserà la place » résout directement l’ambiguïté. - Reprendre le vocabulaire utilisateur : « fermer », « annuler », « suspendre » et « mettre en pause » correspondent aux tickets réels.
- Décrire les limites : les déclarations négatives différencient souvent mieux deux outils voisins que leurs capacités positives.
- Indiquer la réversibilité et le risque : le modèle peut alors prendre en compte les conséquences.
La longueur n’est pas un problème. Une description de cent mots coûte peu de contexte si elle évite un appel erroné à un point de terminaison destructeur. Elle complète les protections applicatives décrites dans ce guide sur les garde-fous des agents IA, mais ne les remplace pas.
Concevez des paramètres qui limitent les erreurs
Une fois le bon outil sélectionné, les arguments deviennent le principal point de défaillance. Le vocabulaire de validation du schéma JSON fournit la plupart des contraintes nécessaires.
Utilisez des énumérations
Un paramètre status générique invite le modèle à inventer une valeur. Une énumération le limite aux valeurs acceptées :
"status": {
"type": "string",
"enum": ["pending", "paid", "refunded", "cancelled"],
"description": "Statut de la commande. 'cancelled' signifie jamais exécutée ; 'refunded' signifie exécutée puis annulée."
}
Mettez les unités dans les noms
amount peut signifier des dollars ou des centimes. Préférez :
amount_cents
timeout_seconds
distance_meters
duration_ms
L’unité devient alors difficile à ignorer.
Donnez des exemples de formats
Pour une date, indiquez le format et un exemple :
"description": "Date de début au format ISO 8601, par exemple 2026-08-26"
``’API sait remplir par défaut pousse le modèle à inventer une valeur.
Alignez le schéma sur le comportement réel de l’API. Ces erreurs sont souvent liées à la conception des réponses d’erreur, abordée dans ce guide sur les [messages d’erreur d’API pour les agents IA](https://apidog.com/fr/blog/api-error-messages-for-ai-agents?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation).
### Préférez les paramètres plats
Les structures imbriquées multiplient les erreurs :
json
{
"customer": {
"address": {
"postal_code": "..."
}
}
}
Lorsque c’est possible, exposez plutôt :
text
customer_postal_code
Aplatissez les paramètres à la limite de l’outil, puis reconstruisez la structure dans votre exécuteur.
### Divisez les outils surchargés
Un outil doté d’un paramètre `mode` qui change la signification de tous les autres champs est probablement plusieurs outils déguisés. Séparez-les : la sélection devient plus fiable et chaque schéma plus simple.
## Indiquez les prérequis et l’ordre
Les workflows en plusieurs étapes échouent lorsque la séquence n’est pas explicite. Décrivez le prérequis directement dans l’outil dépendant :
json
{
"name": "captureCharge",
"description": "Capture une charge précédemment autorisée. Nécessite un authorization_id de authorizeCharge. Appelez authorizeCharge en premier si vous n'en avez pas déjà un. Ne peut pas capturer plus que le montant autorisé."
}
Le même principe s’applique à :
- créer avant de mettre à jour ;
- télécharger avant de traiter ;
- autoriser avant de capturer.
Si l’étape précédente n’est pas nommée, le modèle peut la sauter. Pour les séquences entre plusieurs agents, appliquez également les règles de [passage de contexte entre sous-agents](https://apidog.com/fr/blog/agent-handoff-context-passing?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation).
## Testez la sélection comme n’importe quel comportement
Les descriptions sont du code : elles peuvent régresser. Une personne les raccourcit pour respecter un guide de style, puis l’agent choisit le mauvais point de terminaison quelques jours plus tard.
Créez une suite de 20 à 50 invites. Pour chacune :
1. définissez l’outil attendu ;
2. exécutez l’agent ;
3. enregistrez uniquement le nom de l’outil sélectionné ;
4. comparez le résultat attendu au résultat obtenu.
Les arguments peuvent varier d’une exécution à l’autre ; le choix de l’outil devrait rester stable. Cette méthode reprend les principes du [test d’agents non déterministes](https://apidog.com/fr/blog/testing-non-deterministic-ai-agents?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation).
Commencez par les cas les plus fragiles :
- les deux outils les plus similaires, avec des invites destinées à chacun ;
- des invites utilisant le vocabulaire client plutôt que celui de l’API ;
- une invite qui ne devrait correspondre à aucun outil et devrait déclencher une question ;
- un outil destructeur pour lequel une erreur a un coût réel.
Exécutez chaque invite plusieurs fois. Un outil sélectionné quatre fois sur cinq reste un coup de dés en production : sa description doit être améliorée.
Dirigez les tests vers des mocks afin qu’aucune exécution ne touche aux données réelles. Ce guide sur l’[exécution d’agents contre des mocks plutôt qu’en production](https://apidog.com/fr/blog/ai-agents-mock-apis-not-production?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation) détaille cette configuration. [Apidog](https://apidog.com/?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation) peut servir ces mocks depuis la même définition que celle utilisée pour générer les outils.
## Trois ensembles d’outils qui échouent souvent
### 1. L’ensemble CRUD
Une API expose `getUser`, `listUsers`, `searchUsers` et `queryUsers`, issus de points de terminaison ayant évolué séparément. Pour le modèle, ces noms représentent presque la même idée.
La solution n’est pas nécessairement d’améliorer les quatre descriptions. Exposez à l’agent uniquement l’outil approprié et laissez les autres en dehors de la liste. Un ensemble organisé est souvent plus fiable qu’un ensemble complet.
### 2. L’ensemble d’administration
Les outils de lecture et les outils destructeurs peuvent partager le même ton :
text
getInvoice
voidInvoice
deleteInvoice
Ajoutez les conséquences à la description des outils destructeurs, indiquez s’ils sont réversibles et exigez une approbation lorsque nécessaire. Appliquez les protections dans l’exécuteur plutôt que de faire confiance à la formulation seule. Voir le guide sur la façon d’[empêcher les agents IA de détruire vos API](https://apidog.com/fr/blog/prevent-ai-agents-nuking-apis?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation).
### 3. L’ensemble hérité
Deux points de terminaison peuvent faire le même travail, alors que l’un est déprécié. Si la spécification contient toujours les deux, le générateur les expose tous les deux et l’agent peut choisir l’ancien.
Deux solutions :
- supprimer l’opération dépréciée des outils générés ;
- commencer sa description par :
`Déprécié. Utilisez createOrderV2 à la place.`
Les modèles respectent généralement cette indication lorsqu’elle est placée au début, mais peuvent l’ignorer si elle est enfouie à la fin.
## Traitez les descriptions comme une configuration partagée
Si les descriptions déterminent le comportement, leur propriété ne doit pas être accidentelle. Évitez qu’elles restent dans un fichier local configuré par la première personne ayant créé l’agent.
Traitez l’ensemble d’outils comme une interface partagée, avec revue et historique des modifications. Les plateformes orientées agents modélisent souvent cette configuration directement. Par exemple, un agent Sharkly regroupe les instructions, le runtime, les compétences et les dépôts dans une configuration sauvegardée, partageable dans un Espace via [Sharkly](https://sharkly.ai).
L’intérêt n’est pas le stockage. C’est qu’une modification de description devienne une évolution révisable, appliquée à toute l’équipe, plutôt qu’un ajustement local qui fait diverger les agents.
## Observez le vocabulaire réel des utilisateurs
L’écart le plus fréquent concerne les mots employés :
- votre API dit « abonnement » ;
- vos clients disent « plan », « adhésion » ou « facturation » ;
- votre API dit « désactiver » ;
- vos clients disent « annuler », « fermer » ou « éteindre ».
Analysez les tickets de support, les journaux de recherche et les transcriptions d’exécutions échouées. Reprenez les expressions les plus fréquentes dans les descriptions des outils correspondants.
Cette collecte prend souvent moins d’une heure et améliore davantage la sélection que de longues séances d’ajustement du schéma.
Lorsqu’un agent ne sélectionne aucun outil et répond avec ses connaissances générales, il s’agit souvent d’un problème de vocabulaire : le texte de la tâche ne recoupe pas la description, donc l’outil reste invisible.
## Checklist d’un ensemble d’outils fiable
- [ ] Les noms suivent une convention `verbeNom` et désignent une ressource précise.
- [ ] Chaque description indique ce qui change, quand utiliser l’outil et quand ne pas l’utiliser.
- [ ] Les outils qui se chevauchent se nomment explicitement.
- [ ] Les descriptions reprennent les mots utilisés par les clients.
- [ ] Les actions destructrices ou irréversibles indiquent clairement leurs conséquences.
- [ ] Les ensembles fermés utilisent des énumérations.
- [ ] Les unités et formats figurent dans les noms ou descriptions, avec des exemples.
- [ ] Les champs requis correspondent au comportement réel de l’API.
- [ ] Les outils dépendants nomment leurs prérequis.
- [ ] Une suite de sélection s’exécute en CI contre des mocks.
Le modèle effectue une correspondance de motifs à partir du texte que vous avez écrit. Lorsqu’il se trompe, commencez par examiner la définition de l’outil avant de modifier le modèle ou l’architecture.
## Questions fréquentes
### Quelle doit être la longueur d’une description ?
Elle doit être assez longue pour lever l’ambiguïté, généralement deux à cinq phrases. Raccourcissez les descriptions des outils évidents et consacrez davantage de contexte aux outils qui se ressemblent.
### Dois-je inclure des exemples ?
Oui pour les formats et les unités : un exemple élimine une catégorie entière d’erreurs. Évitez les longs exemples d’utilisation, qui consomment du contexte sans améliorer beaucoup la sélection.
### Vaut-il mieux avoir beaucoup d’outils spécialisés ou quelques outils flexibles ?
Les outils spécialisés sont généralement sélectionnés plus fiablement, car chacun ne fait qu’une chose. Au-delà de quelques dizaines d’outils, la liste elle-même devient toutefois un problème. Filtrez-la ou utilisez une récupération dynamique, comme expliqué dans le guide sur la [génération d’outils d’agent à partir d’OpenAPI](https://apidog.com/fr/blog/openapi-spec-as-agent-tools?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation).
### Puis-je corriger la sélection dans l’invite système ?
Partiellement. C’est un palliatif raisonnable pour une ou deux confusions connues, mais cela ne s’adapte pas : l’invite est partagée entre tous les outils, tandis que la description accompagne précisément celui qui en a besoin.
### Que faire si le modèle invente toujours des valeurs ?
Contraignez le type, ajoutez une énumération et indiquez que la valeur doit provenir d’un appel antérieur plutôt que d’être construite. Si le problème persiste, validez la valeur dans le wrapper et renvoyez une erreur listant les valeurs autorisées.
### Ces règles s’appliquent-elles aux serveurs MCP ?
Oui. Un serveur MCP expose des noms, des descriptions et des schémas sous une forme similaire. Les mêmes règles de formulation s’appliquent donc. Pour comprendre le protocole, consultez ce guide sur [ce qu’est le MCP](https://apidog.com/fr/blog/what-is-mcp-model-context-protocol?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation).
Les descriptions, les mocks et les tests peuvent vivre dans un même projet. [Téléchargez Apidog](https://apidog.com/download?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation) pour gérer ces éléments depuis une définition d’API partagée.
Top comments (0)