Deux outils, lister_commandes et lister_commandes_recentes, exposés par une même extension WooCommerce connectée à un serveur MCP interne : le second avait été ajouté six mois après le premier, pour répondre à un besoin ponctuel de filtrage sur les sept derniers jours, sans jamais retirer ni fusionner l’outil existant.
Cette situation, banale en apparence, illustre un antipattern fréquent dans la conception d’outils MCP au fil du temps : la duplication progressive d’outils aux effets proches, qui complique le choix d’un agent sans que personne ne l’ait décidé délibérément. Ce texte ne traite pas de la rédaction des descriptions elles-mêmes, déjà abordée ailleurs sur ce blog dans un contexte différent, mais de la duplication d’outils en tant que telle et de sa correction.
Comment cette duplication apparaît en pratique
Aucune des deux personnes ayant ajouté ces deux outils, à six mois d’intervalle, n’avait connaissance précise du périmètre de l’autre. La première avait conçu lister_commandes pour un usage général, sans paramètre de filtrage temporel. La seconde, confrontée à un besoin précis de suivi hebdomadaire, a jugé plus rapide de créer un nouvel outil dédié que de modifier le premier, par prudence face à un code qu’elle connaissait moins bien.
Le symptôme observé côté agent
Face à une demande de type « montre-moi les commandes récentes », l’agent choisissait tantôt l’un, tantôt l’autre outil, sans logique apparente d’un appel à l’autre. Aucun des deux choix n’était réellement incorrect en soi, ce qui rendait le problème plus difficile à formuler clairement au départ qu’une simple erreur de sélection d’outil : les deux réponses obtenues restaient globalement cohérentes, mais avec des périmètres de données légèrement différents d’un appel à l’autre pour une même formulation.
Pourquoi ce n’est pas un problème de description
Améliorer les descriptions des deux outils, dans un premier temps, n’a pas réglé le problème : même parfaitement décrits, deux outils dont les périmètres se recoupent partiellement laissent au modèle une marge d’interprétation qu’aucune description, aussi précise soit-elle, ne peut totalement éliminer. La vraie correction ne pouvait venir que d’une réduction du nombre d’outils disponibles, pas d’un simple ajustement de leur formulation.
La fusion retenue
Les deux outils ont été fusionnés en un seul, lister_commandes, avec un paramètre optionnel de filtrage temporel plutôt qu’un outil séparé pour ce cas d’usage.
server.tool(
'lister_commandes',
{
periode_jours: z.number().min(1).max(90).optional()
.describe('Filtre optionnel : ne renvoie que les commandes des N derniers jours. Omis, renvoie toutes les commandes.'),
limite: z.number().min(1).max(50).default(20),
},
async ( { periode_jours, limite } ) => {
const commandes = periode_jours
? await depot.commandesDepuis( periode_jours, limite )
: await depot.commandesRecentes( limite );
return { content: [ { type: 'text', text: JSON.stringify( commandes ) } ] };
}
);Ce que cette fusion a changé pour l’agent
Avec un seul outil disponible pour cette famille de besoins, l’agent n’a plus eu à choisir entre deux options concurrentes : il ne restait qu’à décider si le paramètre de filtrage temporel devait être renseigné ou non, une décision bien plus simple à formuler correctement à partir d’une demande en langage naturel qu’un choix entre deux outils au nom proche.
- Deux outils qui répondent à des variantes proches d’un même besoin devraient presque toujours être un seul outil paramétrable.
- Une description plus précise ne corrige pas un problème de duplication, elle ne fait que le déplacer.
- Avant d’ajouter un nouvel outil, vérifier systématiquement si un outil existant ne peut pas simplement recevoir un paramètre supplémentaire.
Deux outils qui se recoupent partiellement ne doublent pas les options disponibles pour un agent : ils doublent surtout ses occasions de se tromper.
Une revue devenue périodique
Depuis cet incident, une revue trimestrielle de l’ensemble des outils MCP exposés par cette extension cherche spécifiquement les paires d’outils dont les descriptions se recoupent partiellement, en s’appuyant sur un tableau simple listant chaque outil, son verbe d’action principal et le type d’objet manipulé. Deux outils partageant le même verbe et le même type d’objet déclenchent systématiquement une vérification de fusion possible.
En résumé
La duplication d’outils MCP aux effets proches apparaît rarement par décision délibérée : elle s’accumule progressivement, au fil des ajouts successifs de personnes différentes, sans vue d’ensemble du périmètre existant. Fusionner ces outils en un seul, paramétrable, plutôt que de tenter de préciser indéfiniment leurs descriptions respectives, reste la correction la plus fiable observée en pratique.
