MCP Tutorials: Vom Konzept zur Produktion

Effektive Tools für Agenten schreiben: Vollständiger MCP-Entwicklungsleitfaden

Effektive Tools für Agenten schreiben

Agenten sind nur so effektiv wie die Tools, die wir ihnen geben. Dieser Leitfaden zeigt, wie man hochwertige Tools und Evaluationen schreibt und wie Sie die Performance verbessern können, indem Sie Claude verwenden, um seine Tools für sich selbst zu optimieren.

Das Model Context Protocol (MCP) kann LLM-Agenten mit potenziell Hunderten von Tools ausstatten, um reale Aufgaben zu lösen. Aber wie machen wir diese Tools maximal effektiv?

In diesem Leitfaden beschreiben wir unsere effektivsten Techniken zur Leistungsverbesserung in verschiedenen agentischen KI-Systemen.

Was ist ein Tool?

In der Informatik produzieren deterministische Systeme bei identischen Eingaben jedes Mal dieselbe Ausgabe, während non-deterministische Systeme—wie Agenten—auch bei denselben Ausgangsbedingungen unterschiedliche Antworten generieren können.

Wenn wir traditionell Software schreiben, etablieren wir einen Vertrag zwischen deterministischen Systemen. Zum Beispiel wird ein Funktionsaufruf wie getWeather("NYC") immer das Wetter in New York City auf exakt dieselbe Weise abrufen, jedes Mal wenn er aufgerufen wird.

Tools sind eine neue Art von Software, die einen Vertrag zwischen deterministischen Systemen und non-deterministischen Agenten reflektiert. Wenn ein Benutzer fragt “Sollte ich heute einen Regenschirm mitnehmen?”, könnte ein Agent das Wetter-Tool aufrufen, aus allgemeinem Wissen antworten oder sogar zuerst eine klärende Frage zum Standort stellen. Gelegentlich könnte ein Agent halluzinieren oder sogar versagen zu verstehen, wie ein Tool zu verwenden ist.

Das bedeutet ein fundamentales Umdenken unseres Ansatzes beim Schreiben von Software für Agenten: anstatt Tools und MCP-Server so zu schreiben, wie wir Funktionen und APIs für andere Entwickler oder Systeme schreiben würden, müssen wir sie für Agenten designen.

Wie man Tools schreibt

Einen Prototyp erstellen

Es kann schwierig sein zu antizipieren, welche Tools Agenten ergonomisch finden werden und welche nicht, ohne selbst praktische Erfahrungen zu sammeln. Beginnen Sie damit, schnell einen Prototyp Ihrer Tools zu erstellen.

Wenn Sie Claude Code verwenden, um Ihre Tools zu schreiben, hilft es, Claude Dokumentation für alle Software-Bibliotheken, APIs oder SDKs (einschließlich potenziell des MCP SDK) zu geben, auf die Ihre Tools angewiesen sein werden. LLM-freundliche Dokumentation kann häufig in flachen llms.txt-Dateien auf offiziellen Dokumentations-Websites gefunden werden.

Das Einbetten Ihrer Tools in einen lokalen MCP-Server ermöglicht es Ihnen, Ihre Tools in Claude Code oder der Claude Desktop App zu verbinden und zu testen.

Um Ihren lokalen MCP-Server mit Claude Code zu verbinden, führen Sie claude mcp add <name> <command> [args...] aus.

Tools können auch direkt in Anthropic API-Aufrufe für programmatische Tests übergeben werden.

Testen Sie die Tools selbst, um raue Kanten zu identifizieren. Sammeln Sie Feedback von Ihren Benutzern, um eine Intuition für die Anwendungsfälle und Prompts zu entwickeln, die Ihre Tools ermöglichen sollen.

Eine Evaluation durchführen

Als nächstes müssen Sie messen, wie gut Claude Ihre Tools verwendet, indem Sie eine Evaluation durchführen. Beginnen Sie damit, viele Evaluations-Aufgaben zu generieren, die in realen Anwendungen begründet sind. Wir empfehlen die Zusammenarbeit mit einem Agenten, um Ihre Ergebnisse zu analysieren und zu bestimmen, wie Sie Ihre Tools verbessern können.

