Tool call failed: invalid parameters — un message aussi laconique que frustrant, apparu dans les journaux d’un agent HubSpot censé pouvoir créer des tickets de support directement depuis les commentaires d’un site WordPress. L’outil fonctionnait dans les tests manuels, mais échouait systématiquement dès que l’agent tentait de l’appeler lui-même dans une conversation réelle.
Le serveur MCP en question exposait plusieurs outils construits avec le plugin MCP Adapter pour WordPress, dont un outil creer_ticket_support censé transmettre à HubSpot le contenu d’un commentaire signalé comme problématique, avec la priorité déduite par l’agent. Rien dans les journaux WordPress ne laissait deviner d’où venait le blocage.
Symptôme : un échec silencieux, sans trace utile
Côté HubSpot, l’agent renvoyait simplement qu’il n’avait pas pu utiliser l’outil, sans détail. Côté WordPress, aucune entrée d’erreur n’apparaissait dans les journaux du serveur MCP, ce qui a fait perdre un temps précieux : l’équipe a d’abord soupçonné un problème d’authentification, puis un souci de droits utilisateur, avant de comprendre que le problème se situait plus en amont, au niveau du contrat d’interface lui-même.
Diagnostic : un schéma qui ment sur ce qu’il attend
En inspectant directement la réponse de découverte des outils (tools/list dans le protocole MCP), le schéma JSON déclaré pour l’outil creer_ticket_support a révélé le problème : le paramètre priorite était bien listé, mais sans type déclaré (ni string, ni enum), ce qui rendait le schéma techniquement invalide au regard de la spécification JSON Schema attendue par le client MCP côté HubSpot.
// Schéma fautif, tel qu'exposé par le serveur
{
"name": "creer_ticket_support",
"inputSchema": {
"type": "object",
"properties": {
"sujet": { "type": "string" },
"priorite": {}
},
"required": ["sujet", "priorite"]
}
}
Un champ obligatoire (required) sans type déclaré ni valeurs possibles ne permettait pas au client MCP de savoir quoi générer pour ce paramètre. Certains clients tolèrent ce genre d’imprécision et devinent une chaîne de caractères par défaut ; le client utilisé par HubSpot, plus strict, rejetait purement et simplement l’appel avant même de le transmettre, sans remonter d’erreur explicite jusqu’au serveur WordPress.
Correctif : un schéma complet et validé
La correction consistait à déclarer précisément un type enum pour le champ priorite, limitant les valeurs possibles à celles réellement gérées côté HubSpot :
{
"name": "creer_ticket_support",
"inputSchema": {
"type": "object",
"properties": {
"sujet": { "type": "string" },
"priorite": {
"type": "string",
"enum": ["basse", "normale", "haute", "urgente"]
}
},
"required": ["sujet", "priorite"]
}
}
Après ce correctif, l’agent a immédiatement pu utiliser l’outil sans nouvel échec, avec en prime un bénéfice inattendu : en connaissant les valeurs possibles pour la priorité, l’agent a commencé à les choisir plus judicieusement, plutôt que d’inventer des libellés proches mais non reconnus.
Prévention : valider le schéma avant de le publier
Pour éviter qu’une régression similaire ne se reproduise sur un autre outil du même serveur, un test automatisé a été ajouté à la suite de vérifications du projet, exécutant une validation JSON Schema stricte sur chaque schéma exposé avant tout déploiement :
- Chaque paramètre déclaré
requireddoit avoir un type explicite - Les champs à choix limité doivent utiliser
enumplutôt qu’une chaîne libre - Le test tourne dans la même suite que les tests unitaires PHP existants, avant chaque déploiement
Un schéma MCP incomplet ne provoque pas toujours une erreur bruyante : parfois, il provoque simplement un agent qui n’essaie jamais d’utiliser l’outil.
En résumé
Ce genre de panne est particulièrement piégeuse parce qu’elle ne ressemble à rien de familier : pas d’erreur HTTP classique, pas de message d’authentification, juste un outil que l’agent n’utilise jamais ou dont l’appel échoue sans explication. La leçon à retenir dépasse ce seul cas : tout schéma d’outil MCP mérite d’être validé programmatiquement, exactement comme on validerait un schéma de base de données, plutôt que de se fier à des tests manuels ponctuels qui ne couvrent jamais tous les clients MCP existants.
