Votre Serveur MCP a un Problème de Score Secret

Votre serveur MCP fonctionne parfaitement en démo. Vous le savez parce que c'est vous qui avez construit la démo. Vous avez choisi le prompt sur mesure, l'outil s'est déclenché, le résultat est revenu propre. Tout le monde a hoché la tête. On livre.

Puis la production arrive.

En production, le LLM choisit le mauvais outil 30% du temps. Les utilisateurs signalent des résultats étranges. L'agent appelle search quand il devrait appeler fetch. Il passe une chaîne de date là où il faut un timestamp epoch. Il ignore complètement votre outil le plus puissant parce qu'il ne sait pas quand l'utiliser.

Qu'est-ce qui a changé ? Rien dans votre code. Les handlers sont bons. La logique est bonne. Le problème a toujours été là — vous ne l'avez jamais remarqué parce que les démos sont scriptées et la production ne l'est pas. En démo, vous contrôlez l'entrée. En production, le LLM doit deviner lequel de vos quinze outils correspond à la requête ambiguë d'un utilisateur. Et il échoue à cette étape bien plus souvent que vous ne le pensez.

C'est le problème de score secret. Votre serveur n'a pas de bug. Il a un écart de qualité qui n'apparaît que lorsqu'un modèle de langage doit prendre de vraies décisions sur vos outils.

Voici ce que la plupart des développeurs MCP n'intègrent pas : le LLM ne lit jamais votre code. Il ne voit jamais la logique de vos handlers, vos règles de validation, votre gestion d'erreurs soignée. Il ne voit qu'un nom, une description et un schéma.

C'est tout. C'est l'interface complète entre votre outil et l'intelligence qui décide de l'utiliser ou non.

Si deux outils ont des descriptions similaires, le LLM devine. Il ne demande pas de clarification. Il ne signale pas l'ambiguïté. Il en choisit un et passe à la suite. Si votre description dit « chercher des documents » et qu'un autre outil dit « trouver des documents », le LLM tire essentiellement à pile ou face.

Si une description est vague, le LLM hallucine l'intention. Il comble les lacunes avec des suppositions. « Gérer les paramètres utilisateur » pourrait signifier lire, écrire, supprimer ou exporter les paramètres. Le LLM en choisira un et s'y tiendra sans prévenir personne.

La sélection d'outils est un problème de langage, pas de code. L'instinct d'ingénieur est de débugger le handler. La vraie correction est presque toujours dans le texte — les vingt mots qui décrivent ce que fait votre outil et quand l'utiliser. La plupart des équipes ne regardent jamais là parce qu'elles sont trop occupées à lire des stack traces.

Un score de qualité n'est pas un seul nombre. Si c'était le cas, il serait inutile — comme donner à un restaurant une seule note sans distinguer la cuisine du service de l'ambiance.

Un vrai score de qualité comporte six dimensions, chacune mesurable indépendamment, chacune capable de ruiner la fiabilité de votre outil à elle seule.

Clarté de description : La description explique-t-elle ce que fait l'outil, quand l'utiliser et quand ne pas l'utiliser ? Spécifie-t-elle le format de réponse ? Un score de 40 signifie « le LLM utilisera mal cet outil régulièrement ». Un score de 90 signifie « le LLM choisit presque toujours cet outil correctement ».

Complétude du schéma : Les paramètres sont-ils typés précisément ? Les champs obligatoires sont-ils vraiment obligatoires ? Les enums sont-ils utilisés quand les valeurs sont contraintes ?

Cohérence de nommage : Vos outils suivent-ils un pattern prévisible ? Si vous avez create_user et delete_user mais ensuite fetch_all_documents, l'incohérence crée une surcharge cognitive pour le modèle.

Détection de chevauchement : Combien de vos outils pourraient correspondre à la même requête ? Un chevauchement élevé est le meilleur prédicteur d'une mauvaise sélection.

Documentation des erreurs : L'outil décrit-il ce qui se passe quand ça tourne mal ?

Couverture d'exemples : Y a-t-il des exemples d'utilisation ? Les exemples valent plus que des paragraphes d'explication parce qu'ils ancrent la compréhension du LLM dans des patterns concrets.

Rendons cela concret. Voici à quoi ressemble un score de 40 versus 90 sur chaque dimension.

Clarté de description à 40 : « Cherche dans la base de données. » À 90 : « Recherche plein texte dans tous les documents indexés. Renvoie les 10 meilleurs résultats classés par pertinence. Utiliser quand l'utilisateur veut trouver des documents par contenu. Ne pas utiliser pour une recherche par ID exact — utiliser get_document à la place. »

Complétude du schéma à 40 : Un seul paramètre "query" typé string, sans contraintes. À 90 : "query" comme string non vide avec longueur max 500, plus "limit" optionnel comme entier min 1 max 100, plus "date_range" optionnel avec dates ISO 8601.

Nommage à 40 : search, getDoc, user_remove, ListAllItems. À 90 : search_documents, get_document, remove_user, list_items. Le pattern est verbe_nom, systématiquement.

Chevauchement à 40 : search_documents, find_documents et query_documents coexistent et font des choses légèrement différentes. À 90 : chaque outil a un objectif clair et distinct.

La différence est toujours la spécificité. Les outils vagues échouent. Les outils précis fonctionnent. Et l'écart entre 40 et 90 n'est généralement pas une réécriture — c'est un après-midi d'édition soignée.

La plupart des équipes débuggent la mauvaise couche. Elles voient des erreurs de sélection d'outils et foncent dans le code. Elles réécrivent les handlers pour être plus tolérants. Elles ajoutent de la logique de retry. Elles passent à un modèle plus cher. Elles construisent des couches de routage élaborées au-dessus de MCP pour compenser l'ambiguïté en dessous.

Tout ça est cher, lent, et traite le symptôme plutôt que la cause.

La vraie correction est généralement une modification de 20 mots dans une description. Changer « gère les documents » en « crée un nouveau document à partir du titre et du corps fournis. Renvoie l'ID du document. Utiliser uniquement pour créer de nouveaux documents — pour mettre à jour des documents existants, utiliser update_document. »

Cette modification a pris trente secondes. Elle élimine toute une catégorie d'erreurs de sélection. Aucun code modifié. Aucune mise à jour de modèle nécessaire.

Le scoring de qualité vous dit exactement quels 20 mots changer. Il pointe la dimension spécifique qui échoue, sur l'outil spécifique qui pose problème, avec une suggestion concrète de quoi écrire à la place. Il transforme un vague « l'IA se trompe tout le temps » en un précis « la description de votre search_documents ne mentionne pas le format de réponse, et 34% des erreurs remontent à une mauvaise interprétation des résultats par le LLM ».

C'est pour ça que la mesure compte. Pas parce que le score est précieux, mais parce qu'il convertit un problème invisible en un problème visible et réparable. Les équipes qui comprennent ça arrêtent de réécrire des handlers et commencent à réécrire des descriptions. Elles livrent des corrections en minutes au lieu de jours. Et leurs outils marchent — pas parce que le code est meilleur, mais parce que le langage l'est.