Sehen Sie diesen Prozess von Ende zu Ende in unserem Tool-Evaluations-Kochbuch.

Claude Code Evaluations-Workflow Der Aufbau eines Evaluationssystems mit Claude Code ermöglicht systematische Messung und Optimierung der Tool-Performance

Tool-Performance-Fallstudien

Durch systematische evaluationsgesteuerte Entwicklung erzielten wir signifikante Leistungsverbesserungen bei internen Tool-Tests:

Slack Tools Performance-Ergebnisse Vergleich der Held-out-Testset-Performance: von Menschen geschriebene vs. Claude-optimierte Slack MCP-Tools

Asana Tools Performance-Ergebnisse
Vergleich der Held-out-Testset-Performance für Asana MCP-Tools: zeigt signifikante KI-Optimierungseffekte

Evaluations-Aufgaben generieren

Mit Ihrem frühen Prototyp kann Claude Code schnell Ihre Tools erkunden und Dutzende von Prompt- und Response-Paaren erstellen. Prompts sollten von realen Anwendungen inspiriert sein und auf realistischen Datenquellen und Services basieren. Wir empfehlen, übermäßig vereinfachte oder oberflächliche “Sandbox”-Umgebungen zu vermeiden, die Ihre Tools nicht mit ausreichender Komplexität stressiges-testen.

Starke Evaluations-Aufgaben-Beispiele:

Planen Sie ein Meeting mit Jane nächste Woche, um unser neuestes Acme Corp Projekt zu besprechen. Hängen Sie die Notizen aus unserem letzten Projektplanungsmeeting an und reservieren Sie einen Konferenzraum.
Kunde ID 9182 berichtete, dass er dreimal für einen einzigen Kaufversuch belastet wurde. Finden Sie alle relevanten Log-Einträge und bestimmen Sie, ob andere Kunden vom selben Problem betroffen waren.
Kundin Sarah Chen hat gerade eine Kündigungsanfrage eingereicht. Bereiten Sie ein Retention-Angebot vor. Bestimmen Sie: (1) warum sie geht, (2) welches Retention-Angebot am überzeugendsten wäre, und (3) alle Risikofaktoren, die wir beachten sollten, bevor wir ein Angebot machen.

Schwächere Evaluations-Aufgaben-Beispiele:

Planen Sie ein Meeting mit [email protected] nächste Woche.
Durchsuchen Sie die Zahlungs-Logs nach purchase_complete und customer_id=9182.
Finden Sie die Kündigungsanfrage von Kunden-ID 45892.

Jeder Evaluations-Prompt sollte mit einer verifizierbaren Antwort oder einem Ergebnis gepaart werden. Ihr Verifikator kann so einfach wie ein exakter String-Vergleich zwischen Ground Truth und gesampelten Antworten sein, oder so fortgeschritten wie die Beauftragung von Claude, die Antwort zu beurteilen.

Die Evaluation durchführen

Wir empfehlen, Ihre Evaluation programmatisch mit direkten LLM-API-Aufrufen durchzuführen. Verwenden Sie einfache agentische Schleifen (while-Schleifen, die abwechselnde LLM-API- und Tool-Aufrufe umhüllen): eine Schleife für jede Evaluations-Aufgabe.

In den System-Prompts Ihrer Evaluations-Agenten empfehlen wir, Agenten anzuweisen, nicht nur strukturierte Response-Blöcke (für die Verifikation) auszugeben, sondern auch Reasoning- und Feedback-Blöcke. Agenten anzuweisen, diese vor Tool-Call- und Response-Blöcken auszugeben, kann die effektive Intelligenz von LLMs durch das Auslösen von Chain-of-Thought (CoT)-Verhalten erhöhen.

Ergebnisse analysieren

Agenten sind Ihre hilfreichen Partner beim Erkennen von Problemen und beim Bereitstellen von Feedback zu allem, von widersprüchlichen Tool-Beschreibungen bis hin zu ineffizienten Tool-Implementierungen und verwirrenden Tool-Schemas. Denken Sie jedoch daran, dass das, was Agenten in ihrem Feedback und ihren Antworten weglassen, oft wichtiger sein kann als das, was sie einschließen.

