Kollisionen bei MCP-Tool-Namen und sichereres Agent-Verhalten

Ein Agent liest einen MCP-Toolkatalog nicht so sorgfältig wie ein erfahrener Entwickler ein SDK. Er ordnet eine komprimierte Anweisung einer wahrscheinlichen Aktion zu. Wenn Sie ihm get_user, get_users, user_lookup und admin_get_user geben und dann auf einen Absatz voller Einschränkungen setzen, um sie voneinander zu unterscheiden, haben Sie rund um Berechtigungen ein Ratespiel gebaut.

Kollisionen bei MCP-Tool-Namen sind nicht nur doppelte Kennungen, wegen derer ein Client einen Katalog ablehnt. Die schlimmere Kollision ist semantisch: Zwei aufrufbare Aktionen klingen austauschbar, aber eine erreicht ein umfassenderes System, verwendet stärkere Zugangsdaten oder ändert den Zustand. Ich habe erlebt, dass Teams dies als Prompting-Problem bezeichneten, nachdem ein Agent die falsche Aktion ausgewählt hatte. Meist war es ein Schnittstellenproblem, das sie selbst ausgeliefert hatten.

Die Lösung ist weder eine riesige Taxonomie noch ein feierliches Namenskomitee. Geben Sie jeder Aktion einen Namen, der sagt, was sie tut, wo sie es tut und wie weit ihre Berechtigungen reichen. Schreiben Sie anschließend Beschreibungen, die die Grenze festlegen, die der Name nicht vollständig tragen kann. Machen Sie Mehrdeutigkeiten in Tests sichtbar, bevor daraus eine Genehmigungskarte, ein unerwarteter API-Aufruf oder eine schwierige Untersuchung wird.

Eine Kollision ist zuerst semantisch, dann syntaktisch

Eine syntaktische Kollision entsteht, wenn zwei MCP-Server beide ein Tool namens search veröffentlichen. Je nach Client kann ein Eintrag überschrieben, ein Namespace erzwungen oder ein verwirrender Katalog erzeugt werden. Sie sollten das beheben, weil sich das Verhalten zwischen Clients unterscheiden kann.

Eine semantische Kollision bleibt bestehen, auch wenn jede Kennung technisch eindeutig ist. Betrachten Sie diese Tools:

search_customer
search_customer_records
lookup_customer
customer_admin_search

Alle vier können für einen Compiler gültig und für das Team, das sie gebaut hat, verständlich sein. Für einen Agent, der die Anfrage erhält, „Finde den Kundendatensatz von Maya Chen und aktualisiere ihre Adresse“, liefern sie schwache Routing-Signale. Der Agent muss erschließen, welches System die maßgeblichen Daten besitzt, ob die Aktion nur liest, ob sie den gesamten Mandanten durchsuchen kann und ob eine administrative Berechtigung vertretbar ist.

Tool-Schemas retten keinen unklaren Katalog. Ein Modell kann Argumentnamen prüfen, aber ähnliche Schemas machen die Mehrdeutigkeit oft noch größer. Sowohl eine schreibgeschützte Verzeichnissuche als auch eine Suche im Produktions-CRM können query, limit und organization_id akzeptieren. Dass eines Daten zurückgibt, während das andere eine Anreicherung auslösen oder ein Audit-Ereignis schreiben kann, steht womöglich nur in einer Beschreibung, die das Modell geringer gewichtet als die scheinbare Übereinstimmung mit der Aufgabe.

Behandeln Sie diese Fehler getrennt:

• Kennungskollision: Der Client kann zwei Tools nicht konsistent darstellen.
• Absichtskollision: Zwei Tools scheinen dieselbe Benutzeranfrage zu erfüllen.
• Berechtigungskollision: Hinter einem eng klingenden Tool steckt eine weitreichende Berechtigung.
• Umgebungskollision: Ähnliche Bezeichnungen verbergen unterschiedliche Konten, Regionen oder Produktionszustände.

