Sie haben einen MCP-Server erstellt und die Tools funktionieren. Sobald Sie einen LLM-Agenten anbinden, beobachten Sie jedoch: Er ignoriert Tools, ruft sie mit ungeeigneten Parametern auf, verwechselt ihren Zweck oder verkettet sie in ungewöhnlichen Abfolgen.
Dies ist der Abstand zwischen „Tools, die existieren“ und „Tools, die LLMs korrekt verwenden“. Hier wird die meiste Arbeit an MCP-Servern verschwendet. Unternehmen entwickeln leistungsstarke Fähigkeiten, stellen sie als Tools bereit und beobachten, wie LLMs sie nicht effektiv nutzen.
Der entscheidende Perspektivwechsel: Behandeln Sie Tooldesign wie UX-Design, bei dem das LLM Ihr Nutzer ist. Die Toolbeschreibung ist die Oberfläche, das Schema das Formular und eine Fehlermeldung das Feedback. Sind diese Elemente gut gestaltet, arbeiten LLMs effektiv; sind sie schlecht gestaltet, bleibt Ihre komplexe Backend-Infrastruktur für den Agenten unsichtbar.
Dieser Artikel behandelt die Prinzipien, mit konkreten Beispielen für das, was funktioniert und was nicht.
Prinzip 1: Toolnamen vermitteln die Absicht
Der Toolname ist das Erste, was das LLM sieht. Er sollte die ausgeführte Aktion beschreiben.
Schlecht:
customers(Substantiv, keine Aktion)process_customer(vag)do_x(bedeutungslos)
Besser:
search_customers(klare Aktion)get_customer_by_id(spezifische Operation)update_customer_email(spezifische Änderung)
Warum das wichtig ist: LLMs durchsuchen Toollisten nach relevanten Funktionen. Ein aussagekräftiger Name hilft ihnen, das richtige Tool schnell zu erkennen. Ein vager Name zwingt sie, die Beschreibung sorgfältig zu lesen – was nicht immer geschieht.
Ein nützliches Muster sind standardisierte Verbpräfixe.
list_*,search_*,get_*für Lesen.create_*,update_*,delete_*für Schreiben.analyze_*,summarize_*für Berechnungen.
Konsistenz überall im Server hilft dem LLM, mentale Modelle aufzubauen.
Prinzip 2: Beschreibungen sind Prompts
Die Beschreibung des Tools ist der wichtigste Text in Ihrem Server. Sie wird vom LLM genutzt, um zu entscheiden, ob und wie das Tool verwendet werden soll.
Schlechte Beschreibung:
search_customers: Search the customer database.
Bessere Beschreibung:
search_customers: Find customers by name, email, or company. Returns up to 10 matching customers with their basic info. Use this when you need to identify a customer the user is referring to. For exact lookups by ID, use get_customer_by_id instead.
Beachten Sie, was die bessere Version tut:
- Beschreibt Eingaben („nach Namen, E-Mail oder Unternehmen“).
- Beschreibt Ausgaben („bis zu 10 passende Kunden mit ihren Grunddaten“).
- Gibt an, wann sie verwendet werden soll („wenn Sie einen Kunden identifizieren müssen, auf den der Benutzer sich bezieht“).
- Gibt an, wann sie nicht verwendet werden soll („Für exakte Suchen nach ID verwenden Sie get_customer_by_id stattdessen“).
Der Abschnitt „wann nicht verwenden“ ist entscheidend. Ohne ihn könnte das LLM search_customers aufrufen, obwohl get_customer_by_id geeigneter wäre.
Prinzip 3: Parameterbeschreibungen zählen
Jeder Parameter benötigt eine Beschreibung. Verlassen Sie sich nicht allein auf den Parameternamen.
Schlecht:
{
customer_id: string,
fields: string[]
}
Besser:
{
customer_id: string, // "The customer's unique identifier. Get this from search_customers or from explicit user input."
fields: string[] // "Specific fields to return. Available: name, email, phone, tier, created_at, last_active. If not specified, returns name and email."
}
Die Beschreibungen:
- Erklären dem LLM, wie der Wert erlangt werden kann.
- Spezifizieren zulässige Werte, wo anwendbar.
- Geben Standardwerte an.
Prinzip 4: Fehler leiten zur Wiederherstellung
Wenn ein Tool einen Fehler auslöst, leitet die Fehlermeldung den nächsten Schritt des LLMs. Vage Fehler führen zu verwirrten Agenten.
Schlechter Fehler:
{ "error": "Invalid input" }
Besserer Fehler:
{
"error": "validation_error",
"message": "The email '...' is not in a valid format. It must be like 'name@example.com'.",
"field": "email",
"suggestion": "Ask the user for a valid email address."
}
Das LLM weiß nun:
- Was schiefgelaufen ist (Validierungsfehler im E-Mail-Feld).
- Wie es behoben werden kann (Verwenden Sie ein gültiges E-Mail-Format).
- Was als nächstes getan werden soll (Frage an den Benutzer).
Vergleichen Sie das Verhalten eines Agenten mit den beiden Fehlern. Der erste könnte denselben Aufruf erneut versuchen (verschwendet), aufgeben (schlechte UX) oder eine falsche Eingabe erfinden. Der zweite führt zu einer sauberen Benutzerinteraktion.
Prinzip 5: Ausgaben prägen den nächsten Schritt
Die Ausgabe des Tools bestimmt, was der LLM als nächstes tut. Das Ausgabedesign beeinflusst das Verhalten des Agenten.
Schlechte Ausgabe für eine Suche:
[
{"id": "c1", "n": "John", "e": "john@..."},
{"id": "c2", "n": "Jane", "e": "jane@..."}
]
Bessere Ausgabe:
{
"customers": [
{"id": "c1", "name": "John Smith", "email": "john@example.com", "tier": "pro"},
{"id": "c2", "name": "Jane Doe", "email": "jane@example.com", "tier": "free"}
],
"total_found": 2,
"summary": "Found 2 customers matching 'john'. Note that one is named 'Jane Doe' but has 'john' in their email."
}
Die bessere Ausgabe:
- Verwendet lesbare Feldnamen.
- Enthält Meta-Kontext (
total_found). - Enthält eine natürliche Sprache
summary, die dem LLM hilft, zu verstehen, was als nächstes gesagt werden soll.
Das Zusammenfassungsfeld ist mächtig – es ist wie ein „übrigens“-Hinweis für den LLM, wie das Ergebnis interpretiert werden kann.
Prinzip 6: Ein Tool, ein Zweck
Tools, die mehrere Dinge tun, verwirren LLMs. Der LLM muss entscheiden, ob das Tool verwendet werden soll und in welchem Modus.
Verwirrend:
manage_customer:
- mode: "search" | "get" | "update" | "delete"
- params: depends on mode
Das LLM muss den Modus auswählen und trifft dabei häufig die falsche Wahl. Zudem ist das Parameterschema komplex, weil es je nach Modus variiert.
Besser: getrennte Tools.
search_customers: search by name/email/company
get_customer: get details by ID
update_customer: update specific fields
delete_customer: archive a customer
Jedes Tool ist eindeutig. Das LLM wählt es anhand der Absicht aus; die Schemata bleiben einfach.
Das bedeutet mehr Tools, aber jedes ist klarer. Der LLM verarbeitet 10 klare Tools besser als 3 mehrfachmodifizierte Tools.
Prinzip 7: Eingaben einschränken
Wo möglich, beschränken Sie die Eingabemöglichkeiten. Enumerations und Validierungen verhindern Halluzinationen des LLMs.
Lockere:
{
status: string // could be anything
}
Beschränkte:
{
status: "active" | "trial" | "churned" | "suspended"
}
Die Einschränkung wird auf Ebene des Schemas erzwungen (beschränkte Generierung verhindert, dass der LLM ungültige Werte erzeugt).
Das gilt ebenso für Enumerations von Operationen, Schweregraden, Typen – alles mit einer bekannten Menge an gültigen Werten.
Für Daten verwenden Sie das ISO 8601-Format und geben es in der Beschreibung an („Datum im ISO 8601-Format, z. B. 2026-05-15“). Ohne dies erzeugen LLMs Daten in zufälligen Formaten.
Prinzip 8: Standardwerte reduzieren Halluzinationen
Wenn Parameter sinnvolle Standardwerte haben, machen Sie sie optional mit dem Standardwert auf Serverseite angewendet.
Schlecht:
{
query: string,
limit: number, // LLM has to provide some value
include_archived: boolean,
sort_by: string
}
Das LLM muss Werte für alle Parameter wählen, die falsch sein können.
Besser:
{
query: string,
limit: number = 10, // sensible default
include_archived: boolean = false, // safe default
sort_by: "relevance" | "name" | "created_at" = "relevance" // most common
}
Das LLM gibt nur Parameter an, die für die konkrete Abfrage relevant sind. Weniger Parameter bedeuten weniger Fehlermöglichkeiten.
Dokumentieren Sie Standardwerte in der Beschreibung: „Limit: Anzahl der Ergebnisse, die zurückgegeben werden sollen. Standardwert 10, maximal 50.“
Prinzip 9: Komposition zählt
Tools sollten in Workflows komponierbar sein, die der LLM konstruieren kann. Die richtige Granularität macht komplexe Aufgaben einfach.
Betrachten Sie eine Aufgabe: „Erzählen Sie mir von allen offenen Issues für unsere Top 3 Kunden.“
Schlechte Tool-Set:
get_customer_summary(customer_id): returns customer + tickets + activity all in one
Der LLM kann den „Top 3“-Filter nicht leicht durchführen – dieses Tool gibt alles für einen Kunden gleichzeitig zurück. Um die Aufgabe zu erledigen, muss der LLM wissen, wer die Top-Kunden sind, und dann dieses Tool dreimal aufrufen.
Bessere Tool-Set:
list_customers(sort_by="value", limit=N): returns customer summaries with priority info
list_tickets(customer_id, status): returns tickets for a customer
Das LLM kann die Tools kombinieren: zuerst die wichtigsten Kunden auflisten, dann für jeden die offenen Tickets abrufen. Dieser Ablauf ist natürlicher.
Das Prinzip: Denken Sie an die Multi-Tool-Workflows. Tools, die gut komponierbar sind, sind nutzbar; Tools, die nicht, sind oft nicht.
Prinzip 10: Idempotenz wird kommuniziert
Für Schreibtools erwähnen Sie die Anforderungen an die Idempotenz in der Beschreibung:
create_invoice: Create a new invoice for a customer.
IMPORTANT: Pass an idempotency_key (a UUID you generate). If you retry this operation, use the same UUID to prevent duplicate invoices.
Parameters:
- amount: ...
- customer_id: ...
- idempotency_key: UUID to prevent duplicate creation on retry. Generate once per logical operation.
Nun weiß das LLM, dass es eine UUID erzeugen und bei einem erneuten Versuch wiederverwenden muss.
Ohne diese Anleitung könnte das LLM den Schlüssel auslassen oder bei jedem erneuten Versuch eine neue UUID erzeugen – beides untergräbt die Idempotenz.
Prinzip 11: Vor- und Nachbedingungen erwähnen
Für Tools mit Voraussetzungen oder wichtigen Nebenwirkungen erwähnen Sie dies:
delete_customer: Archive a customer record. This is reversible within 30 days; after 30 days, the data is permanently deleted.
PRECONDITIONS:
- Customer must have no active subscriptions.
- Customer must have no open tickets.
If preconditions are not met, this tool returns an error indicating what to resolve first.
SIDE EFFECTS:
- All customer's contacts are also archived.
- Customer is removed from active reports.
- An audit log entry is created.
Der LLM weiß jetzt, was vor dem Aufruf geprüft werden muss und was nach dem Aufruf erwartet wird. Er kann Multi-Schritt-Workflows korrekt planen („zuerst Tickets schließen, dann löschen“).
Prinzip 12: Bei Zweifeln Beispiele verwenden
Für komplexe Tools hilft ein Beispiel in der Beschreibung:
analyze_funnel: Analyze a conversion funnel from event data.
Parameters:
- start_date: ISO 8601 date
- end_date: ISO 8601 date
- steps: array of step definitions, each {event_name: string, filters?: object}
Example:
{
"start_date": "2026-01-01",
"end_date": "2026-01-31",
"steps": [
{"event_name": "signup"},
{"event_name": "first_login"},
{"event_name": "first_action", "filters": {"action_type": "create_project"}},
{"event_name": "subscription_started"}
]
}
Beispiele lehren den LLM die Struktur besser als Schemata allein.
Prinzip 13: Externe Details nicht preisgeben
Der LLM muss nicht wissen, Ihre Datenbankstruktur oder interne IDs. Oberflächen Sie ein sauberes konzeptionelles Modell.
Schlecht:
get_user_by_pk(pk: number)
Der LLM muss wissen, den „Primärschlüssel“ zu verwenden – ein Datenbankkonzept.
Besser:
get_user(user_id: string)
Verbergen Sie das Datenbankkonzept. Der LLM verwendet eine user_id, die ein sinnvolleres Konzept ist.
Ebenso: Exponieren Sie keine veralteten Felder, interne Flags, Debug-Parameter oder andere Dinge, die mit Ihrer Implementierung zu tun haben, statt mit dem Nutzerfokussierten Konzept.
Prinzip 14: Magische Strings vermeiden
Einige Tools erfordern Strings, die wie Befehle oder Codes aussehen. Diese sind fehleranfällig.
Schlecht:
modify_record(record_id: string, change_string: string)
// where change_string is like "field1=value1;field2=value2"
Der LLM muss Änderungen in einem spezifischen String-Format kodieren. Sie machen Fehler.
Besser:
update_record(record_id: string, updates: { field1?: any; field2?: any; ... })
Strukturierte Updates als Objekt. Der LLM kann jedes Feld direkt verwenden.
Prinzip 15: Mit echten LLMs testen
Tool-Beschreibungen lesen sich gut für Menschen, können aber LLMs verwirren. Der einzige Weg, das zu wissen, ist das Testen.
Ein nützlicher Workflow:
- Bauen Sie das Tool.
- Lassen Sie einen LLM-Agenten mehrere realistische Aufgaben mit nur Ihren Tools versuchen.
- Beobachten Sie Fehler.
- Passen Sie die Beschreibungen basierend auf den Fehlern an.
- Wiederholen Sie.
Die Muster, die Sie finden:
- LLM verwendet falsches Tool → Tool-Name oder -Beschreibung ist unklar.
- LLM übergibt falsche Parameterwerte → Parameter-Beschreibung oder -Schema benötigen Verbesserung.
- LLM gibt nach Fehlern auf → Fehlermeldungen benötigen Verbesserung.
- LLM verwendet kein nützliches Tool → Tool ist nicht sichtbar oder nicht gut benannt.
Jede dieser Probleme deutet auf eine spezifische Lösung hin.
Diagnose: Zeichen dafür, dass Ihre Tools nicht gut entworfen sind
Einige Muster, die auf Probleme im Tool-Design hinweisen:
Der LLM verwendet häufig das falsche Tool. Sie sehen, wie er search_customers aufruft, obwohl er get_customer_by_id hätte verwenden sollen. Lösung: Klarstellen, welches Tool für welche Situation verwendet wird.
Der LLM ruft viele Tools auf, um eine Sache zu erledigen. Er verkettet 5 Tool-Aufrufe, um etwas zu tun, was mit einem ausreichen würde. Lösung: Vielleicht benötigen Sie ein höheres, kompositives Tool oder die Granularität ist zu fein.
Der LLM gibt nach Fehlern auf. Er versucht einmal, erhält einen Fehler und sagt dem Benutzer, dass er nicht helfen kann. Lösung: Bessere Fehlermeldungen, die Vorschläge für den nächsten Schritt geben.
Das LLM erfindet Parameterwerte. Es erfindet Nutzer-IDs, Datumsangaben oder andere Kennungen. Lösung: Erklären Sie, wie gültige Werte zu beziehen sind, schränken Sie das Schema ein und fangen Sie ungültige Werte mit verständlichen Fehlermeldungen ab.
Der LLM wiederholt denselben fehlgeschlagenen Aufruf. Derselbe Fehler, wiederholt. Lösung: Die Fehlermeldung sagt dem LLM nicht spezifisch, was falsch ist.
Der LLM verwendet ein mächtiges Tool nicht. Sie haben ein großartiges Tool erstellt; der LLM ruft es nie auf. Lösung: Verbesserung der Entdeckbarkeit (klarere Namen, bessere Beschreibungen, „verwenden Sie dies, wenn…“-Anleitung).
Tool-Taxonomie
Ein nützliches Übung: Organisieren Sie Tools in eine Taxonomie.
Read tools (safe, idempotent):
- search_customers
- get_customer_by_id
- list_tickets
- list_orders
Compute tools (no state changes):
- summarize_account_activity
- analyze_funnel
- calculate_lifetime_value
Write tools (state changes, need idempotency):
- create_customer
- update_customer_email
- create_ticket
- send_email
Destructive tools (require careful authorization):
- delete_customer
- cancel_subscription
- archive_record
Die Taxonomie hilft Ihnen:
- Geeignete Schutzmechanismen anzuwenden, etwa Idempotenz und Bestätigung bei destruktiven Aktionen.
- Die Kategorien im Systemprompt für das LLM zu dokumentieren.
- Fehlende Tools erkennen (wenn eine Kategorie leer ist, benötigen Sie vielleicht eines?).
Ein nützlicher Ergänzung im System-Prompt:
Tool categories available:
- READ tools (safe to call): search_customers, get_customer_by_id, ...
- COMPUTE tools (no side effects): summarize_account_activity, ...
- WRITE tools (side effects, include idempotency_key): create_customer, ...
- DESTRUCTIVE tools (require human confirmation): delete_customer, ...
Before calling a WRITE or DESTRUCTIVE tool, confirm with the user.
Dies steuert, wie das LLM Tools auf Workflow-Ebene und nicht nur bei einzelnen Aufrufen verwendet.
Beispiele für häufige Verbesserungen
Um die Prinzipien konkret zu machen, Beispiele vor und nach:
Beispiel 1: Ein Suchtool
Vorher:
// search documents
{
name: "documents",
description: "Search documents",
inputSchema: { query: "string" }
}
Nachher:
{
name: "search_documents",
description: `Search internal documents (knowledge base, wiki pages, policies).
Returns matching documents with title, excerpt, and link. Use when the user asks about company policies, procedures, or internal documentation. Returns up to 10 most relevant matches by semantic similarity.`,
inputSchema: {
query: {
type: "string",
description: "Search query. Be specific. Good: 'remote work policy 2026'. Bad: 'documents about work'."
},
document_type: {
type: "string",
enum: ["policy", "procedure", "guide", "faq", "any"],
default: "any",
description: "Filter to a specific type of document."
},
limit: {
type: "number",
default: 5,
maximum: 10,
description: "Number of results."
}
}
}
Beispiel 2: Ein Aktionstool
Vorher:
{
name: "send_email",
description: "Send an email",
inputSchema: {
to: "string",
subject: "string",
body: "string"
}
}
Nachher:
{
name: "draft_email_to_customer",
description: `Draft an email to a customer based on a recent interaction. The email is saved as a draft for human review before sending — it is NOT sent automatically. The user must approve drafts in their inbox.
Use when:
- You've identified an action requiring follow-up with the customer.
- You have a specific reason and content for the email.
Do NOT use:
- To send marketing or promotional content.
- Without explicit user request.
- To respond to refund or cancellation requests (escalate to human instead).`,
inputSchema: {
customer_id: {
type: "string",
description: "Customer ID from search_customers or get_customer."
},
subject: {
type: "string",
description: "Email subject, 4-8 words, specific. Avoid generic subjects like 'Following up'."
},
body: {
type: "string",
description: "Email body, plain text. 3-5 sentences. Personal, specific, not template-y."
},
tone: {
type: "string",
enum: ["professional", "friendly", "apologetic", "urgent"],
default: "professional",
description: "Tone of the email."
},
idempotency_key: {
type: "string",
description: "UUID for this draft. Use the same UUID if retrying to avoid duplicates."
}
}
}
Die „Nachher“-Versionen leiten den LLM deutlich effektiver. Sie wirken umfangreich; sie sind es wert.
Die Schlussfolgerung
Das Tool-Design für LLMs ist eine eigene Disziplin. Die Prinzipien sind nicht intuitiv; sie erfordern, den LLM als Nutzer zu betrachten und entsprechend die Schnittstelle zu entwerfen.
Die Muster, die zählen:
- Aktion-Verb-Names.
- Reiche Beschreibungen, die erklären, was, wann und nicht wann.
- Parameterbeschreibungen mit Beispielen und Einschränkungen.
- Strukturierte, handlungsorientierte Fehlermeldungen.
- Ausgaben, die den nächsten Schritt leiten.
- Ein Tool pro Konzept.
- Sinnvolle Standardwerte.
- Kompositionsfähige Granularität.
- Explizite Idempotenz.
- Dokumentierte Vor- und Nachbedingungen.
- Beispiele für komplexe Tools.
- Versteckte Interna.
- Testen mit echten LLMs.
Die meisten MCP-Server scheitern nicht, weil das Protokoll schwierig ist, sondern weil die Tools nicht mit dem LLM im Blick entworfen wurden. Machen Sie das Tool-Design richtig und Ihr Server wird effektiv; machen Sie es falsch und Ihre komplexe Backend-Infrastruktur wird verschwendet.
Behandeln Sie den LLM als Nutzer. Entwerfen Sie entsprechend. Die Investition lohnt sich viele Male über, insofern Ihre Tools tatsächlich genutzt werden.
