MCP-Tool-Design: Lehren aus einem Jira-Server mit 20 Tools

MCP-Tool-Design ist die Arbeit, zu entscheiden, welche Tools ein Model-Context-Protocol-Server bereitstellt und wie jeder einzelne benannt, beschrieben, parametrisiert und beantwortet wird – damit ein Agent beim ersten Versuch das richtige Tool trifft und dabei so wenige Tokens wie möglich verbraucht. Das Protokoll bewegt nur die Aufrufe. Ob der Agent Erfolg hat, hängt fast vollständig an der Tool-Oberfläche, die du ihm gibst.

Ich habe einen Jira-MCP-Server mit 20 Tools geschrieben: Issues suchen, anlegen, ändern und transitionieren, Kommentare, Anhänge, Epics sowie Testfälle und Testläufe. Jira ist ein brauchbarer Testfall, weil seine REST-API breit und seine Daten verrauscht sind. Dieser Beitrag sammelt die Designregeln, auf die es am meisten ankommt, belegt mit den veröffentlichten Messungen von Anthropic und anderen: was Tool-Definitionen kosten, wann man Tools zusammenlegt, wie man sie benennt, was sie zurückgeben, wie sie Fehler melden und wie man das Ergebnis mit einem kleinen Eval prüft.

Was kosten MCP-Tool-Definitionen an Tokens?

Jede Tool-Definition wird in das Kontextfenster des Modells geladen, bevor der Agent deinen Prompt liest, ein großer Server kostet also in jedem Turn tausende Tokens. Gemessene Werte reichen von etwa 3.000 Tokens für einen schlanken 15-Tool-Server bis über 100.000 Tokens für eine große Multi-Server-Aufstellung.

Blocks.ai hat die Schema-Kosten mit dem Token-Counter von Claude Sonnet 4 gemessen, indem ein Request mit und ohne angehängte Tools verglichen wurde: Ein 15-Tool-Server kostete 3.185 Tokens, der GitHub-MCP-Server mit allen 85 aktivierten Tools 26.644. Anthronics Beitrag Advanced Tool Use (24. November 2025) nennt eine Aufstellung aus fünf Servern (GitHub, Slack, Sentry, Grafana, Splunk) mit etwa 55.000 Tokens und Tool-Definitionen, die vor der Optimierung im Großbetrieb 134.000 Tokens erreichen.

Teile die beiden Blocks.ai-Zahlen, und du landest bei rund 210 Tokens pro Tool für den schlanken Server und etwa 310 für GitHub. Die Kosten pro Tool sind nicht der eigentliche Hebel. Die Anzahl ist es. Zwanzig Tools sind eine vernünftige Größe für ein ganzes Produkt wie Jira; fünfundachtzig entstehen, wenn aus jedem Endpunkt ein Tool wird.

Sollen MCP-Tools die REST-API 1:1 abbilden?

Nein. Jeden REST-Endpunkt als Tool abzubilden ist der häufigste MCP-Designfehler: Es vervielfacht die Definitionen und zwingt den Agenten, Aufrufe auf niedriger Ebene zu verketteten. Baue Tools um die Aufgaben, die ein Agent erledigt, und lege Endpunkte zusammen, die immer zusammen benutzt werden.

Anthronics Writing effective tools for agents (11. September 2025) liefert die kanonischen Beispiele: Statt list_users, list_events und create_event baust du schedule_event; statt read_logs baust du search_logs, das nur relevante Zeilen zurückgibt; get_customer_by_id, list_transactions und list_notes werden zu get_customer_context zusammengelegt. Ein zusammengelegtes Tool kann mehrere API-Aufrufe unter der Decke machen.

Für einen Tracker wie Jira ist der Test konkret. Wenn ein Agent ein Ticket kommentiert, holt er dann immer zuerst das Ticket? Wenn er ein Ticket verschiebt, muss er dann wissen, welche Transitions erlaubt sind? Wo die Antwort „immer“ lautet, ist der zweite Aufruf ein Kandidat, um in das Ergebnis des ersten Tools gefaltet zu werden. Wo die Antwort „nur manchmal“ lautet, bleiben die Tools getrennt.