Die letzten drei verursachen die teuren Fehler. Ein Client kann doppelte Namen ablehnen. Er kann Ihnen nicht zuverlässig sagen, dass sync_contact „einen Datensatz im Produktions-CRM mit einem mandantenweiten Token ändert“, während update_contact „in eine lokale Testvorrichtung schreibt“.

Tool-Namen müssen die Routing-Fakten tragen

Ein brauchbarer Name liefert dem Agent die nötigen Fakten, bevor er eine lange Beschreibung liest. Für Aktionen an externen Systemen verwende ich diese Reihenfolge: Zielsystem, Objekt, Verb und anschließend der Geltungsbereich, wenn dieser die Berechtigung oder die Folgen verändert.

crm_contact_update ist besser als update_contact, weil der Name das System nennt. crm_production_contact_update kann noch besser sein, wenn derselbe Katalog auch eine Sandbox enthält. github_org_member_remove ist klarer als manage_member, weil der Name sagt, welche Ressource geändert wird und dass sie entfernt wird.

Packen Sie nicht jedes Implementierungsdetail in den Namen. Agents brauchen nicht crm_v3_contacts_patch_with_bearer_auth. Sie brauchen Unterscheidungen, die die Auswahl verändern. Version, Transport und Authentifizierung gehören normalerweise in die Serverimplementierung oder Beschreibung. Konto, Umgebung, Nebenwirkung und Berechtigungsgrenze gehören oft in den Namen.

Ein praktisches Muster sieht so aus:

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

Beispiele:

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

Das Muster ist kein Dogma. Entscheidend ist, dass benachbarte Namen an der Stelle voneinander abweichen, an der sich ihre Wirkung unterscheidet. Wenn billing_invoice_send_customer und billing_invoice_preview_email nebeneinanderstehen, zeigen Verben und Objekte dem Modell, welches Tool tatsächlich eine Person kontaktiert. Wenn der einzige Unterschied in einem booleschen Parameter steckt, der in einem Schema verborgen ist, verlangt der Katalog beim Routing zu viel.

Vermeiden Sie unklare Verben wie process, manage, handle, run, execute, sync und apply, sofern das Objekt die Wirkung nicht eindeutig macht. Sie sind beliebt, weil Produktteams sie als Sammelbegriffe für mehrere Vorgänge verwenden. Genau deshalb sind sie schlechte Tool-Namen. Ein Modell behandelt einen Sammelbegriff als Erlaubnis, die weitestgehende Interpretation zu wählen, mit der sich die Anfrage erledigen lässt.

Beschreibungen definieren die Grenze, nicht das Marketing

Die Tool-Spezifikation des Model Context Protocol definiert ein Tool mit Name, Beschreibung und Eingabeschema. Das ist ein Schnittstellenvertrag und kein Ort für Produkttexte. Die Beschreibung sollte vier operative Fragen beantworten: Welche Aktion findet statt, welches externe Ziel erhält sie, welcher Umfang gilt und was verweigert das Tool?

Vergleichen Sie diese beiden Beschreibungen:

{
  "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
  }
}

Die zweite Beschreibung gibt dem Agent eine Reihenfolge vor, benennt die Folge und schließt naheliegende Ersetzungen aus. Außerdem stehen die unterscheidenden Details direkt bei der Aktion, statt in einem separaten Betriebshandbuch verborgen zu sein, das der Agent möglicherweise nie sieht.

Seien Sie bei Nebenwirkungen direkt. Schreiben Sie „sendet E-Mails sofort“, „erzeugt eine Abbuchung“, „löscht den entfernten Branch“ oder „schreibt in die Produktion“. Schreiben Sie nicht „speichert Änderungen“ oder „führt den angeforderten Vorgang aus“. Solche Formulierungen lassen eine prüfende Person präzise klingen und verbergen zugleich das Einzige, worauf Agent und Mensch achten müssen.

