Conception de Schéma d'Outils : Guider les Agents IA vers le Bon Point de Terminaison

Vous avez donné deux outils à l'agent : updateUser et deactivateUser. Un ticket de support indique « fermer ce compte ». L'agent a appelé deactivateUser. La semaine dernière, un ticket presque identique l'avait amené à appeler updateUser avec status: "closed", ce que votre API avait accepté et qui signifiait quelque chose de légèrement différent en aval.

Rien n'était cassé. Le modèle choisissait entre deux options plausibles dont les descriptions ne lui indiquaient pas laquelle s'appliquait. La sélection d'outils est le mode de défaillance que les gens attribuent au modèle et qu'ils corrigent dans le schéma, car le schéma est la seule chose sur laquelle le modèle peut se baser.

Ce guide explique ce que le modèle lit réellement lorsqu'il choisit un outil, comment rédiger des noms et des descriptions qui discriminent, comment la conception des paramètres modifie le taux d'erreur, et comment tester la sélection afin qu'un changement de formulation ne la brise pas silencieusement. Une fois que vos outils sont générés à partir d'une spécification, comme dans notre guide sur la transformation d'une spécification OpenAPI en outils d'agent, cela devient une question de ce qui entre dans cette spécification.

Apidog est l'endroit où résident les descriptions si vos outils proviennent de votre définition d'API, donc améliorer l'un améliore les documents et les outils ensemble.

Ce que le modèle voit

Au moment de choisir, le modèle dispose de la conversation, de l'invite système et d'une liste de définitions d'outils. Chaque définition comprend un nom, une description et un schéma de paramètres. Il n'a pas votre documentation d'API, vos commentaires de code ou la connaissance tribale que updateUser est obsolète.

Cela signifie que toute désambiguïsation doit être écrite dans la définition elle-même. Le guide d'appel de fonctions OpenAI et la documentation d'utilisation d'outils Anthropic soulignent le même point : la description est le texte le plus important de toute la définition, et elle doit être verbeuse plutôt que concise.

Les erreurs de sélection se présentent sous quatre formes, et chacune a une solution différente.

Le modèle choisit un outil similaire lorsque deux définitions se chevauchent. Corrigez les descriptions pour que chacune indique quand ne pas l'utiliser. Le modèle ne choisit rien et répond de mémoire lorsqu'aucune description ne correspond au langage de la tâche. Corrigez en utilisant les mots que vos utilisateurs emploient. Le modèle choisit le bon outil avec de mauvais arguments lorsque les paramètres sont ambigus. Corrigez avec des types, des énumérations et des unités. Le modèle enchaîne mal les outils lorsque l'ordre compte et que rien ne l'indique. Corrigez en indiquant le prérequis dans la description.

Nommez les outils en fonction de ce qu'ils font

Les noms véhiculent plus de signal que leur longueur ne le suggère, car le modèle les lit en premier.

Utilisez le format verbeNom, dans le même style pour l'ensemble des outils : createOrder, refundOrder, getOrderStatus. La cohérence est aussi importante que le choix individuel, car un ensemble qui mélange order_create, getOrder et refund rend chaque nom légèrement plus difficile à lire.

Soyez précis sur l'objet. search est un mauvais nom d'outil. searchCustomersByEmail en est un bon, et il indique au modèle à la fois ce qu'il recherche et comment.

Évitez le jargon interne. Si votre API appelle un client une « entité » et un abonnement un « instrument », le modèle ne fera pas le lien avec un ticket qui dit « client » et « plan ». Nommez les outils dans le langage de la tâche, pas dans le langage du schéma.

Ne réutilisez jamais un nom dans des contextes différents. Deux outils appelés list dans des espaces de noms différents tombent dans l'ambiguïté dès qu'ils apparaissent dans une même liste.

Rédigez des descriptions discriminantes

Une description utile répond à quatre questions : ce qu'elle fait, ce qu'elle change, quand l'utiliser et quand ne pas l'utiliser.

Voici une paire faible :

{ "name": "updateUser", "description": "Mets à jour un utilisateur." }
{ "name": "deactivateUser", "description": "Désactive un utilisateur." }

Et une paire qui sépare réellement :

{
  "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."
}

Quatre techniques sont à l'œuvre ici.

Nommez le jumeau. « Utilisez deactivateUser à la place » résout l'ambiguïté directement, au moment précis où le modèle les compare.

Incluez le vocabulaire de l'utilisateur. Les mots « fermer », « annuler », « suspendre » et « mettre en pause » apparaissent parce que ce sont les mots qui se retrouvent dans les tickets. C'est la modification avec le rendement le plus élevé que vous puissiez faire, et elle est presque gratuite.

Dites ce qu'il ne fait pas. Les déclarations négatives sont plus discriminantes que les déclarations positives, car les affirmations positives de deux outils voisins ont tendance à se ressembler.

Signalez la réversibilité. Le modèle raisonne sur le risque lorsque vous lui dites qu'il y a un risque. Cela s'associe aux modèles d'application de notre article sur les garde-fous des agents IA, où réside la véritable protection.

