Conception d’outils et intégration MCP

Une définition d’outil est un contrat avec un client non déterministe. Le modèle ne peut pas lire votre code source, ne peut pas deviner vos intentions et ne voit pas votre documentation — tout ce qu’il sait d’un outil tient dans le nom, la description et le schéma d’entrée, livrés dans la requête API. Ce trio est l’interface entière, et les questions de ce domaine sont presque toujours « quelle partie du contrat est fausse ? » déguisée en scénario.

01L’interface : nom, description, schéma

Le nom est une adresse : verbe d’abord, spécifique, honnête sur ce qui va se passer — query_orders, pas data_lookup ; create_invoice, pas process. La description est la substance du contrat, et l’examen a une idée fixe de ce qu’elle doit contenir : ce que l’outil fait, quand l’utiliser, quand ne pas l’utiliser, et ce que signifient ses résultats. Un outil relecteur qui « vérifie si un fichier Python suit le guide de style de l’équipe » bat « relit le code », exactement comme une bonne docstring bat une docstring vague — le modèle choisit entre les outils comme un développeur choisit entre des fonctions : en lisant la doc.

Le schéma d’entrée est du JSON Schema, et sa qualité sépare l’outil qui marche de celui qui hallucine des arguments. Peu de paramètres, chacun avec un nom clair, un type déclaré, une description, et des contraintes que le schéma lui-même impose — des enums plutôt que des chaînes libres là où le domaine est fermé, required exactement là où l’exigence est réelle. Le modèle remplira la forme que vous lui donnez ; un schéma où tout est optionnel invite le modèle à deviner des valeurs qu’il aurait dû être forcé de faire émerger. Et le schéma coupe dans les deux sens : une validation stricte des entrées rejette les appels mal formés avant toute exécution, ce qui transforme « comportement mystérieusement faux » en « une erreur lisible dans la section suivante du domaine 2 ».

02Les périmètres : portée, rayon d’action, idempotence

Au-delà de la syntaxe, l’examen teste trois propriétés de périmètre d’un outil bien cadré. Le rayon d’action (blast radius) : préférez la lecture à l’écriture, l’écriture à la suppression, l’étroit au large — un outil qui lit une commande est plus sûr qu’un qui les lit toutes, et un outil qui rédige un courriel est plus sûr qu’un qui l’envoie ; la granularité que vous choisissez est une décision de sûreté, pas de confort. Réversibilité et idempotence : les opérations qui se rejouent sans mal (idempotentes) sont le mariage naturel des agents qui réessaient ; les opérations destructrices et irréversibles méritent leur propre outil, verrouillé par leur propre permission, jamais fondues dans un fourre-tout multi-usage commode. Une seule finalité : un outil, un métier. Les outils qui font « n’importe quoi avec l’API records » produisent des descriptions entre lesquelles le modèle ne peut pas choisir et des échecs que personne ne peut attribuer.

C’est aussi ici que l’interface rencontre les couches d’imposition du domaine 1 : un outil étroit est une restriction par construction. Vous ne dites pas à l’agent « ne supprime rien » en lui tendant delete_everything() avec une description polie ; vous lui donnez les outils dont l’union des capacités est exactement la tâche, et le travail du prompt devient facile parce que la conception l’a déjà fait.

03Les réponses d’erreur structurées

Un appel d’outil peut échouer ; le métier de l’architecte est de rendre l’échec utile. La règle que l’examen répète sous différents costumes : les erreurs sont faites pour être lues par le modèle, et le modèle est un lecteur de langage clair sans accès à votre pile d’exécution. Une erreur structurée dit ce qui a échoué, pourquoi, et — quand c’est possible — ce qui fonctionnerait à la place. « Date invalide : YYYY-MM-DD attendu, reçu “3 mars” » permet à l’agent de se corriger au tour suivant. Une trace de pile nue, un HTTP 500 ou une exception brute le laissent s’agiter, réessayer l’identique, se mettre à deviner — la boucle du domaine 1, qui tourne sur une entrée mal formée jusqu’à ce qu’un budget la sauve.