Beobachten Sie, wo Ihre Agenten ratlos oder verwirrt werden. Lesen Sie durch das Reasoning und Feedback (oder CoT) Ihrer Evaluations-Agenten, um raue Kanten zu identifizieren. Überprüfen Sie die rohen Transkripte (einschließlich Tool-Calls und Tool-Responses), um jedes Verhalten zu erfassen, das nicht explizit im CoT des Agenten beschrieben wird.

Mit Agenten zusammenarbeiten

Sie können sogar Agenten Ihre Ergebnisse analysieren und Ihre Tools für Sie verbessern lassen. Verketten Sie einfach die Transkripte Ihrer Evaluations-Agenten und fügen Sie sie in Claude Code ein. Claude ist ein Experte darin, Transkripte zu analysieren und viele Tools auf einmal zu refactoren.

Tatsächlich kam der meiste Rat in diesem Post vom wiederholten Optimieren unserer internen Tool-Implementierungen mit Claude Code. Wir verließen uns auf Held-out-Testsets, um sicherzustellen, dass wir nicht auf unsere “Training”-Evaluationen überanpassten.

Prinzipien für das Schreiben effektiver Tools

Die richtigen Tools für Agenten wählen

Mehr Tools führen nicht immer zu besseren Ergebnissen. Ein häufiger Fehler, den wir beobachtet haben, sind Tools, die lediglich bestehende Software-Funktionalität oder API-Endpunkte umhüllen—ob die Tools für Agenten geeignet sind oder nicht.

LLM-Agenten haben begrenzten “Kontext” (das heißt, es gibt Grenzen dafür, wie viele Informationen sie gleichzeitig verarbeiten können), während Computer-Speicher billig und reichlich vorhanden ist. Betrachten Sie die Aufgabe, einen Kontakt in einem Adressbuch zu suchen. Traditionelle Software-Programme können eine Liste von Kontakten einen nach dem anderen effizient speichern und verarbeiten, jeden überprüfend, bevor sie zum nächsten übergehen.

Wenn jedoch ein LLM-Agent ein Tool verwendet, das ALLE Kontakte zurückgibt und dann jeden einzelnen Token für Token durchlesen muss, verschwendet es seinen begrenzten Kontextraum für irrelevante Informationen. Der bessere und natürlichere Ansatz ist, zuerst zur relevanten Seite zu springen.

Wir empfehlen, einige durchdachte Tools zu erstellen, die spezifische wirkungsvolle Workflows ansprechen, die zu Ihren Evaluations-Aufgaben passen, und von dort aus zu skalieren.

Tools können Funktionalität konsolidieren und potenziell mehrere diskrete Operationen (oder API-Calls) unter der Haube handhaben. Zum Beispiel können Tools Tool-Responses mit verwandten Metadaten anreichern oder häufig verkettete, mehrstufige Aufgaben in einem einzigen Tool-Call behandeln.

Bessere Tool-Design-Beispiele:

Anstatt list_users, list_events und create_event Tools zu implementieren, erwägen Sie die Implementierung eines schedule_event Tools, das Verfügbarkeit findet und ein Event plant.
Anstatt ein read_logs Tool zu implementieren, erwägen Sie die Implementierung eines search_logs Tools, das nur relevante Log-Zeilen und etwas umgebenden Kontext zurückgibt.
Anstatt get_customer_by_id, list_transactions und list_notes Tools zu implementieren, implementieren Sie ein get_customer_context Tool, das alle kürzlichen & relevanten Informationen eines Kunden auf einmal zusammenstellt.

Ihre Tools mit Namespaces versehen

Ihre KI-Agenten werden potenziell Zugang zu Dutzenden von MCP-Servern und Hunderten verschiedener Tools erhalten—einschließlich derer von anderen Entwicklern. Wenn Tools sich in der Funktion überschneiden oder einen vagen Zweck haben, können Agenten verwirrt werden, welche sie verwenden sollen.