La longueur n'est pas un problème. Une description de cent mots qui empêche un appel erroné à un point de terminaison destructeur est bon marché.

Concevez des paramètres de manière à rendre les arguments erronés difficiles

Une fois le bon outil choisi, les arguments sont le prochain point où les choses tournent mal.

Le schéma JSON vous offre la plupart des contraintes dont vous avez besoin ici, et le vocabulaire de validation du schéma JSON vaut la peine d'être parcouru pour les mots-clés que votre API d'appel d'outils prend en charge.

Utilisez des énumérations partout où l'ensemble est fermé. Un paramètre status de type chaîne de caractères invite à l'invention. Typé comme une énumération, il contraint le modèle aux valeurs acceptées par votre API.

"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 le nom. amount est ambigu et les modèles devineront les dollars ou les cents de manière incohérente. amount_cents ne l'est jamais. Il en va de même pour timeout_seconds, distance_meters et duration_ms.

Donnez un exemple pour les formats de date. "description": "Date de début au format ISO 8601, par exemple 2026-08-26" produit des dates correctement formatées bien plus souvent que "date de début" seule.

Gardez les listes requises honnêtes. Tout marquer comme facultatif reporte les échecs à l'exécution ; marquer comme requis des éléments que l'API gère par défaut de manière sensée fait inventer des valeurs au modèle. Les deux sont courants, et les deux apparaissent comme des erreurs de validation couvertes par notre article sur la conception des messages d'erreur d'API pour les agents IA.

Préférez plat à imbriqué. Un modèle remplissant {"customer": {"address": {"postal_code": "..."}}} commet des erreurs structurelles qu'il ne ferait pas sur customer_postal_code. Aplatissez à la limite de l'outil et réassemblez dans votre exécuteur.

Divisez les outils surchargés. Un outil avec un paramètre mode qui change la signification de tous les autres champs est en réalité deux outils. Le diviser améliore la sélection et simplifie les deux schémas.

Indiquer les prérequis et l'ordre

Le travail en plusieurs étapes échoue lorsque le modèle ne connaît pas la séquence. Dites-le dans la description de l'outil dépendant :

{
  "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é."
}

Deux lignes, et le problème d'ordre est géré là où le modèle est déjà en train de lire. Cela vaut pour toute la catégorie : créer avant de mettre à jour, télécharger avant de traiter, autoriser avant de capturer. Si la description d'une étape dépendante ne nomme pas l'étape précédente, attendez-vous à ce que le modèle la saute. Lorsque la séquence s'étend sur plusieurs agents plutôt que sur plusieurs appels, les règles de transfert de notre article sur le passage de contexte entre sous-agents s'appliquent.

Testez la sélection comme tout autre comportement

Les descriptions sont du code, et elles régressent. Quelqu'un en raccourcit une pour s'adapter à un guide de style et l'agent commence à choisir le mauvais point de terminaison le mardi suivant.

Construisez une petite suite de sélection. Vingt à cinquante invites, chacune avec l'outil que vous attendez. Exécutez-les, enregistrez l'outil que le modèle choisit, et n'affirmez que le nom. Les arguments varient d'une exécution à l'autre ; le choix ne devrait pas. C'est la forme pratique de l'approche de notre guide sur le test d'agents non déterministes.

Amorcez-le avec les cas les plus susceptibles de se rompre :

• Les deux outils les plus similaires de votre ensemble, avec des invites qui devraient se diriger vers chacun d'eux.
• Des invites utilisant le vocabulaire client plutôt que le vocabulaire API.
• Une invite qui ne devrait correspondre à rien, où le comportement correct est de demander plutôt que de forcer un appel.
• Un outil destructeur, où un mauvais choix a un coût réel.

Exécutez chaque invite plusieurs fois. Un outil qui gagne quatre fois sur cinq est un coup de dés en production et sa description nécessite du travail.

Dirigez les exécutions vers des mocks afin qu'un test de sélection ne touche jamais de données en direct. Notre article sur l'exécution d'agents contre des mocks plutôt qu'en production couvre la configuration, et Apidog peut servir ces mocks à partir de la même définition à partir de laquelle vos outils ont été générés, ce qui maintient le schéma et le comportement alignés.

Trois ensembles qui tournent mal de la même manière

L'ensemble CRUD. Une API expose getUser, listUsers, searchUsers et queryUsers, tous générés à partir de points de terminaison qui ont évolué au fil des ans. Pour un modèle, ce sont quatre noms pour une seule idée. La solution n'est pas de meilleures descriptions pour les quatre ; c'est d'exposer l'un d'eux à l'agent et de laisser les autres en dehors de la liste des outils. Un ensemble organisé l'emporte toujours sur un ensemble complet.

L'ensemble d'administration. Les outils de lecture et les outils destructeurs se côtoient avec le même ton : getInvoice, voidInvoice, deleteInvoice. Rien dans le texte n'indique que deux de ceux-ci mettent fin à des carrières. Ajoutez la conséquence à la description, marquez-les pour approbation et maintenez l'application dans l'exécuteur plutôt que de faire confiance à la formulation. L'approche en couches est expliquée dans notre article sur l'empêchement des agents IA de détruire vos API.

