Collisions entre noms d'outils MCP et comportement plus sûr des agents

Un agent ne lit pas un catalogue d'outils MCP comme un ingénieur attentif lit un SDK. Il passe d'une instruction condensée à l'action la plus probable. Si vous lui donnez get_user, get_users, user_lookup et admin_get_user, puis comptez sur un paragraphe de réserves pour les distinguer, vous avez conçu un jeu de devinettes autour des autorisations.

Les collisions entre noms d'outils MCP ne sont pas seulement des identifiants en double qui font rejeter un catalogue par un client. La collision la plus grave est sémantique : deux actions appelables semblent interchangeables, mais l'une atteint un système plus vaste, utilise un identifiant plus puissant ou modifie l'état. J'ai vu des équipes parler d'un problème de prompt après qu'un agent a choisi la mauvaise action. La plupart du temps, c'est un problème d'interface qu'elles ont elles-mêmes livré.

La solution n'est ni une taxonomie gigantesque ni un comité de nommage cérémonieux. Donnez à chaque action un nom qui indique ce qu'elle fait, où elle agit et jusqu'où s'étendent ses autorisations. Rédigez ensuite des descriptions qui définissent la limite que le nom ne peut pas porter. Rendez l'ambiguïté visible dans les tests avant qu'elle ne devienne une fiche d'approbation, un appel d'API inattendu ou un incident difficile à analyser.

Une collision est d'abord sémantique, avant d'être syntaxique

Une collision syntaxique se produit lorsque deux serveurs MCP publient tous deux un outil appelé search. Selon le client, une entrée peut en écraser une autre, un espace de noms peut être imposé ou le catalogue peut devenir déroutant. Vous devez corriger ce problème, car le comportement peut varier d'un client à l'autre.

Une collision sémantique persiste même lorsque chaque identifiant est techniquement unique. Prenez ces outils :

search_customer
search_customer_records
lookup_customer
customer_admin_search

Les quatre noms peuvent sembler valides pour un compilateur et compréhensibles pour l'équipe qui les a créés. Pour un agent à qui l'on demande « Trouve la fiche client de Maya Chen et mets son adresse à jour », ils donnent de faibles indications de routage. L'agent doit deviner quel système fait foi, si l'action est en lecture seule, si elle peut parcourir tout un environnement client et si un identifiant d'administration est acceptable.

Les schémas d'outils ne rattrapent pas un catalogue vague. Un modèle peut examiner les noms des arguments, mais des schémas similaires aggravent souvent l'ambiguïté. Une recherche en lecture seule dans un annuaire et une recherche dans un CRM de production peuvent toutes deux accepter query, limit et organization_id. Le fait que l'une renvoie des données tandis que l'autre peut déclencher un enrichissement ou écrire un événement d'audit peut n'apparaître que dans une description que le modèle évalue moins fortement que la correspondance apparente avec la demande.

Considérez ces problèmes comme des défauts différents :

• Collision d'identifiants : le client ne peut pas présenter deux outils de manière cohérente.
• Collision d'intentions : deux outils semblent répondre à la même demande utilisateur.
• Collision d'autorité : un identifiant étendu se trouve derrière un outil dont le nom évoque une action limitée.
• Collision d'environnement : des libellés similaires masquent des comptes, des régions ou des environnements de production différents.

Les trois derniers provoquent les erreurs coûteuses. Un client peut rejeter des noms en double. Il ne peut pas vous signaler de manière fiable que sync_contact signifie « modifier une fiche CRM de production avec un jeton valable pour toute l'organisation », tandis que update_contact signifie « écrire dans un jeu de données de test local ».

Les noms des outils doivent porter les informations de routage

Un nom utile fournit à l'agent les informations nécessaires pour choisir avant qu'il ne lise une longue description. Pour les actions qui touchent des systèmes externes, j'utilise cet ordre : système cible, objet, verbe, puis portée lorsque celle-ci change l'autorité ou les conséquences.

crm_contact_update vaut mieux que update_contact, car il identifie le système. crm_production_contact_update peut être encore préférable si le même catalogue contient un bac à sable. github_org_member_remove est plus clair que manage_member, car il indique quelle ressource est modifiée et que le résultat est une suppression.

