Linter de schémas MCP

Pourquoi un agent appelle le mauvais outil

La description d'un outil Model Context Protocol n'est pas une documentation destinée à un humain. Elle est envoyée au modèle à chaque requête et constitue la seule chose sur laquelle il décide d'appeler cet outil ou non. Quand un agent choisit delete_branch au lieu de list_branches, ce n'est presque jamais un bug de l'agent : ce sont deux descriptions que le modèle n'a pas pu distinguer.

Collez ci-dessus l'URL de votre serveur MCP : ce linter lit chaque définition d'outil annoncée par votre serveur, exactement telle qu'un agent la reçoit, et signale ce qui rend la sélection peu fiable.

Ce qui est vérifié

• Descriptions absentes ou trop maigres — un outil décrit en trois mots ne donne au modèle aucun élément de décision.
• Descriptions qui redisent le nom — le modèle a déjà le nom. « Lister les tickets : liste les tickets » n'apporte aucun signal.
• Paramètres non documentés — les descriptions de paramètres sont ce qui indique au modèle quoi mettre dans chaque champ. Sans elles, il déduit du nom et se trompe.
• Schémas sans propriétés déclarées — un outil qui ne déclare aucune entrée acceptera ce que le modèle invente.
• Pas de tableau required — tous les paramètres semblent alors optionnels : le modèle en omet un nécessaire et reçoit une erreur.
• Descriptions assez longues pour coûter du contexte réel — envoyées à chaque tour, la verbosité est donc une charge récurrente, pas ponctuelle.

Plus long n'est pas meilleur

Cela mérite d'être dit franchement, car l'instinct se trompe généralement : le linter signale les descriptions trop longues autant que les trop courtes. Les définitions d'outils sont renvoyées à chaque requête, donc un paragraphe supplémentaire se paie à chaque tour de chaque conversation, indéfiniment, sans améliorer la justesse de la sélection. Visez une ou deux phrases précises : ce que fait l'outil, et quand le préférer à son voisin. Vous pouvez voir exactement ce que coûte votre liste actuelle avec le calculateur de tokens MCP.

Ce que contient le rapport

Un score de qualité, chaque constat avec l'outil concerné, et — là où une réécriture changerait vraiment le comportement d'un modèle — une description de remplacement suggérée. Les vérifications elles-mêmes n'utilisent aucun modèle et tournent toujours. Les réécritures suggérées, si, et un budget mensuel leur est alloué pour que l'outil reste gratuit ; s'il est épuisé, le rapport le dit franchement et tous les constats au-dessus restent valables.

Outils et guides associés

• MCP Inspector — lire les schémas complets sur lesquels la revue s'appuie.
• Calculateur de tokens MCP — ce que ces descriptions coûtent par requête.
• Scanner de sécurité MCP — les mêmes descriptions, examinées pour des instructions glissées plutôt que pour leur clarté.
• Créer un serveur MCP en Python

Une description ne peut pas servir deux lecteurs

Optimiser une description pour la sélection d'outils la rend concise, précise et tournée vers la machine — et inutile à un client qui cherche à comprendre ce que fait votre serveur. Cette tension est réelle et ne se résout pas en écrivant mieux. MCP Showcase la tranche en produisant les deux à partir du même serveur : vos schémas allégés continuent d'aller au modèle, tandis que vos prospects obtiennent un playground en direct avec une documentation lisible par outil, qu'ils peuvent réellement essayer dans leur navigateur.