Créer des outils MCP de qualité avec Arcade.dev Evals

Dans notre premier article de cette série, « Everything Is a Test », nous avons présenté Arcade.dev Evals : un framework pour tester si les LLMs peuvent sélectionner le bon outil MCP et remplir les arguments correctement, sans exécuter aucun outil. Cet article se concentre sur le côté pratique : ce qui distingue une bonne définition d’outil d’une mauvaise, et comment mesurer la différence.

Les définitions d’outils ne sont pas des signatures de fonctions

Créer des outils MCP de qualité demande une réflexion approfondie, non seulement sur leur fonctionnement interne, mais aussi sur la façon dont ils sont présentés aux LLMs pour que leur bon usage dans les bons contextes soit compris. Un ensemble de définitions bien décrites peut fortement impacter les performances de votre agent, ce qui se répercute directement sur l’expérience des utilisateurs.

En tant que développeur d’outils débutant, on pourrait naïvement traiter les outils MCP comme de simples fonctions. On ne réfléchit pas vraiment à l’importance de la façon dont on les présente aux modèles : on reprend les noms exacts de la spec OpenAPI (ils semblent assez explicites) et on saute les descriptions. Qui lit la doc, non ? Pour simplifier, on accepte aussi les enums sous forme de chaînes. Puis on fait le câblage nécessaire pour que les outils accèdent à notre API REST, et c’est plié.

Les difficultés commencent lors des tests en situation réelle. L’outil ne sera pas forcément désastreux : selon les exigences de formatage, les modèles les plus puissants (et les plus chers) peuvent souvent inférer ce qu’il faut faire avec un toolkit mal défini, mais les modèles moins chers peineront davantage. Le vrai problème surgit avec les paramètres qui nécessitent un formatage précis, comme les dates et les enums. Sans guidage clair, même les modèles compétents peuvent rater le bon format, surtout quand on utilise des chaînes pour les enums et les dates, ce qui introduit une complexité cardinale considérable.

De plus, selon votre ensemble d’outils, le modèle peut tomber dans un piège d’ambiguïté et choisir un outil qu’il croit adapté à votre besoin, faute d’une bonne description. Selon ce que fait cet outil, les conséquences peuvent être désastreuses. Sans compter que des outils mal définis entraînent une consommation de tokens plus élevée à cause des tentatives répétées.

L’analogie du menu de restaurant

Notre première erreur était de traiter les définitions d’outils MCP comme des signatures de fonctions. Ce n’en sont pas. Elles ressemblent davantage aux entrées d’un menu de restaurant : vous présentez les options à un LLM, et selon le contexte, il choisit la plus appropriée et la paramètre. Le serveur transmet ensuite la commande en cuisine et vous la rapporte.

Si le menu ne propose que des noms génériques sans explication, impossible de savoir ce que vous obtiendrez si vous voulez tenter quelque chose de nouveau. Quand le plat arrive et qu’il ne vous convient pas, vous pouvez commander à nouveau, mais le même problème peut se répéter indéfiniment jusqu’à ce que vous abandonniez. Dans le pire des cas, vous pourriez recevoir un plat contenant des ingrédients auxquels vous êtes allergique, avec des effets secondaires potentiellement irréparables pour votre santé.

À quoi ressemble un bon outil

Le premier changement logique consiste à mettre à jour les noms d’outils pour que l’intention soit plus claire, même quand seul le nom est disponible. Cela aide à la fois les LLMs et les humains qui gèrent leurs propres toolsets. On ajoute aussi une description qui capture l’objectif de l’outil et ses contraintes essentielles, sans être verbeux.

Le changement suivant s’applique à chaque paramètre. Il faut décrire les formats requis, les valeurs par défaut et les valeurs acceptées (y compris les options d’enum). C’est extrêmement important et augmentera considérablement le taux de succès des appels d’outils.

# BEFORE: Vague tool definition
{
    "name": "schedule",  # Generic name
    # No description!
    "inputSchema": {
        "properties": {
            "when": {"type": "string"},      # What format?
            "type": {"type": "string"},      # What are the options?
            "location": {"type": "string"},  # Zoom? Address? URL?
        }
    }
}

# AFTER: Descriptive tool definition
{
    "name": "create_meeting",
    "description": "Schedule a video meeting with ISO formats and one attendee.",
    "inputSchema": {
        "properties": {
            "datetime": {
                "type": "string",
                "description": "ISO 8601 datetime (YYYY-MM-DDTHH:MM)"
            },
            "meeting_type": {
                "type": "string",
                "description": "Meeting type: demo | review | planning | 1:1"
            },
            "platform": {
                "type": "string",
                "description": "Video platform",
                "enum": ["Zoom", "Google Meet", "Teams"]
            }
        }
    }
}

Mesurer la différence

Nous avons fait passer les deux versions dans Arcade Evals avec les mêmes cas de test sur plusieurs modèles. Les résultats ont été constants : le toolkit vague n’a pas atteint le seuil de 90 % sur les cas de planification de réunions pour chaque modèle testé. Le toolkit descriptif a passé les tests sans exception.

La principale cause d’échec ? L’absence de guidage sur le formatage (datetime et durée ISO) et le mapping enum/liste. Quand vous ne dites pas au modèle que « when » doit être « 2026-02-04T14:00 », il devine. Parfois il se trompe.

Sachant cela, nous avons construit un framework d’evalsaxé sur le scoring de correspondance d’outils, qui vous permet de tester si un LLM peut sélectionner le bon outil et remplir les arguments correctement, en utilisant uniquement des définitions d’outils et des prompts. Aucune exécution d’outil n’est requise.

Une checklist rapide pour des schémas d’outils MCP de qualité

À garder en tête lors de la création d’outils MCP :

• Les noms d’outils communiquent l’intention : préférez verbe + objet (create_meeting , send_email ) plutôt que des verbes génériques (schedule , notify ).
• Les descriptions énoncent les contraintes : une phrase qui explique ce que fait l’outil et ce qu’il ne fait pas.
• Les paramètres sont compréhensibles par le modèle : les noms correspondent au langage utilisateur ; les descriptions incluent formats et exemples.
• Les ensembles fermés sont des enums : si la valeur doit être l’une des N options, listez-les.
• Les formats sont explicites : datetime/durée ISO, IDs, règles de parsing d’URL, règles d’ordonnancement.
• Évitez les « exigences cachées » : si un outil nécessite une identité, une sélection ou un contexte, faites-en un paramètre d’entrée ou fournissez ce contexte.

Démarrer avec Arcade Evals

Prêt à tester vos outils MCP avant qu’ils arrivent en production ? Arcade Evals est intégré dans l’Arcade CLI.

pip install 'arcade-mcp[evals]'
arcade evals .

Pour la documentation complète, consultez le guide Arcade Evals.

Envie d’aller plus loin ? Nous avons exécuté ces evals sur 14 modèles avec 3 passes chacun, dont une évaluation complète du Figma MCP Server. Lire le rapport ou le tester vous-même.