---
title: "Tools designen, die Kunst der Beschreibung — StudioMeyer Academy"
description: "Warum 80% der MCP-Server ignoriert werden. Tool-Design entscheidet ob das Modell Dich findet."
canonical: "https://studiomeyer.academy/lernwege/fuer-entwickler/lektionen/03-tool-design"
language: de
image: "https://studiomeyer.academy/og/academy-og-share.png"
publisher: "StudioMeyer Academy, https://studiomeyer.academy (llms.txt: https://studiomeyer.academy/llms.txt)"
---

## 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 weiß 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: max@example.com, Letzter Auftrag: 2025-11-15 (Produkt X, 250 EUR)."
```

Tools die strukturierte Daten liefern, geben JSON:

```json
{"customers": [{"id":"123","name":"Max","email":"max@example.com","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 weiß WARUM etwas nicht ging.

## Der MCP-Discovery-Hinweis

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

```typescript
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.

Du kannst alle Inhalte frei lesen. Mit einem Konto bleibt dein Fortschritt gespeichert.

[Anmelden](https://studiomeyer.academy/login?next=%2Flernwege%2Ffuer-entwickler%2Flektionen%2F03-tool-design)

Für Entwickler · Modul 1 von 1

## Für Entwickler

[Zum Lernweg](https://studiomeyer.academy/lernwege/fuer-entwickler)

## Deine Notizen

Melde Dich an, um Deine eigenen Notizen zu dieser Lektion zu speichern.

[Anmelden](https://studiomeyer.academy/login?next=%2Flernwege%2Ffuer-entwickler%2Flektionen%2F03-tool-design)

## Sitemap

Öffentliche Seiten dieser Website als Markdown: [Sitemap](https://studiomeyer.academy/sitemap.md). Kuratierter Einstieg: [llms.txt](https://studiomeyer.academy/llms.txt), Volltext: [llms-full.txt](https://studiomeyer.academy/llms-full.txt).