Tools designen, die Kunst der Beschreibung

Das unterschätzte Problem

Du hast Deinen MCP-Server geschrieben, alle Tools funktionieren, alles klappt. Aber Claude ruft sie nie auf.

Warum? Weil das Modell nicht weiss dass Deine Tools existieren, oder weil es nicht versteht was sie tun.

Die Tool-Beschreibung ist wichtiger als der Tool-Code. Der Code wird 10 Mal aufgerufen. Die Beschreibung wird vom Modell jedes Mal gelesen wenn es überlegt welches Tool es braucht.

Die drei Regeln für Tool-Namen

1. Verb + Objekt. get_customer ist besser als customer. send_email ist besser als email. Das Modell braucht das Verb um die Handlung zu verstehen.

2. Spezifisch, nicht generisch. get_stripe_customer ist besser als get_customer wenn Dein Server multi-source ist. fetch_latest_blog_post ist besser als fetch_data.

3. Consistent across Tools. Wenn Du get_X, list_X, create_X nutzt, bleib dabei. Nicht in einem Tool get_customer, im nächsten fetch_user, dann retrieve_account. Vereinheitliche.

Die Tool-Beschreibung

Das ist der wichtigste Text im ganzen Server. 1-3 Sätze, die erklären:

1. Was das Tool tut.
2. Wann man es benutzen soll (das vergessen die meisten).
3. Wann man es NICHT benutzen soll (noch mehr vergessen).

Beispiel, schlecht:

Gibt eine Liste von Kunden zurück.

Beispiel, gut:

Listet Kunden aus der CRM-Datenbank. Benutze dies wenn der User nach mehreren Kunden fragt oder eine Übersicht braucht. Für einen einzelnen spezifischen Kunden nutze get_customer stattdessen. Gibt maximal 100 Einträge zurück, pagination via offset-Parameter.

Der zweite Text hilft dem Modell zu entscheiden. Der erste ist reine Dokumentation.

Input-Schemas sind Teil der Beschreibung

Jeder Parameter sollte:

• Einen klaren Namen haben (customer_id, nicht id).
• Eine Description haben (Zod-Schema mit .describe(...) nutzen).
• Ein sinnvolles Default bekommen wenn optional.

Das Modell liest das Schema zusammen mit der Tool-Beschreibung. Unklare Parameter führen zu falschen Aufrufen.

Output-Design

Das Modell liest auch den Output. Zwei Regeln:

1. Kurzer Text wenn möglich, JSON wenn nötig. Simple Tools geben einen einzelnen Text-Block zurück:

"Customer Max Mustermann gefunden. Email: [email protected], Letzter Auftrag: 2025-11-15 (Produkt X, 250 EUR)."

Tools die strukturierte Daten liefern, geben JSON:

{"customers": [{"id":"123","name":"Max","email":"[email protected]","lastOrder":"2025-11-15"}]}

2. Fehler klar erklären. Bei Errors nicht {"error":"failed"}. Sondern:

"Konnte den Kunden nicht finden. Mögliche Gründe: ID ungültig, DB-Connection down. Versuch es mit `list_customers` um die richtige ID zu finden."

Das Modell entscheidet besser wenn es weiss WARUM etwas nicht ging.

Der MCP-Discovery-Hinweis

Bei stdio-Servern liest Claude beim Start die Tool-Liste. Bei HTTP-Servern kann man ausserdem einen globalen System-Prompt setzen, der erklärt WAS Dein Server kann. Das ist die "instructions" im Server-Setup:

const server = new Server(
  {
    name: "mein-crm-server",
    version: "0.1.0",
    description: "CRM-Integration. Bietet Zugriff auf Kunden, Deals, Interaktionen. Nutze für Sales-Workflows, nicht für Support-Tickets."
  },
  { capabilities: { tools: {} } }
);

Der Beschreibungs-Text wird dem Modell gezeigt wenn es überlegt welches Tool relevant ist. Nutze das.

Die finale Regel

Lies Deine Tool-Beschreibungen laut vor. Wenn sie sich wie Doku anhören, ist es schlecht. Wenn sie sich wie eine Gebrauchsanweisung für einen Kollegen anhören, ist es gut.

Nächste Lektion

Deployment. Von lokalem Server zu npm-Package, Cloud Run, oder MCPize. Wie Du von "läuft bei mir" zu "installierbar für andere" kommst.