L'ensemble hérité. Deux points de terminaison font le même travail, l'un étant déprécié. La spécification liste toujours les deux, donc le générateur émet les deux, et l'agent choisit l'ancien environ la moitié du temps. Soit vous supprimez l'opération dépréciée des outils générés, soit vous commencez sa description par les mots « Déprécié. Utilisez createOrderV2 à la place. » Les modèles respectent cette ligne lorsqu'elle est en premier, et l'ignorent lorsqu'elle est enfouie à la fin.

Les descriptions sont une configuration partagée

Une fois que vous acceptez que les descriptions d'outils déterminent le comportement, la question suivante est de savoir qui en est propriétaire. Dans la plupart des équipes, la réponse est accidentelle : celui qui a configuré l'agent en premier, dans un fichier sur sa machine.

Traitez plutôt l'ensemble d'outils comme un artefact partagé, revu comme toute autre interface. Les plateformes conçues autour du travail d'agent modélisent souvent cela directement. Un agent Sharkly est une configuration sauvegardée couvrant les instructions, le runtime, les compétences et les dépôts, et le partager dans un Espace rend la configuration de travail d'une personne réutilisable par l'équipe. La valeur n'est pas le stockage. C'est qu'un changement de description devient une modification révisable affectant tout le monde, plutôt qu'un ajustement local silencieux qui fait que l'agent d'un développeur se comporte différemment des autres.

Observez les mots qu'apportent les utilisateurs

L'écart le plus courant est le vocabulaire. Votre API dit abonnement, vos clients disent plan, adhésion et facturation. Votre API dit désactiver, ils disent annuler, fermer et éteindre.

Recueillez le langage réel. Tirez les phrases les plus fréquentes des tickets de support, des journaux de recherche ou des transcriptions d'exécutions d'agents ayant échoué, puis intégrez-les dans les descriptions des outils qu'ils auraient dû correspondre. Cela coûte une heure et améliore généralement la précision de la sélection plus que n'importe quelle quantité d'ajustement de schéma.

Gardez également un œil sur les échecs. Lorsqu'un agent ne choisit rien et répond à partir de ses propres connaissances, c'est une erreur de vocabulaire, pas une erreur de raisonnement. Le langage de la tâche n'a jamais recoupé le texte de l'outil, donc l'outil était invisible.

Une liste de contrôle pour un ensemble d'outils

• Les noms suivent une convention verbeNom et désignent un objet spécifique.
• Chaque description indique ce qui change, quand l'utiliser et quand ne pas l'utiliser.
• Les outils qui se chevauchent se nomment explicitement mutuellement.
• Les descriptions incluent les mots réellement utilisés par les utilisateurs, et pas seulement les termes internes.
• Les actions destructrices et irréversibles le mentionnent dans la description.
• Des énumérations sont déclarées pour chaque ensemble fermé.
• Les unités et les formats sont dans les noms ou les descriptions des paramètres, avec des exemples.
• Les listes requises correspondent à ce que l'API applique réellement.
• Les outils dépendants nomment leur 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, le texte est le premier endroit où regarder, et généralement le seul endroit que vous devez modifier. Téléchargez Apidog si vous souhaitez les descriptions, les mocks et les tests dans un seul projet.

Questions fréquemment posées

Quelle doit être la longueur d'une description d'outil ? Assez longue pour lever toute ambiguïté, ce qui représente généralement deux à cinq phrases. Les descriptions occupent du contexte, alors raccourcissez celles des outils non ambigus et consacrez cet espace aux outils qui se côtoient.

Dois-je inclure des exemples dans la description ? Oui pour les formats et les unités, où un exemple élimine toute une catégorie d'erreurs. Évitez les longs exemples d'utilisation, car ils coûtent en contexte et modifient rarement la sélection.

Est-il préférable d'avoir de nombreux outils étroits ou quelques outils flexibles ? Des outils étroits, jusqu'à un certain point. Chacun sélectionne de manière plus fiable car il ne fait qu'une chose. Au-delà de quelques dizaines, la liste elle-même devient le problème et vous filtrez ou récupérez, comme expliqué dans notre article sur la génération d'outils d'agent à partir d'OpenAPI.

Puis-je corriger la sélection dans l'invite système à la place ? Partiellement, et c'est un palliatif raisonnable pour une ou deux confusions connues. Cela ne s'adapte pas, car l'invite est partagée entre tous les outils tandis que la description voyage avec l'outil qui en a besoin.

Que se passe-t-il si le modèle continue d'inventer des valeurs de paramètres ? Contraignez le type, ajoutez une énumération et indiquez dans la description que la valeur doit provenir d'un appel antérieur plutôt que d'être construite. Si cela se produit toujours, validez dans le wrapper et renvoyez une erreur nommant les valeurs autorisées.

Ces règles s'appliquent-elles également aux serveurs MCP ? Oui. Un serveur MCP expose les noms, les descriptions et les schémas sous la même forme, les mêmes règles de formulation s'appliquent donc. Notre explication sur ce qu'est le MCP couvre le protocole lui-même.