Der Seiteneffekt-Zweig ist so sehr eine Sicherheits- wie eine Genauigkeitsfrage. Eine reine Suche und ein Schreibzugriff, der den Status eines Tickets ändert, sollten getrennte Tools bleiben, damit ein Host eines automatisch freigeben und beim anderen einen Menschen fragen kann. Das ist dieselbe Grenze, die meine Agent-Skills an anderer Stelle ziehen: Menschen geben frei, was öffentlich oder unumkehrbar ist.

Wie benennt und beschreibt man MCP-Tools?

Benenne Tools mit einem Verb und einem Namensraum, den der Agent nicht mit den Tools eines anderen Servers verwechseln kann, und schreibe jede Beschreibung so, als würdest du einen neuen Kollegen einarbeiten: Was das Tool tut, wann man es einsetzt, was die Parameter bedeuten und was zurückkommt.

Die MCP-Tools-Spec verlangt Namen mit 1 bis 128 Zeichen aus Buchstaben, Ziffern, Unterstrich, Bindestrich und Punkt, innerhalb eines Servers eindeutig. Eindeutigkeit über Server hinweg ist nicht garantiert: Zwei Server können beide search anbieten, und die Clients sollen das selbst auflösen, etwa durch ein vorangestelltes Serverkürzel. Verlass dich nicht darauf, dass die Clients das gut machen. Anthropic berichtet, dass die Wahl zwischen Präfix- und Suffix-Namensraum (jira_search versus search_jira) „nicht triviale Auswirkungen“ auf ihre Tool-Use-Evaluierungen hatte – wähle eine Variante und teste sie.

Die Beschreibungen tragen das meiste Auswahlsignal. Anthropic schreibt, dass „schon kleine Verfeinerungen an Tool-Beschreibungen dramatische Verbesserungen bringen können“. In der Praxis heißt das:

• Sag, was das Tool zurückgibt, nicht nur, was es tut. Ein Agent wählt den nächsten Aufruf nach der erwarteten Ausgabe.
• Nenne die Query-Sprache oder das Format, wenn es eines gibt. Ein Suchtool, das JQL entgegennimmt, sollte das sagen und ein Beispiel zeigen.
• Verwende eindeutige Parameternamen: issue_key statt id, user_email statt user.
• Schreibe die Grenzen in die Beschreibung: Seitengröße, maximale Ergebniszahl, welche Felder editierbar sind.

// Illustrative tool definition (not copied from a real server)
{
  "name": "jira_search_issues",
  "description": "Search Jira issues with a JQL query, e.g. project = PROJ AND status = \"In Progress\". Returns up to `limit` issues with key, summary, status and assignee name. Use response_format \"detailed\" only when you need descriptions or custom fields.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "jql": { "type": "string", "description": "JQL query" },
      "limit": { "type": "integer", "description": "Max issues, default 20" },
      "response_format": { "type": "string", "enum": ["concise", "detailed"] }
    },
    "required": ["jql"]
  }
}

Was sollte ein MCP-Tool zurückgeben?

Gib das kleinste Ergebnis zurück, mit dem der Agent seinen nächsten Schritt gehen kann: menschenlesbare Felder statt interner IDs, standardmäßig ein knappes Format und bei großen Ergebnissen Paginierung oder Kürzung mit Anleitung.

Anthronics Guide zum Schreiben von Tools fand heraus, dass das Auflösen opaker alphanumerischer UUIDs in verständliche Sprache „Claudes Präzision deutlich verbessert“, und dass Felder wie name und file_type die nächste Aktion deutlich häufiger bestimmen als rohe Identifier. Sein ResponseFormat-Beispiel zeigt den Größenunterschied: Derselbe Slack-Thread kostete 206 Tokens in einem ausführlichen Format mit IDs und 72 Tokens in einem knappen, etwa ein Drittel. Bietet man beides an, mit knapp als Standard, kann der Agent IDs erst dann anfordern, wenn ein Folgeaufruf sie braucht.

