Outils et MCP

Un outil est un contrat typé entre le modèle et votre application : vous déclarez une opération et la forme de ses arguments ; le modèle décide quand l’appeler et avec quelles valeurs ; votre application exécute l’appel. Deux faits sur ce contrat organisent tout le domaine : le modèle ne voit jamais votre implémentation — seulement le schéma que vous avez écrit et les résultats que vous avez renvoyés — et ce que l’examen teste vraiment ici, c’est la qualité de votre conception d’outils, pas l’intelligence du modèle.

Une carte avant de commencer. L’examen nomme trois sous-domaines ; cette page compte plus de trois sections, et c’est voulu. Les sections 01–03 couvrent les définitions d’outils, la section 04 la boucle d’exécution, la section 05 les échecs et les approbations, la section 06 MCP, et la section 07 l’échelle de décision entre mécanismes. Tout ce qui suit — les tableaux de révision, les pièges, le quiz — est de l’aide à la révision, pas un nouveau programme. Une légende pour le balisage : la prose explique, les encadrés « À retenir pour l’examen » regroupent les faits sur lesquels portent les questions, et les pièges sont les mauvaises réponses déguisées en bonnes. Tout ce qui est étiqueté note SDK est à reconnaître seulement — l’examen vise le concept, pas le câblage.

01Quand un outil est la réponse

Le principe est simple : utilisez un outil quand le modèle doit agir, obtenir une information récente, ou répondre dans une forme que votre code peut exploiter ; passez-vous-en quand la prose seule constitue déjà la bonne réponse.

Quatre situations en justifient un : les actions avec effets de bord (envoyer, écrire, mettre à jour) ; les données fraîches ou externes que le modèle ne peut pas connaître (prix, météo, contenu d’une base de données) ; les sorties qui doivent respecter une structure garantie ; et les appels à des systèmes existants — bases de données, API internes, systèmes de fichiers. Pour le cas limite, l’heuristique de la documentation mérite d’être connue : si vous devez écrire une expression régulière pour extraire une décision du texte produit par le modèle, cette décision aurait probablement dû prendre la forme d’un appel d’outil. À l’inverse, les anti-cas — résumé, traduction, questions de culture générale — ont deux points communs : aucun effet de bord, et un modèle qui sait déjà traiter ces tâches ; dans ces cas, un aller-retour d’outil coûte plus que le travail lui-même.

02Anatomie d’une définition

Dans le tableau tools de l’API, un outil défini par l’utilisateur comporte un nom (lettres, chiffres, tirets et tirets bas, jusqu’à 128 caractères), une description en texte brut et un input_schema en JSON Schema. Autour de ce noyau, des propriétés optionnelles : des exemples d’entrées, cache_control, l’application stricte du schéma, le chargement différé pour les grands jeux d’outils, et allowed_callers, qui limite les composants autorisés à invoquer l’outil. Utilisez le schéma pour sécuriser les arguments : des enums pour borner un paramètre d’unité à celsius ou fahrenheit, required pour distinguer obligatoire et optionnel. Le modèle lit le schéma pour construire les arguments, mais il lit la description pour décider s’il doit appeler l’outil.

C’est le fait le plus exigible du domaine : la documentation qualifie la description de facteur de loin le plus important de la performance des outils, et le mécanisme explique ce classement — l’API assemble un prompt système dédié à partir de vos définitions d’outils, de la configuration des outils et de votre propre prompt système. Une description n’est donc pas une métadonnée que le modèle consulte : c’est du texte de prompt, présent à chaque tour. Une bonne description compte au moins trois ou quatre phrases et précise ce que fait l’outil, quand l’utiliser, quand ne pas l’utiliser, ce que signifie chaque paramètre — et, le point que tout le monde saute — ce que l’outil ne renvoie pas. « Récupère le cours de l’action » est le mauvais exemple type ; la réécriture nomme les bourses couvertes, la devise de la réponse, et énonce noir sur blanc qu’elle ne fournit aucune autre information sur l’entreprise. Les exemples d’entrées existent, mais ils résolvent un autre problème : les arguments complexes, imbriqués ou sensibles au format — et chaque exemple doit valider par rapport au schéma.