N'encombrez pas le nom de chaque détail d'implémentation. Les agents n'ont pas besoin de crm_v3_contacts_patch_with_bearer_auth. Ils ont besoin des distinctions qui changent la sélection. La gestion des versions, le transport et l'authentification appartiennent généralement à l'implémentation ou à la description du serveur. Le compte, l'environnement, l'effet secondaire et la limite de privilèges appartiennent souvent au nom.

Un modèle pratique ressemble à ceci :

<system>_<object>_<verb>[_<scope>]

Exemples :

billing_invoice_get
billing_invoice_send_customer
billing_production_refund_create
source_control_repo_issue_list
source_control_org_member_remove
warehouse_inventory_adjust
warehouse_inventory_adjust_dry_run

Ce modèle n'est pas sacré. Ce qui compte, c'est que les noms voisins diffèrent au point où leur effet diffère. Si billing_invoice_send_customer et billing_invoice_preview_email sont côte à côte, les verbes et les objets indiquent au modèle lequel contacte réellement une personne. Si la seule différence apparaît dans un paramètre booléen enfoui dans un schéma, le catalogue exige trop du routage.

Évitez les verbes vagues comme process, manage, handle, run, execute, sync et apply, sauf si l'objet rend lui-même l'effet parfaitement clair. Ils sont populaires parce que les équipes produit les utilisent comme des termes génériques pour plusieurs opérations. C'est précisément ce qui en fait de mauvais noms d'outils. Un modèle interprète un terme générique comme l'autorisation de choisir l'interprétation la plus large qui permet de répondre à la demande.

Les descriptions définissent la limite, pas le discours marketing

La spécification des outils du Model Context Protocol définit un outil avec un nom, une description et un schéma d'entrée. C'est un contrat d'interface, pas un emplacement pour du texte marketing. La description doit répondre à quatre questions opérationnelles : quelle action se produit, quelle cible externe la reçoit, quelle portée s'applique et ce que l'outil refuse de faire.

Comparez ces deux descriptions :

{
  "name": "crm_contact_update",
  "description": "Updates customer contact information in the CRM.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "contact_id": {"type": "string"},
      "address": {"type": "string"}
    },
    "required": ["contact_id"]
  }
}

{
  "name": "crm_production_contact_update",
  "description": "Changes address, phone, or email fields for one existing contact in the production CRM. This writes immediately. Use crm_contact_search first when the caller supplies a name rather than a contact ID. It cannot create contacts, merge records, or update more than one contact per call.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "contact_id": {
        "type": "string",
        "description": "Stable production CRM contact ID, not an email address or display name."
      },
      "changes": {
        "type": "object",
        "properties": {
          "address": {"type": "string"},
          "phone": {"type": "string"},
          "email": {"type": "string"}
        },
        "minProperties": 1,
        "additionalProperties": false
      }
    },
    "required": ["contact_id", "changes"],
    "additionalProperties": false
  }
}

La seconde description donne à l'agent une séquence, nomme la conséquence et écarte les substitutions tentantes. Elle place aussi les informations qui lèvent l'ambiguïté près de l'action, plutôt que de les enfouir dans un manuel opérationnel séparé que l'agent ne verra peut-être jamais.

Soyez explicite sur les effets secondaires. Écrivez « envoie immédiatement un e-mail », « crée une transaction », « supprime la branche distante » ou « écrit en production ». N'écrivez pas « conserve les modifications » ou « exécute l'opération demandée ». Ces formules permettent à un relecteur de sembler précis tout en masquant la seule chose que l'agent et l'humain doivent remarquer.

Les descriptions des champs d'entrée comptent pour la même raison. Si un champ accepte un identifiant de ressource, précisez qu'un nom affiché n'est pas valide. Si une date utilise UTC par défaut, indiquez-le. Des schémas trop permissifs, avec des chaînes facultatives, reportent le sens dans la prose et laissent l'agent improviser des arguments qui se trouvent simplement être acceptés.

Un accès étendu ne doit jamais ressembler à une solution de repli pratique

Le catalogue le plus dangereux contient un outil limité et un outil plus étendu qui semblent répondre à la même demande. Le second existe souvent pour de bonnes raisons : un administrateur a besoin d'un accès d'urgence, une migration nécessite une recherche inter-comptes ou une procédure d'assistance a besoin d'une dérogation. L'erreur consiste à l'exposer comme un outil voisin au nom sympathique.