Namespacing (Gruppierung verwandter Tools unter gemeinsamen Präfixen) kann helfen, Grenzen zwischen vielen Tools abzugrenzen; MCP-Clients tun dies manchmal standardmäßig. Zum Beispiel kann das Namespacing von Tools nach Service (z.B. asana_search, jira_search) und nach Ressource (z.B. asana_projects_search, asana_users_search) Agenten helfen, die richtigen Tools zur richtigen Zeit auszuwählen.

Bedeutungsvollen Kontext von Ihren Tools zurückgeben

Tool-Implementierungen sollten darauf achten, nur hoch-signifikante Informationen an Agenten zurückzugeben. Sie sollten kontextuelle Relevanz über Flexibilität priorisieren und low-level technische Identifikatoren (zum Beispiel: uuid, 256px_image_url, mime_type) vermeiden. Felder wie name, image_url und file_type werden viel wahrscheinlicher die nachgelagerten Aktionen und Antworten der Agenten direkt informieren.

Agenten neigen auch dazu, mit natürlichsprachigen Namen, Begriffen oder Identifikatoren deutlich erfolgreicher umzugehen als mit kryptischen Identifikatoren. Wir haben festgestellt, dass das bloße Auflösen willkürlicher alphanumerischer UUIDs zu semantisch bedeutungsvollerem und interpretierbarerem Vokabular Claudes Präzision bei Retrieval-Aufgaben signifikant verbessert.

In einigen Fällen benötigen Agenten möglicherweise die Flexibilität, sowohl mit natürlichsprachigen als auch mit technischen Identifikator-Ausgaben zu interagieren, wenn auch nur um nachgelagerte Tool-Calls auszulösen (zum Beispiel search_user(name='jane') → send_message(id=12345)). Sie können beides ermöglichen, indem Sie einen einfachen response_format Enum-Parameter in Ihrem Tool bereitstellen, der Ihrem Agenten erlaubt zu kontrollieren, ob Tools "concise" oder "detailed" Antworten zurückgeben.

response_format.py

from enum import Enum

class ResponseFormat(Enum):
    DETAILED = "detailed"
    CONCISE = "concise"

Response-Format-Beispiele

Detaillierte Tool-Antwort (206 Token): Detaillierte Tool-Response-Beispiel

Prägnante Tool-Antwort (72 Token): Prägnante Tool-Response-Beispiel

Slack-Threads und Thread-Antworten werden durch eindeutige thread_ts identifiziert, die erforderlich sind, um Thread-Antworten abzurufen. thread_ts und andere IDs (channel_id, user_id) können aus einer "detailed" Tool-Response abgerufen werden, um weitere Tool-Calls zu ermöglichen, die diese benötigen. "concise" Tool-Responses geben nur Thread-Inhalt zurück und schließen IDs aus. In diesem Beispiel verwenden wir ~⅓ der Token mit "concise" Tool-Responses.

Tool-Responses für Token-Effizienz optimieren

Die Optimierung der Kontextqualität ist wichtig. Aber so ist auch die Optimierung der Quantität des Kontexts, der in Tool-Responses an Agenten zurückgegeben wird.

Wir schlagen vor, eine Kombination aus Paginierung, Bereichsauswahl, Filterung und/oder Kürzung mit sinnvollen Standard-Parameterwerten für alle Tool-Responses zu implementieren, die viel Kontext verbrauchen könnten. Für Claude Code beschränken wir Tool-Responses standardmäßig auf 25.000 Token.

Wenn Sie sich entscheiden, Responses zu kürzen, stellen Sie sicher, dass Sie Agenten mit hilfreichen Anweisungen lenken. Sie können Agenten direkt ermutigen, token-effizientere Strategien zu verfolgen, wie viele kleine und gezielte Suchen anstatt einer einzigen, breiten Suche für eine Wissensabruf-Aufgabe zu machen.

Response-Kürzung und Fehlerbehandlung-Beispiele