Quand un appel d’outil échoue en aval, renvoyez un tool_result avec le tool_use_id correspondant, is_error réglé à true, et un message sur lequel le modèle peut agir — ce qui a échoué, si et quand réessayer. Renvoyer le corps d’erreur brut comme une donnée ordinaire est la façon documentée de semer la confusion.

03Concevoir le jeu

• —Consolidez — un outil avec un paramètre action vaut mieux que create_pr, review_pr et merge_pr en trois définitions séparées : moins d’outils, plus polyvalents, offrent au modèle moins d’options voisines à départager, et la sélection s’en trouve plus fiable.
• —Utilisez des espaces de noms — github_list_prs, slack_send_message : des noms qui portent leur service, ce qui compte le plus dès que tool search entre en jeu.
• —Ne renvoyez que l’essentiel — des identifiants sémantiques stables et les champs dont le modèle a besoin pour son prochain pas, rien d’autre. Des résultats volumineux consomment le contexte en pure perte et noient le signal utile.

04La boucle et qui exécute quoi

Une question déverrouille toute cette section, et l’essentiel du domaine avec elle : où l’outil s’exécute-t-il ? L’endroit où il s’exécute détermine qui mène la boucle, qui renvoie le résultat et qui gère l’échec — réglez cela d’abord, et tout le reste suit. Les identifiants de blocs donnent la réponse d’un coup d’œil : toolu_ marque un tool_use client, srvtoolu_ un server_tool_use. Traitez ces préfixes comme des indices de diagnostic à lire, pas comme une liste à réciter par cœur.

Les outils clients mettent votre application au volant : Claude peut demander un appel, mais il ne peut pas exécuter votre code — c’est donc votre application qui mène la boucle. Quand le modèle veut un outil, la réponse se termine par stop_reason « tool_use » et un ou plusieurs blocs tool_use, chacun portant un id, le nom de l’outil et un objet input conforme à votre schéma. Vous aiguillez selon le nom, vous exécutez, puis vous répondez par un message utilisateur dont les blocs tool_result reprennent ces ids. En code, le client standard est une boucle while pilotée par stop_reason :

Les server tools inversent l’arrangement. Recherche web, fetch web, exécution de code et tool search font tourner leur propre boucle au sein de l’infrastructure d’Anthropic — une même requête peut déclencher plusieurs recherches avant qu’une réponse ne revienne. Cette réponse apparie chaque bloc server_tool_use (ids préfixés srvtoolu_) avec son résultat déjà attaché : vous ne construisez jamais de tool_result pour ces blocs, et le tour favori de l’examen sur ce terrain consiste justement à vous faire croire que vous en devez un. Le comportement à connaître par cœur est pause_turn : la boucle serveur a atteint sa limite d’itérations et le travail reste inachevé — une pause, pas un échec.

Le cas subtil est le tour mixte : Claude émet un server tool et un client tool dans le même groupe parallèle, et l’API répond aussitôt — sans exécuter le server tool — pour que vous exécutiez le vôtre d’abord. Ce tour récompense une lecture attentive : stop_reason « tool_use » et non « pause_turn » ; un bloc server_tool_use sans résultat attaché comme signe ; exactement un tool_result dû, et il est à vous.

05Quand les outils échouent, et qui approuve

La répartition des erreurs se déduit d’une seule question, déjà posée : où l’outil s’exécute-t-il ? La réponse indique qui gère l’échec — votre application pour un outil client, Anthropic pour un server tool.

Les approbations sont la réponse de l’Agent SDK à la question « cet appel doit-il s’exécuter du tout ? » — et le concept compte plus que le câblage. Enregistrez un callback can_use_tool (canUseTool en TypeScript) : ce callback se déclenche chaque fois qu’un appel n’a pas déjà été approuvé par une règle ou un mode de permission. C’est le seul endroit où vous inspectez l’entrée complète avant toute exécution : la vraie commande derrière Bash, le vrai chemin et le vrai contenu derrière Write. Renvoyez allow, éventuellement avec un updated_input qui remplace ce qui a été demandé, ou deny — l’exécution est sautée, mais Claude voit votre message et peut changer de cap.