Größenlimits sind nicht theoretisch. Claude Code begrenzt Tool-Antworten laut demselben Guide standardmäßig auf 25.000 Tokens. Eine Tracker-Suche, die vollständige Beschreibungen, Kommentar-Threads und jedes Custom Field zurückgibt, stößt in einem ausgelasteten Projekt an diese Grenze. Paginiere die Ergebnisse, wähle vernünftige Defaults, und wenn du kürzt, sage es im Ergebnis und erkläre dem Agenten, wie er an den Rest kommt (eine engere Query, die nächste Seite oder das ausführliche Format für ein Issue).

Wie sollen MCP-Tools Fehler melden?

Melde behebbare Probleme als Tool-Ausführungsfehler mit isError: true und einer Nachricht, die sagt, was falsch war und wie ein gültiger Aufruf aussieht. Das Modell kann dann seinen eigenen Aufruf korrigieren, statt aufzugeben oder blind neu zu versuchen.

Die MCP-Spec trennt zwei Arten von Fehlern. Protokollfehler (unbekanntes Tool, fehlerhafter Request) sind JSON-RPC-Fehler, aus denen Modelle seltener wieder herausfinden. Tool-Ausführungsfehler, etwa ein Validierungsfehler bei der Eingabe oder ein Fehler in der Geschäftslogik, gehören in das Tool-Ergebnis, und Clients sollten sie dem Modell durchreichen, damit es sich selbst korrigiert. Anthronics Guide sagt dasselbe von der anderen Seite: opake Fehlercodes und Stacktraces helfen nicht; konkrete, umsetzbare Nachrichten mit einem Beispiel für korrekte Eingabe schon.

Jira hat mir hier eine klare Lektion erteilt. Die API lehnt Wiki-Markup in manchen Feldern mit einem nackten HTTP 400 und ohne Erklärung ab. Ein Agent, der nur „400 Bad Request“ sieht, rät – oft, indem er denselben Payload erneut schickt. Die Lösung war doppelt: Inhalt als ADF (Atlassian Document Format) senden und nach einem Schreibzugriff das Ergebnis prüfen, indem man danach sucht, statt der Antwort zu glauben. Die allgemeine Regel für deinen eigenen Server: Übersetze Upstream-Fehler in Sätze, mit denen ein Agent etwas anfangen kann.

// Illustrative tool execution error
{
  "content": [{ "type": "text", "text": "Transition 'Done' is not available for PROJ-42 in status 'Open'. Allowed transitions: 'Start progress', 'Close'. Call again with one of these names." }],
  "isError": true
}

Wann reicht eine kleinere Tool-Liste nicht mehr? Tool Search, Code-Ausführung und Trade-offs

Wenn ein Agent auf hunderte Tools zugreifen muss, hält Konsolidierung allein den Kontext nicht klein. Verzögertes Laden (Tool Search) und Code-Ausführung laden Definitionen stattdessen bei Bedarf, um den Preis eines zusätzlichen Schritts und mehr bewegter Teile.

Anthronics Tool Search Tool markiert Tools mit defer_loading: true, sodass sie über Suche gefunden statt vorab geladen werden. In ihren Messungen senkte das den Token-Verbrauch um 85% und hob die Genauigkeit auf Opus 4 von 49% auf 74% und auf Opus 4.5 von 79,5% auf 88,1%. Tool-Use-Beispiele in den Definitionen hoben die Genauigkeit bei komplexen Parametern von 72% auf 90%. Ihr Beitrag Code execution with MCP (4. November 2025) geht weiter: Tools als Code auf einem Dateisystem dargestellt, ging bei einem Workflow von 150.000 auf 2.000 Tokens, eine Einsparung von 98,7%.