Gekürztes Response-Beispiel: Gekürztes Tool-Response-Beispiel Intelligente Führung von Agenten zu präziseren Suchen

Fehler-Response-Vergleich:

❌ Unhilfreiche Fehler-Response: Unhilfreiche Fehler-Response-Beispiel

✅ Hilfreiche Fehler-Response: Hilfreiche Fehler-Response-Beispiel

Tool-Kürzung und Fehler-Responses können Agenten zu token-effizienteren Tool-Use-Verhaltensweisen lenken (Verwendung von Filtern oder Paginierung) oder Beispiele korrekt formatierter Tool-Eingaben geben.

Prompt-Engineering Ihrer Tool-Beschreibungen

Wir kommen nun zu einer der effektivsten Methoden zur Tool-Verbesserung: Prompt-Engineering Ihrer Tool-Beschreibungen und -Spezifikationen. Da diese in den Kontext Ihrer Agenten geladen werden, können sie kollektiv Agenten zu effektiven Tool-Calling-Verhaltensweisen lenken.

Beim Schreiben von Tool-Beschreibungen und -Spezifikationen denken Sie daran, wie Sie Ihr Tool einem neuen Mitarbeiter in Ihrem Team beschreiben würden. Berücksichtigen Sie den Kontext, den Sie implizit mitbringen könnten—spezialisierte Query-Formate, Definitionen von Nischenterminologie, Beziehungen zwischen zugrundeliegenden Ressourcen—und machen Sie ihn explizit.

Mit Ihrer Evaluation können Sie die Auswirkungen Ihres Prompt-Engineerings mit größerer Sicherheit messen. Sogar kleine Verfeinerungen der Tool-Beschreibungen können dramatische Verbesserungen erzielen.

Vermeiden Sie Mehrdeutigkeit, indem Sie erwartete Eingaben und Ausgaben klar beschreiben (und mit strikten Datenmodellen durchsetzen). Insbesondere sollten Eingabeparameter eindeutig benannt werden: anstatt eines Parameters namens user, versuchen Sie einen Parameter namens user_id.

Praktische Anleitung

Tool-Entwicklungs-Workflow

Schneller Prototyp → 2. Benutzer-Testing → 3. Evaluation erstellen → 4. Tests durchführen → 5. Agent-Analyse → 6. Iterieren → 7. Wiederholen

Häufige Fallstricke zu vermeiden

Vermeiden Sie diese häufigen Fehler:

Ein Tool pro API-Endpunkt erstellen
Zu viele low-level technische Details zurückgeben
Vage oder sich überschneidende Tool-Namen verwenden
Tool-Beschreibungsqualität vernachlässigen
Tatsächliche Agent-Workflows nicht testen

Performance-Optimierungs-Tipps

Verwandte Funktionalität konsolidieren - Häufig verkettete Tools in einzelne Tools zusammenführen
Intelligente Defaults - Vernünftige Standardwerte für Parameter setzen
Fehlerbehandlung - Klare, umsetzbare Fehlermeldungen bereitstellen
Response-Formate - Sowohl detaillierte als auch prägnante Response-Modi unterstützen
Kontext-Management - Relevanz und Quantität der zurückgegebenen Informationen optimieren

Zusammenfassung

Das Erstellen effektiver Tools für Agenten erfordert eine Neuorientierung unserer Software-Entwicklungspraktiken von vorhersagbaren, deterministischen Mustern zu non-deterministischen.

Durch den iterativen, evaluationsgesteuerten Prozess, den wir in diesem Post beschrieben haben, haben wir konsistente Muster in dem identifiziert, was Tools erfolgreich macht:

Effektive Tools sind:

Absichtlich und klar definiert
Umsichtig mit Agent-Kontext
Kombinierbar in verschiedenen Workflows
Intuitiv für das Lösen realer Aufgaben

Während Agenten fähiger werden, werden sich die Tools, die sie verwenden, neben ihnen weiterentwickeln. Mit einem systematischen, evaluationsgesteuerten Ansatz zur Verbesserung von Tools für Agenten können wir sicherstellen, dass sowohl Tools als auch Agenten gemeinsam voranschreiten.