Deux notes SDK, à reconnaître seulement : un tableau tools passé avec le callback doit inclure AskUserQuestion, et le SDK Python exige un hook PreToolUse no-op enregistré pour tenir le flux ouvert. En revanche, ceci n’est pas une note : pour les refus fermes, disallowed_tools est évalué avant que tout mode de permission ne soit consulté — « Bash(rm -rf *) » reste donc bloqué même sous bypassPermissions, tandis qu’un « Bash » nu retirerait l’outil entier de la vue du modèle, plus large que prévu.

06MCP sans mystère

MCP est une interface standardisée. L’application hôte possède la conversation et la politique ; à l’intérieur, un client par serveur ; et les serveurs sont les programmes que les gens écrivent, qui exposent des capacités via un protocole uniforme. Tout ce qui parle ce protocole — un éditeur, Claude Desktop, Claude Code, votre propre application — peut réutiliser le même serveur.

Le principe de conception que l’examen teste est l’isolation : un serveur ne voit que les requêtes qui lui parviennent — jamais la conversation, ni les autres serveurs, ni l’intérieur de l’hôte. S’il a besoin de quelque chose du côté client, il doit le demander et attendre : elicitation pour recueillir une entrée auprès de l’humain, roots pour savoir quels répertoires il peut toucher, sampling pour emprunter le modèle de l’hôte le temps d’une complétion. Une précision : sampling est déprécié depuis la révision 2026-07-28 de la spécification — reconnaissez le nom ; les nouvelles implémentations s’intègrent directement aux API de fournisseurs LLM.

Deux transports, et une règle simple pour les distinguer : une commande désigne généralement un serveur local utilisant stdio ; une URL désigne généralement un serveur distant utilisant Streamable HTTP. Côté hygiène : liez les serveurs locaux au loopback seulement ; pour les connexions distantes, validez l’en-tête Origin et authentifiez comme il faut. Dans Claude Code, l’enregistrement tient en une ligne dans chaque sens — une commande pour stdio, une URL pour HTTP.

Avant qu’une capacité soit utilisée, les deux parties la déclarent et la négocient pour la session : un client ne peut appeler des outils que si le serveur a déclaré la capacité tools, et les listes se rafraîchissent par notification quand elles changent.

Puis les trois primitives — une ligne chacune avant le détail. Un outil accomplit une action. Une ressource expose des données lisibles. Un prompt encapsule une interaction réutilisable. Ce sont trois primitives distinctes, pas trois vues d’une même chose, et un serveur peut exposer n’importe quel mélange : l’exemple de la spécification elle-même est un serveur de base de données offrant des outils de requête, une ressource de schéma et un prompt few-shot en même temps.

• —Outils — la primitive d’action du modèle : un nom, une description et un schéma d’entrée requis (un outil sans argument déclare tout de même un objet vide et fermé — {} sans rien de permis dedans) ; en option, un schéma de sortie, qui apporte dans les résultats du contenu structuré vérifiable par une machine. Les résultats portent un tableau content et un drapeau d’erreur ; un outil peut aussi signaler qu’il attend une entrée humaine avant de continuer.
• —Ressources — des données lisibles adressées par URI, que le client liste et lit, avec en option des gabarits d’URI pour des familles paramétrées. La règle de sécurité n’est pas négociable : un serveur doit valider chaque URI et assainir les chemins de fichiers, car une URI file:// forgée qui sort de son répertoire est l’attaque classique ; les URI inconnues reçoivent une erreur de protocole.
• —Prompts — des gabarits de messages nommés et réutilisables, avec arguments, remplis à la demande. La manière dont une organisation encapsule ses flux de travail pour que des humains les invoquent.

07Intégré, outil personnalisé, MCP, ou skill

Le principe est simple : utilisez ce qui est livré, n’écrivez que la logique qui vous appartient, branchez-vous sur ce qui existe déjà, et ajoutez de la connaissance — pas des outils — quand l’écart est une lacune de connaissance. Le choix dépend surtout de l’endroit où la logique s’exécute et de l’existence éventuelle d’une intégration ; l’ordre va du moins cher d’abord, parce que le mécanisme le moins cher est celui que vous n’avez pas à construire.

Un fait de câblage éclaire à la fois une bizarrerie de nommage et une façon de cadrer le débat : dans l’Agent SDK, les outils personnalisés s’enregistrent enveloppés dans un serveur MCP en processus. Retenez-le deux fois : il explique les noms d’outils préfixés mcp__, et il signifie que « outil personnalisé contre MCP » est en réalité une question sur l’endroit où la logique s’exécute — votre processus, ou le serveur de quelqu’un d’autre.