Die Trade-offs sind real. Zusammengelegte Tools verstecken Schritte, ein Workflow-Tool, das drei Dinge tut, braucht also für jedes davon eine klare Fehlermeldung. Tool Search kostet einen zusätzlichen Round-Trip und verfehlt das richtige Tool, wenn die Beschreibungen vage sind. Code-Ausführung braucht eine Sandbox, und die ist ein eigenes Sicherheitsprojekt (siehe Sandboxing für Coding-Agenten). Und manchmal ist gar nicht MCP die richtige Antwort: eine CLI plus eine Skill-Datei ist für lokale Arbeit oft günstiger. Ich vergleiche die Optionen in AGENTS.md, Skills, MCP oder CLI.

Wie man Tool-Auswahl misst: ein kleines Eval und eine Checkliste

Ob Agenten deine Tools richtig auswählen, findest du heraus, indem du realistische Aufgaben laufen lässt und prüfst, welche Tools mit welchen Argumenten aufgerufen wurden und ob die Aufgabe gelungen ist. Anthronics Guide zu Agent-Evals empfiehlt, mit 20 bis 50 Aufgaben aus echten Fehlfällen zu starten.

Anthropic empfiehlt, Eval-Aufgaben an echten Abläufen auszurichten, die mehrere Tool-Aufrufe brauchen, jeweils mit einem überprüfbaren Ergebnis und optional den erwarteten Tool-Aufrufen. Für einen Tracker-Server könnte eine Aufgabe lauten: „Verschiebe jeden offenen Bug im aktuellen Sprint, der mir zugewiesen ist, auf In Review und kommentiere den PR-Link.“ Nenne das Transkript auf und prüfe drei Dinge: die gewählten Tools, die Anzahl der Aufrufe und den Endzustand im Tracker. Ändere eine Beschreibung, lass es noch einmal laufen und vergleiche. Mehr zum Aufbau solcher Suiten in Evals für LLM-Features.

1. Zähle deine Tools und miss ihre Token-Kosten mit dem Token-Counter deines Modells, mit und ohne den Server.
2. Lege Operationen zusammen, die immer zusammen aufgerufen werden; halte Lesen und Schreiben in getrennten Tools.
3. Gib jedem Tool-Namen einen Namensraum und bleib im ganzen Server bei einer Konvention (Präfix oder Suffix).
4. Schreibe Beschreibungen, die die Ausgabe nennen, das Query-Format, die Grenzen und ein Beispiel.
5. Gib Namen zurück, keine UUIDs, mit knappem Standard und einer ausführlichen Option.
6. Paginiere und kürze mit Anleitung, deutlich unter dem Antwortlimit des Clients.
7. Mach aus Upstream-Fehlern umsetzbare isError-Ergebnisse und prüfe Schreibzugriffe, indem du sie zurückliest.
8. Halte tools/list in stabiler Reihenfolge, wie es die Spec 2026-07-28 inzwischen empfiehlt, damit die Caches der Clients gültig bleiben.
9. Führe nach jeder Beschreibungsänderung ein kleines Eval für die Tool-Auswahl aus.

Auch die Protokollseite bewegt sich; der MCP-2026-07-28-Migrationsleitfaden behandelt, wie Handles und Bestätigungen in die Tool-Schemas wandern, und die MCP-Server-Sicherheits-Checkliste, was schiefgehen kann, wenn die Tool-Beschreibungen selbst bösartig sind. Wenn du einen MCP-Server für dein eigenes Produkt designst, ist das die Art Arbeit, die ich als KI-Engineer mache.

Quellen

1. Writing effective tools for agents – with agents – Anthropic, 11. September 2025
2. Introducing advanced tool use on the Claude Developer Platform – Anthropic, 24. November 2025
3. Code execution with MCP – Anthropic, 4. November 2025
4. MCP vs CLI: context window cost – Blocks.ai
5. Demystifying evals for AI agents – Anthropic, 9. Januar 2026
6. MCP 2026-07-28 specification: Tools