Beschreibungen von Eingabefeldern sind aus demselben Grund wichtig. Wenn ein Feld eine Ressourcen-ID erwartet, sagen Sie, dass ein Anzeigename ungültig ist. Wenn ein Datum standardmäßig in UTC interpretiert wird, sagen Sie es. Lockere Schemas mit optionalen Zeichenketten verlagern die Bedeutung in den Fließtext und lassen einen Agent Argumente improvisieren, die zufällig akzeptiert werden.

Weitreichender Zugriff darf nie wie eine bequeme Ausweichlösung aussehen

Der gefährlichste Katalog enthält ein eng begrenztes und ein umfassenderes Tool, die scheinbar dieselbe Anfrage lösen. Das umfassendere Tool kann gute Gründe haben: Ein Administrator benötigt Notfallzugriff, eine Migration muss kontenübergreifend suchen oder ein Supportprozess braucht eine Ausnahme. Der Fehler besteht darin, es als gleichrangiges Tool mit einem freundlichen Namen bereitzustellen.

Stellen Sie sich diese Einträge vor:

support_ticket_get
support_ticket_update
support_admin_query

Ein Agent möchte Kontext zu einem Ticket. support_admin_query kann Tickets, Benutzer, Abrechnungsverläufe, interne Notizen und gelöschte Datensätze durchsuchen. Beginnt seine Beschreibung mit „Durchsucht die Supportplattform“, kann der Agent es auswählen, weil die große Abdeckung nützlich wirkt. Das Tool tat, was sein Name nahelegt. Das Design war schon vor dem Aufruf fehlerhaft.

Benennen und begrenzen Sie es neu:

support_internal_cross_account_search

Die Beschreibung sollte sagen, dass es interne Supportdaten kontenübergreifend durchsucht, Material außerhalb des Ticketdatensatzes zurückgibt und eine ausdrückliche Anweisung mit Kontengrenze benötigt. Wenn der Prozess es erlaubt, verlangen Sie eine Konto-ID im Schema, statt allein eine Freitextanfrage zu akzeptieren.

Ich halte wenig von der üblichen Empfehlung, aus Gründen der Flexibilität ein einziges „Power-Tool“ bereitzustellen. Sie ist beliebt, weil sie Servercode reduziert und erfahrenen Bedienenden ermöglicht, mit weniger Aufrufen mehr zu tun. Für einen autonomen Agent löscht sie jedoch den Unterschied zwischen normaler Arbeit und besonderer Berechtigung. Erstellen Sie getrennte Tools für Berechtigungen, die sich wesentlich unterscheiden. Mehr Katalogeinträge sind billiger, als später erklären zu müssen, warum eine weitreichende Suche die falsche Kundenvorgeschichte offengelegt hat.

Das gilt auch für Umgebungen. Bieten Sie kein deploy mit einem environment-Argument an, das standardmäßig auf die Produktion zeigt. Verwenden Sie getrennte Aktionsnamen, wenn ein falscher Wert unterschiedliche Auswirkungen hat:

release_staging_deploy
release_production_deploy

Ein Enum im Schema hilft weiterhin. Unterschiedliche Namen machen die Produktion jedoch bereits bei der Auswahl, bei der Genehmigung und später im Audit-Eintrag sichtbar.

Parameter können nicht die gesamte Sicherheitsbedeutung tragen

Ein Parameter verändert eine Aktion, nachdem der Agent das Tool ausgewählt hat. Name und Beschreibung beeinflussen bereits die Auswahl. Teams vermischen diese Aufgaben, wenn sie ein universelles Tool mit einem großen Argumentobjekt bauen.

Dieses Design wirkt kompakt:

{
  "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"]
  }
}

Es legt jedoch eine Leseaktion, eine Schreibaktion und eine zerstörerische Aktion hinter dasselbe Routing-Label. Ein Agent, der repository_action ausgewählt hat, hat die wesentliche Grenze bereits überschritten. Eine prüfende Person sieht eine Genehmigung für eine undurchsichtige Sammelaktion und muss unter Zeitdruck die Argumente untersuchen.

Teilen Sie das Tool dort auf, wo sich die Aktionsklasse ändert:

