Was ich beim Schreiben von 50 MCP-Tools gelernt habe: Funktionsaufrufe waren eine ungewöhnlich intime Beziehung

Ein Text, der auf Basis der Erfahrung, ein Vermögensverwaltungs-Tool an zwei Wochenendtagen auf eine SQLite-basierte CLI und einen MCP-Server umgestellt zu haben, zusammenfasst, an welchem entscheidenden Punkt sich das Design von MCP-Tools von RPC trennt.
Der Autor schrieb rund 30 CLI-Kommandos und mehr als 50 MCP-Tools und ging von der Erkenntnis aus, dass er trotz des Umfangs nicht am Code, sondern an den Beschreibungen der Funktionen am längsten festhing.

• Als dieselbe Funktion gleichzeitig für CLI und MCP offengelegt wurde, liefen die beiden Interfaces unterschiedlich, obwohl Signatur/Argumente/Rückgabewerte identisch waren. Geändert hatte sich nur, ob der Aufrufer ein Mensch oder ein LLM war
• Die Signatur erklärt zwar, was eine Funktion entgegennimmt, aber kaum, wann sie aufgerufen werden sollte. Ein Funktionsname ist eher wie eine Zeile in einem Wörterbuch und entscheidet als Wort allein nicht, in welchen Satz er gesetzt wird
• Für einen LLM-Aufrufer sind schwere Tools, die eine Absicht direkt treffen, natürlicher als fein nach dem Single Responsibility Principle (SRP) aufgespaltene Tools
• MCP gehört der Form nach zwar zur RPC-Linie (JSON-RPC, Signaturen, Schemata), der entscheidende Unterschied ist jedoch, dass die Richtung des Vertrauens umgekehrt wird. Bei RPC vertraut der Aufrufer dem Aufrufziel, bei MCP muss die Seite, die das Tool gebaut hat, dem Aufrufer (LLM) vertrauen
• Die Signatur ist eine Deklaration, die Beschreibung eine Bitte. Das eine ist Zwang, das andere Überzeugung. In das Tool-Design hält damit eine Sprache der Überzeugung Einzug
• Das ist weniger eine neue Veränderung als eher eine Rückkehr. Industriedesign, Architektur und UX standen schon lange an diesem Punkt; nur die Programmierung war bislang auffällig lange an einem besonders intimen Ende geblieben

Was Signaturen nicht sagen

• Bei Firma waren add_txn (Transaktion), add_balance (Vermögens-Snapshot) und add_flow (Einnahmen/Ausgaben) in ihren Signaturen alle klar, und auch die Argumenttypen waren streng über zod-Schemata definiert, doch das LLM verwechselte häufig, welches Tool es aus einer Nutzeraussage heraus aufrufen sollte
• Zuerst wurde ein Problem des LLM-Modells vermutet, tatsächlich lag das Problem aber in der Signatur selbst. Der Name add_txn enthält nicht den Aufrufzeitpunkt im Sinne von „Wenn der Nutzer einen Kauf oder Verkauf erwähnt, verwende dieses Tool“
• Erst nachdem in der description im Format "Use this when... Do NOT use this for..." der Aufrufzeitpunkt und die Abgrenzung zu anderen Tools explizit gemacht wurden, stabilisierte sich das Aufrufverhalten
• Die Intention der Funktion wanderte von der Signatur in die Funktionsbeschreibung. So wie der Griff eines Hammers durch seine Form die Benutzung andeutet, ist die Beschreibung einer MCP-Funktion für das LLM faktisch die Affordanz des Tools (Donald Norman)

SRP vs. Affordanz und die Richtung des Vertrauens

• Zunächst sollte alles nach dem Single Responsibility Principle in kleine Einheiten wie get_holdings, get_prices und get_pnl zerlegt werden. Fragt der Nutzer jedoch „Wie sieht mein Portfolio aus?“, muss das LLM vier oder fünf Aufrufe kombinieren, die Antwort wird langsamer und die Gefahr von Fehlgriffen steigt
• Am Ende wurde show_portfolio als schweres Tool entworfen, das Bestände/Durchschnittseinstandskurs/aktuellen Preis/Bewertungsbetrag/kumulierten Gewinn und Verlust in einem Zug zurückgibt. get_brief geht noch weiter und liefert sogar Makroindikatoren und Insights auf einmal zurück
• SRP ist eine Tugend für den Menschen, der Funktionen baut; Affordanz ist eine Tugend für den Menschen, der Tools benutzt. Ist der Aufrufer ein Mensch, lässt sich zusammensetzen; ist er ein LLM, sind Tools besser, die eine Absicht direkt treffen
• Bei Schreib-Tools zeigt sich die Richtung des Vertrauens am deutlichsten. Als bei add_txn "Always confirm with the user before recording" stand, fragte das LLM jedes Mal nach und der Nutzer antwortete jedes Mal mit „OK“ — der Vorteil eines Natural-Language-Interfaces ging verloren
• Schließlich wurde die Verantwortung neu aufgeteilt nach dem Muster „Sofort aufzeichnen, nur bei Unklarheiten nachfragen, und falls etwas falsch ist, kann es rückgängig gemacht werden“. Solche Anweisungen sind keine formale Beschreibung des Tools, sondern Betriebsprinzipien für den Aufrufer

Vielleicht war der Funktionsaufruf selbst eher der Sonderfall

• Menschen haben schon immer Werkzeuge benutzt, die sie nicht selbst gebaut haben. Das gilt gleichermaßen für das Gefäß des Töpfers, das Messer des Schmieds und Programme, die Entwickler gebaut haben
• Funktionsaufrufe waren dann wohl eine ziemlich spezielle Beziehung, in der Aufrufer und Autor viel Kontext teilen und Typsystem/IDE/Dokumentation diese Intimität fortlaufend verstärken
• Wenn der Aufrufer kein Mensch ist, gibt es zwei Möglichkeiten: (1) dem LLM mehr Kontext geben, um es zu einem intimen Aufrufer zu machen, oder (2) auf Tool-Seite die Distanz überbrücken. MCP liegt näher an Letzterem
• Möglicherweise leben wir in einer Zeit, in der sich schon leise die Art verändert, wie Interfaces entworfen werden. Der Schwerpunkt wandert von der Signatur zur Beschreibung, von Zwang zu Überzeugung, von der Annahme von Intimität zur Anerkennung von Distanz