Imaginez ces entrées :

support_ticket_get
support_ticket_update
support_admin_query

Un agent veut obtenir le contexte d'un ticket. support_admin_query peut rechercher des tickets, des utilisateurs, l'historique de facturation, des notes internes et des fiches supprimées. Si sa description commence par « Interroge la plateforme d'assistance », l'agent peut le sélectionner parce que son large périmètre semble utile. L'outil a fait ce que son nom lui demandait. L'échec se situe dans la conception, avant l'appel.

Renommez-le et limitez-le :

support_internal_cross_account_search

Sa description doit préciser qu'il recherche des données internes d'assistance entre plusieurs comptes, renvoie des éléments qui ne figurent pas dans la fiche du ticket et exige une instruction explicite indiquant la limite de compte. Si le processus le permet, demandez un identifiant de compte dans le schéma au lieu d'accepter seulement une requête en texte libre.

Je déconseille la recommandation habituelle qui consiste à exposer un « outil tout-puissant » pour gagner en flexibilité. Elle est populaire parce qu'elle réduit le code serveur et permet aux opérateurs expérimentés de faire davantage avec moins d'appels. Pour un agent autonome, elle efface la distinction entre le travail ordinaire et une autorité exceptionnelle. Créez des outils distincts pour les niveaux d'autorité réellement différents. Quelques entrées de catalogue supplémentaires coûtent moins cher qu'une explication à fournir après la divulgation de l'historique du mauvais client par une recherche trop étendue.

Cela vaut aussi pour les environnements. Ne proposez pas deploy avec un argument environment dont la valeur par défaut est la production. Utilisez des noms d'action distincts lorsqu'une mauvaise valeur entraîne un rayon d'impact différent :

release_staging_deploy
release_production_deploy

Une énumération dans le schéma reste utile, mais des noms distincts rendent la production visible lors de la sélection, de l'approbation et, plus tard, dans le journal d'audit.

Les paramètres ne peuvent pas porter tout le sens lié à la sécurité

Un paramètre modifie une action après que l'agent a choisi l'outil. Le nom et la description influencent le choix lui-même. Les équipes confondent ces deux rôles lorsqu'elles créent un outil universel doté d'un grand objet d'arguments.

Cette conception semble compacte :

{
  "name": "repository_action",
  "description": "Performs repository operations.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "operation": {"enum": ["read_file", "create_branch", "delete_branch", "open_pull_request"]},
      "repository": {"type": "string"},
      "branch": {"type": "string"}
    },
    "required": ["operation", "repository"]
  }
}

Elle place aussi une opération de lecture, une opération d'écriture et une opération destructive derrière le même libellé de routage. Un agent qui a choisi repository_action a déjà franchi la limite importante. Le relecteur voit une approbation pour une action générique et opaque, puis doit examiner les arguments dans l'urgence.

Séparez-les lorsque la classe de l'action change :

repository_file_read
repository_branch_create
repository_branch_delete
repository_pull_request_create

Gardez les paramètres pour les informations qui varient au sein d'une même action : identifiant du dépôt, nom de branche, chemin du fichier, message de commit ou curseur de page. Ne faites pas d'un paramètre le choix entre lire, écrire, envoyer, facturer, supprimer ou atteindre la production.

La même règle s'applique à la portée. report_export avec scope: all_accounts transforme une exportation apparemment anodine en extraction inter-comptes. Si la portée change les personnes susceptibles d'être affectées ou les données pouvant sortir du système, donnez-lui son propre outil ou imposez un chemin d'autorisation plus fort. L'agent ne doit pas découvrir cette différence d'autorité seulement après avoir rempli un champ JSON.

La sélection des outils nécessite une suite de tests d'ambiguïté

Vous ne pouvez pas examiner un catalogue une seule fois et le déclarer compréhensible. Testez-le avec les demandes réellement formulées par les utilisateurs, en particulier les demandes incomplètes qui obligent l'agent à déduire la portée.