repository_file_read
repository_branch_create
repository_branch_delete
repository_pull_request_create

Verwenden Sie Parameter für Fakten, die innerhalb einer Aktion variieren: Repository-ID, Branchname, Dateipfad, Commit-Nachricht oder Seiten-Cursor. Lassen Sie einen Parameter nicht entscheiden, ob der Aufruf liest, schreibt, sendet, abbucht, löscht oder die Produktion erreicht.

Dasselbe gilt für den Geltungsbereich. report_export mit scope: all_accounts macht aus einem harmlos wirkenden Export eine kontenübergreifende Extraktion. Wenn der Umfang beeinflusst, wer betroffen sein kann oder welche Daten das System verlassen, geben Sie diesem Umfang ein eigenes Tool oder verlangen Sie einen stärkeren Autorisierungsweg. Der Agent sollte den Berechtigungsunterschied nicht erst entdecken, nachdem er ein JSON-Feld ausgefüllt hat.

Für die Tool-Auswahl braucht es eine Mehrdeutigkeits-Testsuite

Sie können einen Katalog nicht einmal ansehen und anschließend für verständlich erklären. Testen Sie ihn mit den Anfragen, die Benutzer tatsächlich stellen, besonders mit unvollständigen Anfragen, bei denen ein Agent den Geltungsbereich erschließen muss.

Erstellen Sie für jeden Server eine kleine Auswahlsuite. Sie können sie manuell mit dem unterstützten Agent-Client ausführen oder Katalog und Prompts in eine kontrollierte Evaluationsumgebung geben. Protokollieren Sie das ausgewählte Tool, die vorgeschlagenen Argumente und die Frage, ob ein Mensch den Aufruf akzeptieren würde. Bewerten Sie nicht nur, ob die Aufgabe letztlich erfolgreich war. Ein weitreichendes Tool, das die richtige Antwort liefert, ist trotzdem die falsche Auswahl, wenn ein engeres Tool vorhanden war.

Verwenden Sie beispielsweise diese Prompts:

1. „Finde die Rechnung für Bestellung 1842.“ Erwartet wird eine schreibgeschützte Suche in der Abrechnung, keine allgemeine Suche im Hauptbuch.
2. „Aktualisiere Priyas Telefonnummer.“ Wenn keine stabile Kontakt-ID vorhanden ist, sollte der Agent fragen, welche Priya gemeint ist, statt zu suchen und einen wahrscheinlichen Treffer zu ändern.
3. „Stell den Fix bereit.“ Wenn der Katalog Aktionen für Staging und Produktion enthält, sollte der Agent nach der Umgebung fragen.
4. „Entferne Alex aus dem Repository.“ Der Agent sollte zwischen Repository-Mitgliedschaft und Organisationsmitgliedschaft unterscheiden.
5. „Sende die Rechnung.“ Der Agent sollte eine Versandaktion wählen, keinen Vorschaugenerator und keinen allgemeinen Aufruf zum Aktualisieren einer Rechnung.

Fügen Sie bewusst Formulierungen hinzu, die der Beschreibung des problematischen Tools ähneln. Wenn internal_cross_account_search gewinnt, sobald eine Anfrage lautet „Finde alles, was wir über diesen Kunden haben“, ist die Beschreibung möglicherweise technisch korrekt, aber noch immer zu einladend. Das richtige Verhalten kann darin bestehen, eine Suche mit begrenztem Umfang zu wählen oder den Benutzer nach einem Konto zu fragen.

Bewahren Sie das Testprotokoll, wenn Sie Tools umbenennen. Es macht Regressionen sichtbar, die ein Schema-Validator nicht erkennen kann. Ein Katalog kann gültig bleiben, während eine harmlose Umbenennung aus billing_invoice_get das allgemeinere get_invoice macht, das mit Einkaufs-, Logistik- und Rechtssystemen konkurriert.

Genehmigungsdialoge sollten die Aktion in klarer Sprache wiederholen

