MCP Tool Schema Linter

Warum ein Agent das falsche Tool aufruft

Eine Model-Context-Protocol-Tool-Beschreibung ist keine Dokumentation für Menschen. Sie geht bei jeder Anfrage an das Modell und ist das einzige, woran das Modell entscheidet, ob es dieses Tool aufruft. Wenn ein Agent zu delete_branch statt zu list_branches greift, ist das fast nie ein Fehler im Agenten — es sind zwei Beschreibungen, die das Modell nicht auseinanderhalten konnte.

Füge oben deine MCP-Server-URL ein: Der Linter liest jede Tool-Definition, die dein Server bereitstellt, genau so, wie ein Agent sie erhält, und meldet, was die Auswahl unzuverlässig macht.

Was geprüft wird

• Fehlende oder zu dünne Beschreibungen — ein in drei Worten beschriebenes Tool gibt dem Modell nichts, woran es sich entscheiden könnte.
• Beschreibungen, die den Namen wiederholen — den Namen hat das Modell bereits. „Issues auflisten: listet Issues auf" trägt kein Signal bei.
• Undokumentierte Parameter — über Parameterbeschreibungen weiß das Modell, was in welches Feld gehört. Ohne sie schließt es vom Feldnamen und liegt daneben.
• Schemas ohne deklarierte Properties — ein Tool ohne deklarierte Eingaben nimmt an, was das Modell erfindet.
• Kein required-Array — dann wirkt jeder Parameter optional, das Modell lässt einen nötigen weg und bekommt einen Fehler zurück.
• Beschreibungen, die echten Kontext kosten — sie gehen bei jedem Turn mit, Ausschweifung ist also eine laufende Gebühr, keine einmalige.

Länger ist nicht besser

Das gehört ausdrücklich gesagt, weil der Reflex meist der falsche ist: Der Linter meldet zu lange Beschreibungen ebenso wie zu kurze. Tool-Definitionen werden mit jeder Anfrage erneut gesendet, ein zusätzlicher Absatz wird also bei jedem Turn jedes Gesprächs bezahlt — dauerhaft — ohne die Trefferquote zu verbessern. Ziel sind ein bis zwei konkrete Sätze: was das Tool tut und wann man es dem daneben vorzieht. Was deine aktuelle Tool-Liste kostet, zeigt dir der MCP Token Calculator.

Was der Bericht enthält

Einen Qualitäts-Score, jeden Befund samt betroffenem Tool und — wo eine Neuformulierung das Verhalten eines Modells wirklich ändern würde — eine vorgeschlagene Ersatzbeschreibung. Die Prüfungen selbst nutzen überhaupt kein Modell und laufen immer. Die Vorschläge schon, und dafür gibt es ein Monatsbudget, damit das Werkzeug kostenlos bleiben kann; ist es ausgeschöpft, sagt der Bericht das offen, und jeder Befund darüber gilt weiterhin.

Verwandte Tools und Anleitungen

• MCP Inspector — die vollständigen Schemas lesen, auf denen die Prüfung beruht.
• MCP Token Calculator — was diese Beschreibungen pro Anfrage kosten.
• MCP Security Scanner — dieselben Beschreibungen, geprüft auf untergeschobene Anweisungen statt auf Klarheit.
• MCP-Server mit Python bauen

Eine Beschreibung kann nicht zwei Lesern dienen

Eine auf Tool-Auswahl getrimmte Beschreibung wird knapp, konkret und maschinenorientiert — und damit nutzlos für einen Kunden, der verstehen will, was dein Server tut. Dieser Zielkonflikt ist real und löst sich nicht durch besseres Schreiben. MCP Showcase löst ihn, indem beides aus demselben Server entsteht: Deine schlanken Schemas gehen weiter an das Modell, während Interessenten ein Live-Playground mit lesbarer Dokumentation pro Tool bekommen, das sie im Browser wirklich ausprobieren können.