Une distinction côté API revient sans cesse dans les questions d’examen : les schémas définis par Anthropic comme bash et text_editor ressemblent à des server tools, mais ils s’exécutent de votre côté. Anthropic définit leur schéma — vous le demandez par son type daté plutôt que de définir le vôtre —, entraîne le modèle dessus, mais votre application exécute l’appel et renvoie le résultat. Seuls les vrais server tools — recherche web, fetch web, exécution de code, tool search — tournent sur l’infrastructure d’Anthropic.

08Une page pour réviser

Sept sections de prose précèdent cette ligne. Voici le même domaine en un tableau — qui exécute quoi, la question sur laquelle tourne chaque scénario — plus la liste de contrôle de la veille. Si vous ne relisez qu’une chose la veille de l’examen, relisez ceci.

La liste de contrôle de la veille. Vous devriez pouvoir énoncer chacune de ces lignes sans regarder :

• —Les cinq règles du haut de la page, à voix haute, dans l’ordre.
• —Ce que signifie chaque stop_reason — et que pause_turn veut dire inachevé, pas échoué.
• —Le tour mixte en une phrase : un server tool sans résultat plus un client tool dans le groupe → exécutez seulement le vôtre, renvoyez un tableau d’outils identique.
• —Les trois rôles MCP, le principe unique (l’isolation), et la règle de transport : commande → stdio avec stdout réservé au protocole ; URL → Streamable HTTP.
• —Outil, ressource et prompt en une ligne chacun — et le fait qu’un serveur peut exposer les trois.
• —L’échelle du moins cher d’abord — intégrés, personnalisé, MCP, skill — et le fait qu’un skill n’est pas un outil.

Un dernier tri, parce que tout ce qui précède ne mérite pas le même effort de mémorisation. À connaître parfaitement : les cinq règles, les valeurs de stop_reason et ce que votre code fait pour chacune, les trois rôles MCP, et outil / ressource / prompt en une ligne chacun. À reconnaître immédiatement : les préfixes toolu_ et srvtoolu_ (des indices de diagnostic, pas une liste à réciter), les notes SDK autour de can_use_tool, les raisons d’échec nommées de la recherche web. En simple référence : tout le reste. Ce domaine récompense le jugement — quel mécanisme, à qui revient l’échec, quelle primitive — bien plus que la mémoire.

09Les pièges de ce domaine

• —« Claude choisit le mauvais outil — ajoutez des exemples d’entrée » — la sélection est un problème de description ; les exemples corrigent les arguments complexes.
• —« Plus d’outils, plus étroits, rendent la sélection plus claire » — la documentation dit consolider : un outil, un paramètre action.
• —« Le serveur MCP peut voir toute la conversation » — l’isolation est la conception : l’hôte voit tout, le serveur ne voit que des requêtes.
• —« Les serveurs stdio peuvent imprimer sur stdout » — stdout est le canal du protocole ; les journaux vont sur stderr.
• —« bash et text_editor tournent sur les serveurs d’Anthropic » — les schémas définis par Anthropic s’exécutent pourtant dans votre application.
• —« Un skill est une sorte d’outil » — un skill ajoute de la connaissance et du flux de travail, pas une action.
• —« Après un server tool, vous devez un tool_result » — jamais : Anthropic apparie chaque server_tool_use avec son résultat ; en construire un vous-même est l’erreur.
• —« Un server_tool_use sans résultat veut dire pause_turn » — seulement si aucun client tool ne partage le groupe ; sinon, c’est un tour mixte, et vous ne devez que le résultat de votre client tool.
• —« Un outil qui lève une exception termine la boucle » — un échec d’exécution est une donnée, pas un crash : is_error true, un message actionnable, et Claude le relaie.
• —« bypassPermissions passe outre toute restriction » — les règles deny passent avant tout mode consulté ; disallowed_tools tient même là.

10Vérifiez vos acquis

Quatre questions, à peu près dans le registre de l’examen. Chacune se déplie pour montrer la réponse et — plus utile encore — pourquoi les mauvaises options sont mauvaises.