Pour les outils MCP précisément, la forme est fixée : un appel d’outil échoué est une réponse de protocole réussie dont la charge utile porte isError: true, avec l’explication en contenu que le modèle lit. Deux distinctions que l’examen trace nettement. Une erreur d’outil (« vos arguments étaient invalides », « l’enregistrement n’existe pas ») est une donnée — elle retourne dans la boucle comme contexte, et l’agent peut se rétablir seul. Une erreur de protocole ou de transport (le serveur n’a jamais répondu) est de l’infrastructure — c’est l’affaire de votre couche d’orchestration : nouvelle tentative avec temporisation, timeout, remontée à un humain. Fusionner les deux catégories produit le mauvais design classique : des agents qui réessaient une panne réseau comme s’ils disputaient une erreur de validation.

04Distribuer les outils entre agents — et le tool choice

Quand un coordinateur fait tourner des subagents, la distribution des outils est une décision d’architecture avec un ensemble fixe de bonnes réponses. Principe un : donnez à chaque agent le jeu d’outils que son métier implique, et rien de plus — le chercheur reçoit recherche et lecture ; l’implémenteur reçoit lecture-écriture et shell ; le relecteur reçoit la lecture seule. Chaque outil retenu est un mode d’échec supprimé. Principe deux : surveillez le compteur. Les jeux d’outils qui grossissent sans borne dégradent la qualité de sélection — le modèle se trompe parmi les quasi-doublons et rate le bon outil dans la foule ; les atténuations sont la spécialisation (répartir les jeux entre subagents pour qu’aucun contexte ne les porte tous), la consolidation (retirer les quasi-doublons) et, à l’échelle API, laisser le modèle chercher ou récupérer programmatiquement les définitions d’outils plutôt que d’expédier chaque schéma dans chaque requête. La formulation de l’examen est généralement « l’agent choisit le mauvais outil parmi beaucoup de semblables » — la réponse n’est jamais « écris un prompt système plus long » ; c’est « le jeu d’outils est le problème ».

L’autre moitié du sous-domaine est le réglage tool_choice de l’API — quatre valeurs, et l’examen les attend toutes les quatre au mot près. auto (par défaut) : le modèle décide s’il appelle un outil et lequel. any : un outil doit être appelé — le modèle choisit lequel, mais il ne peut pas répondre en prose ; utilisez-le quand un résultat structuré est obligatoire. tool, avec un nom : force cet outil précis. none : les outils sont visibles mais le modèle ne doit rien appeler. Le langage des scénarios s’y mappe directement : « le modèle répond en prose alors qu’il nous faut une note du schéma » → tool_choice any ; « toujours extraire avec notre schéma, jamais un autre outil » → tool avec le nom ; « laissons-le décider » → auto.

05MCP : serveurs, transports et portées

Model Context Protocol est le standard ouvert qui fait passer la conception d’outils de « codé à la main dans mon application » à « brancher un serveur dans n’importe quel hôte MCP ». Un serveur MCP expose des tools (fonctions que le modèle peut appeler), des resources (données qu’il peut lire) et des prompts (gabarits qu’on peut lui donner) — un seul serveur peut servir les trois. Un hôte — Claude Code, l’Agent SDK, Claude Desktop, votre propre application — se connecte aux serveurs et fusionne leurs offres dans le jeu d’outils de l’agent. Le principe de conception de l’examen est l’isolation : un serveur ne voit pas les autres serveurs, ne voit pas la conversation, ne peut pas mettre la main dans l’hôte. Si un scénario exige une coordination entre serveurs, c’est le coordinateur qui la fait — jamais les serveurs.