Créez une petite suite de sélection pour chaque serveur. Vous pouvez l'exécuter manuellement avec le client d'agent pris en charge, ou fournir le catalogue et les prompts à un banc d'évaluation contrôlé. Enregistrez l'outil choisi, les arguments proposés et la décision de savoir si un humain accepterait l'appel. Ne notez pas uniquement la réussite finale de la tâche. Un outil étendu qui renvoie la bonne réponse reste un mauvais choix lorsqu'un outil plus limité existait.

Utilisez des prompts comme ceux-ci :

1. « Trouve la facture de la commande 1842. » Le choix attendu devrait être une recherche de facturation en lecture seule, pas une recherche générale dans le grand livre.
2. « Mets à jour le numéro de téléphone de Priya. » L'agent devrait demander de quelle Priya il s'agit si aucun identifiant de contact stable n'est fourni, plutôt que de rechercher puis de modifier une correspondance probable.
3. « Déploie le correctif. » L'agent devrait demander l'environnement lorsque le catalogue contient des actions distinctes pour le staging et la production.
4. « Retire Alex du dépôt. » L'agent devrait distinguer l'appartenance au dépôt de l'appartenance à l'organisation.
5. « Envoie la facture. » L'agent devrait sélectionner une action d'envoi, pas un générateur d'aperçu ni une action générique de mise à jour de facture.

Ajoutez des formulations adversariales qui ressemblent à la description du mauvais outil. Si internal_cross_account_search l'emporte lorsqu'un prompt dit « trouve tout ce que nous avons sur ce client », votre description est peut-être honnête sur le plan technique, mais elle reste trop attirante. Le comportement correct peut consister à choisir une recherche limitée ou à demander à l'utilisateur d'indiquer un compte.

Conservez la transcription des tests lorsque vous renommez des outils. Elle révèle des régressions qu'un validateur de schéma ne peut pas détecter. Un catalogue peut rester valide alors qu'un renommage innocent transforme billing_invoice_get en get_invoice, lequel entre en concurrence avec des systèmes d'achats, de logistique et de services juridiques.

Les écrans d'approbation doivent répéter l'action en langage clair

Une approbation humaine est un dernier point de contrôle, pas une permission de laisser les libellés d'outils dans le vague. Si l'approbation ne présente qu'une requête de bas niveau comme POST /v1/contacts/123, la personne qui approuve doit reconstituer l'intention à partir d'un point d'accès et d'une charge utile. C'est un mauvais moment pour découvrir que l'agent a choisi le CRM de production plutôt qu'un bac à sable.

Faites passer le même sens métier à travers toutes les couches. Le nom de l'outil indique crm_production_contact_update. La description précise qu'il écrit immédiatement dans une seule fiche de production existante. L'approbation doit dire que l'agent veut modifier un champ donné sur un contact de production précis, identifier le compte cible lorsqu'il est connu et afficher les valeurs proposées. L'événement d'audit doit conserver l'identité de l'outil ainsi que le canal et la cible réellement utilisés.

Ne rendez pas le texte de l'approbation plus rassurant que l'action. « Autoriser la mise à jour du CRM » masque la différence entre corriger un numéro de téléphone et remplacer l'adresse e-mail utilisée pour récupérer un compte. Affichez les arguments importants, après en avoir supprimé les secrets. Si un argument contient des données client sensibles, montrez suffisamment de structure pour permettre la vérification tout en respectant vos règles de traitement des données.

L'autorisation par session de Sallyport peut établir qu'un processus d'agent donné est autorisé à agir pendant son exécution, tandis que les clés par appel peuvent exiger une approbation distincte pour les identifiants qui méritent un examen à chaque utilisation. Cette séparation fonctionne d'autant mieux que les libellés d'action donnent à la personne qui approuve une description immédiate et exacte de ce que l'agent demande.

Les identifiants et l'identité de l'outil répondent à des problèmes différents

Garder les identifiants hors de portée de l'agent évite un problème courant : l'agent ne peut pas copier une clé d'API dans un journal, un fichier source, un ticket ou une réponse de chat puisqu'il ne reçoit jamais le secret. Cette protection ne rend pas chaque demande sûre. L'agent peut toujours demander à une passerelle d'exécuter le mauvais outil avec un identifiant légitime.

Séparez ces questions lors de la conception :