Eine menschliche Genehmigung ist der letzte Kontrollpunkt, keine Erlaubnis, Tool-Bezeichnungen nachlässig zu halten. Wenn die Genehmigung nur eine Anfrage auf niedriger Ebene wie POST /v1/contacts/123 anzeigt, muss die genehmigende Person die Absicht aus Endpunkt und Payload rekonstruieren. Das ist ein schlechter Moment, um zu bemerken, dass der Agent das Produktions-CRM statt einer Sandbox gewählt hat.

Führen Sie dieselbe fachliche Bedeutung durch jede Ebene. Der Tool-Name lautet crm_production_contact_update. Die Beschreibung sagt, dass sofort in einen bestehenden Produktionsdatensatz geschrieben wird. Die Genehmigung sollte sagen, dass der Agent ein benanntes Feld eines einzelnen Produktionskontakts ändern möchte, das Zielkonto nennen, sofern es bekannt ist, und die vorgeschlagenen neuen Werte anzeigen. Das Audit-Ereignis sollte sowohl die Tool-Identität als auch den tatsächlich ausgeführten Kanal und das Ziel bewahren.

Formulieren Sie den Genehmigungstext nicht beruhigender als die Aktion. „CRM-Aktualisierung zulassen“ verbirgt den Unterschied zwischen der Korrektur einer Telefonnummer und dem Ersetzen einer E-Mail-Adresse, die zur Kontowiederherstellung dient. Zeigen Sie die wichtigen Argumente ohne Geheimnisse. Enthält ein Argument sensible Kundendaten, zeigen Sie genug Struktur für eine Prüfung und beachten Sie zugleich Ihre Regeln zum Umgang mit Daten.

Sallyports sitzungsbezogene Autorisierung kann festlegen, dass ein bestimmter Agent-Prozess während seines Laufs handeln darf. Schlüssel pro Aufruf können zusätzlich eine eigene Genehmigung für Zugangsdaten verlangen, die bei jeder Verwendung geprüft werden sollten. Diese Aufteilung funktioniert am besten, wenn die Aktionsbezeichnungen der genehmigenden Person sofort und korrekt zeigen, was der Agent anfordert.

Zugangsdaten und Tool-Identität lösen unterschiedliche Probleme

Wenn Zugangsdaten vom Agent ferngehalten werden, kann er einen API-Schlüssel nicht in ein Log, eine Quelldatei, ein Ticket oder eine Chatantwort kopieren, weil er das Geheimnis nie erhält. Diese Kontrolle macht nicht jede Anfrage sicher. Der Agent kann ein Gateway weiterhin auffordern, mit einer legitimen Berechtigung das falsche Tool auszuführen.

Trennen Sie diese Fragen bei der Entwicklung:

• Kann der Agent die Zugangsdaten erhalten oder offenlegen?
• Kann der Agent eine Aktion außerhalb des vom Benutzer beabsichtigten Umfangs anfordern?
• Kann ein Mensch sehen, welcher Prozess die Aktion angefordert hat?
• Kann eine untersuchende Person nach dem Lauf prüfen, was geschehen ist?

Ein Toolkatalog beantwortet die zweite Frage. Sitzungsidentität und Genehmigungen beantworten die dritte. Ein manipulationssicherer Datensatz beantwortet die vierte. Jede Ebene hat ihre Aufgabe, und keine ersetzt eine andere.

Sallyport bewahrt HTTP- und SSH-Zugangsdaten in seinem verschlüsselten Tresor auf und führt die Aktion aus, ohne diese Geheimnisse an den Agent weiterzugeben. Das verringert die Gefahr, dass Zugangsdaten offengelegt werden. Der Agent braucht aber weiterhin einen Katalog, dessen Namen verhindern, dass er eine umfassendere Aktion anfordert, nur weil ihr Name ähnlich genug klingt.

Diese Unterscheidung ist wichtig, wenn Teams sagen: „Der Agent sieht das Token nicht, also ist das Tool sicher.“ Das Token kann geschützt sein, während die Aktion trotzdem zu weitreichend ist. Eine schreibgeschützte Berechtigung für Berichte und eine Berechtigung für Rückerstattungen in der Produktion sollten nicht hinter nahezu identischen Einträgen liegen, nur weil beide vom Modell getrennt sind.