Les transports disent comment on atteint un serveur, et deux comptent : stdio pour les serveurs locaux (l’hôte lance un sous-processus et parle le protocole sur l’entrée-sortie standard du processus — stdout est le canal de protocole, les logs vont sur stderr) et streamable HTTP pour les serveurs distants (un point de terminaison sert beaucoup de clients, généralement avec OAuth pour l’authentification). Les indices de formulation de l’examen : « tourne sur la machine de l’utilisateur, sans réseau » → stdio ; « serveur d’équipe partagé, authentifié » → streamable HTTP. Dans Claude Code, les serveurs s’enregistrent avec claude mcp add et vivent à l’une de trois portées : local (par défaut — ce projet, cet utilisateur, non partagé), project (commité dans .mcp.json à la racine du dépôt, pour que chaque clone reçoive les mêmes serveurs) et user (disponible dans tous vos projets). Le verbe du scénario donne la portée : « toute l’équipe, de façon reproductible » → portée projet avec .mcp.json versionné.

La sécurité MCP a un autre favori de l’examen : le serveur fait confiance à ses entrées. Un serveur doit valider chaque URI de ressource et assainir les chemins de fichiers — le file:// forgé qui remonte d’un répertoire est l’illustration classique de ce qui arrive sinon. L’hôte limite ce qu’un serveur voit (isolation) ; le serveur reste responsable de ce qu’il fait de ce qu’on lui tend. Les deux moitiés sont de votre ressource de conception ; aucune n’excuse l’autre.

06Les outils intégrés, par leur nom

L’examen nomme six outils intégrés et attend une aisance dans leurs arbitrages — c’est la partie la plus « trivia » de l’examen d’architecte, et les points sont réels. Read lit des fichiers (avec offset et limit pour feuilleter les gros — la manière polie envers le contexte de regarder un grand fichier). Glob cherche des fichiers par motif de nom ; Grep cherche du contenu par motif à l’intérieur — la paire forme l’étage recherche, et la recherche ciblée bat la lecture en vrac partout où elle peut répondre à la question. Edit fait des remplacements chirurgicaux : donnez-lui une chaîne exacte à matcher et le remplacement ; le match doit être exact, espaces comprises, et un raté échoue plutôt que d’approximer — ce qui est précisément sa valeur de mutateur sûr. Write crée ou écrase un fichier entier — le mutateur large spectre ; notez la sémantique d’écrasement, parce que « Write pour le correctif chirurgical » est une mauvaise réponse que l’examen aime. Bash exécute des commandes shell avec toute leur puissance et tout leur rayon d’action, et son état de session persiste entre appels — un cd dans un appel s’applique encore au suivant — ce qui est soit un confort, soit un piège, selon qui a écrit la commande.

07Les pièges de ce domaine

• —« L’outil a échoué, donc on lance l’exception et on laisse l’appelant voir la pile. » Le modèle lit du langage clair, pas des traces de pile. isError avec un message actionnable est le contrat ; les exceptions brutes sont la maternité des boucles qui s’agitent.
• —« Un outil puissant garde le schéma simple. » Un outil fourre-tout rend chaque mauvaise action possible et aucune description honnête. Des petits outils mono-usage au rayon d’action étroit sont la réponse du sénior.
• —« Envoyer les quarante outils à chaque agent pour la flexibilité. » Les jeux surchargés dégradent la sélection. Répartissez par métier, consolidez les quasi-doublons, et gardez petit le jeu d’outils d’un contexte donné.
• —« Le modèle ignorait l’outil, donc forcer tool_choice any. » any force un appel — n’importe lequel. Si le problème était le mauvais outil choisi parmi d’autres, forcer aggrave. Réparez d’abord le jeu d’outils ou les descriptions.
• —« Les serveurs MCP se coordonnent entre eux. » Ils ne se voient pas. La coordination appartient à l’hôte ou à votre coordinateur ; une conception qui suppose un dialogue serveur-à-serveur est une conception qui échoue sur le papier.
• —« Utilisez Write — c’est plus exhaustif qu’Edit. » Write écrase tout le fichier ; un Edit qui ne matche pas échoue bruyamment au lieu de réécrire silencieusement tout. L’exhaustivité qu’on n’a pas demandée est un dégât.