• L'agent peut-il obtenir ou exposer l'identifiant ?
• L'agent peut-il demander une action en dehors de la portée prévue par l'utilisateur ?
• Un humain peut-il voir quel processus a demandé l'action ?
• Un enquêteur peut-il vérifier ce qui s'est passé après l'exécution ?

Le catalogue d'outils répond à la deuxième question. L'identité de session et les approbations répondent à la troisième. Un enregistrement infalsifiable répond à la quatrième. Chaque couche a son rôle et aucune ne remplace les autres.

Sallyport conserve les identifiants HTTP et SSH dans son coffre chiffré et exécute l'action sans remettre ces secrets à l'agent. Cela réduit l'exposition des identifiants, mais l'agent a toujours besoin d'un catalogue dont les noms l'empêchent de demander une action plus étendue simplement parce que son nom semblait suffisamment proche.

Cette distinction compte lorsque des équipes disent : « L'agent ne voit pas le jeton, donc l'outil est sûr. » Le jeton peut être protégé alors que l'action reste trop puissante. Un identifiant de reporting en lecture seule et un identifiant de remboursement en production ne devraient pas se trouver derrière des entrées presque identiques simplement parce qu'ils sont tous deux isolés du modèle.

Les espaces de noms aident les opérateurs, mais ne justifient pas des actions vagues

De nombreux clients affichent les outils avec un préfixe dérivé du serveur, comme crm.search_contacts ou billing.search_contacts. Utilisez un espace de noms lorsque votre client le permet. Il donne à l'agent et à l'opérateur un indice de routage supplémentaire et réduit les noms littéralement en double.

N'en dépendez pas comme seul indice. Les clients peuvent raccourcir les libellés, aplanir les catalogues de serveurs ou afficher des noms de serveurs qui ne veulent pas dire grand-chose à la personne qui lit une approbation. Un outil appelé search_contacts reste vague si un serveur atteint une base de test et un autre des données client réelles.

Un meilleur duo serait :

crm_production_contact_search
marketing_audience_contact_search

Ces noms restent compréhensibles après l'ajout ou la suppression d'un préfixe par le client. Ils rendent aussi les catalogues mixtes plus sûrs lorsqu'un agent se connecte progressivement à davantage de serveurs.

Utilisez les limites entre serveurs pour regrouper des autorités liées, pas pour les dissimuler. Un serveur appelé operations qui expose des remboursements de facturation, des déploiements en production, des exports clients et des modifications de personnel peut être pratique pour l'équipe qui le gère. Il produit un catalogue encombré, avec des verbes sans rapport entre eux et une large surface d'identifiants. Séparez les serveurs lorsque des domaines distincts ont des responsables, des identifiants, des attentes d'approbation ou des circuits de contrôle différents.

Une revue du catalogue détecte les problèmes avant le déploiement

Examinez un catalogue d'outils avec une liste de tâches en langage naturel, pas isolément. Un nom qui semble évident à son auteur s'appuie souvent sur un contexte qui disparaît lorsque trente outils provenant de six serveurs apparaissent dans la même session d'agent.

Utilisez cette courte revue avant de livrer une nouvelle action :

1. Lisez uniquement le nom. Une personne peut-elle identifier le système externe, l'objet, l'effet secondaire et la portée inhabituelle ?
2. Placez-le à côté de tous les outils similaires. Un nom décrit-il un accès plus large avec un verbe plus doux ?
3. Faites abstraction de la description. Le schéma cache-t-il dans un argument le choix entre lecture et écriture, bac à sable et production, ou fiche unique et recherche inter-comptes ?
4. Formulez une demande utilisateur ambiguë. L'agent devrait-il poser une question de clarification, et avez-vous rendu cette option plus sûre que la devinette ?
5. Vérifiez les libellés d'approbation et d'audit. Conservent-ils la même distinction que le nom de l'outil ?

La bonne réponse consiste souvent à refuser une demande d'action générique et pratique. Ce refus contrarie quelqu'un une fois, pendant l'implémentation. Un outil ambigu contrarie les personnes qui devront analyser l'appel inattendu plus tard, lorsque le contexte aura déjà disparu.

Gardez un nom précis, décrivez clairement la limite et rendez difficile la sélection accidentelle d'une autorité étendue. Un agent n'a pas besoin de choix plus plausibles. Il a besoin de moins de façons de confondre une autorisation avec une autre.