Namespaces helfen Bedienenden, entschuldigen aber keine unklaren Aktionen

Viele Clients zeigen Tools mit einem vom Server abgeleiteten Präfix an, etwa crm.search_contacts oder billing.search_contacts. Verwenden Sie einen Namespace, wenn Ihr Client dies unterstützt. Er gibt Agent und Bedienenden einen weiteren Routing-Hinweis und reduziert echte doppelte Namen.

Verlassen Sie sich nicht auf ihn als einzigen Hinweis. Clients können Bezeichnungen kürzen, Serverkataloge zusammenführen oder Servernamen anzeigen, die einer Person bei der Genehmigung wenig sagen. Ein Tool namens search_contacts bleibt unklar, wenn ein Server eine Testdatenbank und ein anderer echte Kundendaten erreicht.

Ein besseres Paar lautet:

crm_production_contact_search
marketing_audience_contact_search

Diese Namen bleiben verständlich, wenn ein Client ein Präfix hinzufügt oder entfernt. Sie machen gemischte Kataloge auch dann sicherer, wenn ein Agent im Lauf der Zeit weitere Server verbindet.

Verwenden Sie Servergrenzen, um zusammengehörige Berechtigungen zu gruppieren, nicht um sie zu verbergen. Ein Server namens operations, der Rückerstattungen, Produktionsbereitstellungen, Kundenexporte und Personaländerungen anbietet, mag für das zuständige Team bequem sein. Für einen Agent erzeugt er jedoch einen überfüllten Katalog mit unzusammenhängenden Verben und eine breite Berechtigungsfläche. Teilen Sie Server auf, wenn getrennte Bereiche eigene Verantwortliche, Zugangsdaten, Genehmigungserwartungen oder Prüfpfade haben.

Eine Katalogprüfung findet Fehler vor der Bereitstellung

Prüfen Sie einen Toolkatalog zusammen mit einer Liste natürlichsprachlicher Aufgaben, nicht isoliert. Ein Name, der seinem Urheber eindeutig erscheint, beruht oft auf Kontext, der verschwindet, sobald dreißig Tools von sechs Servern in einer Agent-Sitzung erscheinen.

Verwenden Sie diese kurze Prüfung, bevor Sie eine neue Aktion ausliefern:

1. Lesen Sie nur den Namen. Kann eine Person das externe System, das Objekt, die Nebenwirkung und den ungewöhnlichen Umfang erkennen?
2. Stellen Sie ihn neben jedes ähnliche Tool. Beschreibt ein Name einen breiteren Zugriff mit einem harmloseren Verb?
3. Denken Sie sich die Beschreibung weg. Verbirgt das Schema die Entscheidung zwischen Lesen und Schreiben, Sandbox und Produktion oder Einzel- und kontenübergreifendem Datensatz in einem Argument?
4. Stellen Sie eine mehrdeutige Benutzeranfrage. Sollte der Agent eine Rückfrage stellen, und haben Sie dieses Verhalten sicherer gemacht als ein Raten?
5. Prüfen Sie Genehmigungs- und Audit-Bezeichnungen. Bewahren sie dieselbe Unterscheidung wie der Tool-Name?

Oft ist es richtig, die Bitte um eine bequeme Sammelaktion abzulehnen. Diese Ablehnung frustriert jemanden einmal, während der Implementierung. Ein unklar benanntes Tool frustriert später die Menschen, die den unerwarteten Aufruf untersuchen müssen, wenn der Kontext bereits verschwunden ist.

Halten Sie den Namen präzise, beschreiben Sie die Grenze klar und machen Sie es schwer, weitreichende Berechtigungen versehentlich auszuwählen. Ein Agent braucht nicht mehr plausible Optionen. Er braucht weniger Möglichkeiten, eine Berechtigung mit einer anderen zu verwechseln.