amplitude/builder-skills

MCP-Server analysieren — Absichts- und Fehleranalyse

Erstellen Sie einen Bericht, der drei Fragen zu einem MCP-Server beantwortet, der mit dem Amplitude MCP Analytics SDK instrumentiert ist:

1. Welche Tools werden genutzt und welche schlagen fehl? (Tool-spezifisches Volumen + Fehlerrate)
2. Was versuchen die Aufrufer mit jedem Tool zu erreichen, und wo scheitert welche Absicht? (Begründungen innerhalb eines Tools × Fehlermeldung)
3. Was sollte das Team zuerst reparieren? (Korrekturen, die auf Fehlerbelegen basieren, nicht auf Bauchgefühl)

Der Kern dieser Analyse, der sie wertvoll macht: Das Tool lokalisiert die Korrektur; die Begründung erklärt die Absicht dahinter. Eine Gesamtfehlerrate besagt „4,5 % der Aufrufe schlagen fehl.“ Aufgeschlüsselt nach Tool sagt sie „query_chart schlägt in 22 % der Fälle fehl“ – jetzt wissen Sie, was Sie öffnen sollen. Wenn Sie die Begründungen innerhalb dieses Tools hinzufügen, heißt es „Die Fehler sind auf Dashboard-Aktualisierungs-Agents zurückzuführen, die das Batch-Limit erreichen“ – jetzt wissen Sie, warum, und die Korrektur ergibt sich von selbst. Die Begründung ist weitgehend Tool-spezifisch (jedes Tool hat seinen eigenen Grund für den Aufruf). Daher ist das Tool die primäre Achse und die Begründung der zweite Schnitt darin – eine globale Clusterung der Begründungen würde nur die Tool-Grenzen neu ableiten und dabei nicht vergleichbare Absichten vermischen.

Voraussetzungen

• Amplitude MCP Connector ist aktiv. Wenn nicht, stoppen Sie und bitten Sie den Benutzer, den Amplitude Connector in seinen Tool-/Connector-Einstellungen hinzuzufügen – es gibt keine alternative Datenquelle.

• Ein Projekt, das die Ereignisse des SDKs enthält. Das SDK sendet SDK-eigene Standardereignisse, die alle mit [MCP] präfixiert sind, und – entscheidend – jede Standardeigenschaft, die sie enthalten, ist ebenfalls mit [MCP] präfixiert, sie können aber auch benutzerdefinierte Eigenschaften haben.

  Ereignisse:

  • [MCP] Tool Call Response – das Arbeitstier: ein Ereignis pro Tool-Aufruf, der einen Tool-Callback erreicht hat (Erfolg oder Fehler).
  • [MCP] Tool Call Rejected – ein tools/call, das bevor ein Tool ausgeführt wurde, fehlgeschlagen ist (unbekanntes/deaktiviertes Tool, Eingabeschema-Validierung). Hier landen halluzinierte/falsch geschriebene Tool-Namen, getragen von [MCP] Attempted Tool Name (außerhalb des reservierten [MCP] Tool Name).
  • [MCP] Session Initialized, [MCP] Session Ended, [MCP] Tools Listed.

  Schlüsseleigenschaften von [MCP] Tool Call Response: [MCP] Tool Name, [MCP] Client Name, [MCP] Client Version, [MCP] Session ID, [MCP] Auth Type, [MCP] Rationale, [MCP] Is Error, [MCP] Error Message, [MCP] Error Type (returned_error vs. thrown_exception – unterscheidet ein Tool, das einen Fehler gemeldet hat, von einem, das abgestürzt ist), [MCP] Response Duration, [MCP] Response Size, [MCP] Request Size.

• Ereignis-/Eigenschaftsnamen können zwischen SDK-Versionen abweichen. Gehen Sie nie von etwas aus – überprüfen Sie sie mit den Taxonomie-Tools in Phase 0. Die kanonischen Namen oben stammen aus der constants.ts des SDKs (EVENT_PROPERTY_KEYS); wenn die Projektdaten widersprechen, vertrauen Sie dem Projekt und passen Sie sich an.

Phase 0 – Daten lokalisieren und validieren

1. Rufen Sie das Amplitude-Kontext-Tool (ohne projectId) auf, um Projekte aufzulisten. Wenn es mehr als ein plausibles Projekt gibt und der Benutzer keins angegeben hat, fragen Sie nach.
2. Bestätigen Sie, dass die [MCP]-Ereignisse im ausgewählten Projekt existieren (Ereignisse suchen oder auflisten; get_events filtert nur nach exaktem Namen, verwenden Sie daher die Suche für die [MCP]-Präfix-Erkennung).
3. Rufen Sie die Ereigniseigenschaften für [MCP] Tool Call Response (und [MCP] Tool Call Rejected) ab, um die genauen Eigenschaftsnamen zu bestätigen – denken Sie daran, sie sind mit [MCP] präfixiert und in Title Case (z. B. [MCP] Rationale, nicht tool rationale). Binden Sie das, was Sie finden, an die in den folgenden Abfragen verwendeten Namen.
4. Führen Sie eine Volumen-/Aktualitätsabfrage durch: Gesamtsummen von [MCP] Tool Call Response, [MCP] Session Initialized in den letzten 60 Tagen, wöchentliches Intervall. Dies gibt Ihnen das nutzbare Datumsfenster und zeigt, ob genügend Daten vorhanden sind. Bei weniger als ~5k Tool-Aufrufen insgesamt warnen Sie den Benutzer, dass die Aufschlüsselungen pro Tool dünn und Prozentsätze instabil sein werden – fahren Sie trotzdem fort, aber sagen Sie es im Bericht.

Notieren Sie: Projekt-ID, Datumsfenster, gesamtes Anrufvolumen. Jede spätere Abfrage verwendet denselben Bereich, sodass die Zahlen vergleichbar bleiben.

Phase 1 – Aufschlüsselung nach Tool (das Rückgrat)

Dies ist die primäre Karte; alles andere taucht tiefer ein.

• Volumen nach Tool: Gesamtsummen von [MCP] Tool Call Response, gruppiert nach [MCP] Tool Name, groupByLimit ~100.
• Fehler nach Tool: dasselbe, plus Filter [MCP] Is Error is "true".
• Abgelehnte Aufrufe nach versuchtem Namen: Gesamtsummen von [MCP] Tool Call Rejected, gruppiert nach [MCP] Attempted Tool Name. Diese erreichen nie einen Callback, sind also für die beiden obigen Abfragen unsichtbar – aber ein versuchter Name mit hohem Volumen, der kein echtes Tool ist, ist einer der umsetzbarsten Befunde (eine Umbenennung oder Halluzination, die Agents immer wieder erraten).

Berechnen Sie pro Tool Anrufvolumen, Fehleranzahl und Fehlerrate und ordnen Sie die Tools auf zwei Arten: nach Anrufvolumen (was lasttragend ist) und nach Fehlervolumen (was die meisten Fehler verursacht). Wählen Sie die Top 3–5 Tools für die tiefergehende Analyse aus – bevorzugen Sie hohes Fehlervolumen, nicht nur hohen Traffic, und berücksichtigen Sie die Wahl des Benutzers, wenn er bestimmte Tools genannt hat. Ein Tool mit geringem Traffic und einer Fehlerrate von 90 % kann ein ausgelastetes, gesundes Tool übertrumpfen.

Phase 2 – Begründungen innerhalb jedes Top-Tools (das „Warum“)

Für jedes Top-Tool sampeln Sie seine Begründungen – Gesamtsummen von [MCP] Tool Call Response, gruppiert nach [MCP] Rationale, gefiltert auf dieses eine Tool ([MCP] Tool Name is "<tool>"), groupByLimit ~150. Lesen Sie sie dann und gruppieren Sie sie nach dem, was der Aufrufer mit diesem Tool erreichen möchte, nicht nach der Formulierung. Leitfaden:

• Innerhalb eines einzelnen Tools finden Sie normalerweise 2–5 Absichtsgruppen, nicht neun – das Tool grenzt den Zweck bereits ein. Benennen Sie sie nach der Absicht (z. B. für ein query_chart-Tool: „Live-Dashboard-Aktualisierung“, „Ad-hoc-Erkundung“, „Geplante Berichtserstellung“).
• Gewichten Sie nach Anrufvolumen (jeder Begründungswert trägt seine Gesamtsumme), nicht nach eindeutigen Zeichenfolgen.
• Achten Sie auf eine Junk-Gruppe: „Platzhalter“, „ignorieren“, „noop“, „test“, „dummy“, einzelne Buchstaben. Ihre Größe ist ein Befund zur Begründungshygiene, und Junk darf nicht in echte Absichten eindringen.
• Begründungen wie „Wiederholung nach Ratenlimit“ / „Wiederholung von X“ signalisieren Wiederholungsschleifen – vermerken Sie sie.
• Nicht-englische Begründungen sind normal; gruppieren Sie sie nach Bedeutung.
• Berechnen Sie die Begründungsabdeckung pro Tool (Anteil der Tool-Aufrufe mit einer nicht leeren Begründung). Wenn sie niedrig ist (<50 %), beschreiben die Absichten nur einen Ausschnitt – sagen Sie das, und „Verbesserung der Begründungsabdeckung zum Zeitpunkt der Instrumentierung“ wird selbst zu einer Empfehlung.
• Berechnen Sie den Top-Absichtsanteil pro Tool (die größte Absichtsgruppe als % der begründungsgedeckten Aufrufe des Tools). Dies ist das Konzentrationssignal: ~90 % bedeutet, dass das Tool einen Job erfüllt, und Sie können hart dafür optimieren (Schema/Beschreibung für diesen Pfad verschärfen); eine flache Streuung (Top-Absicht ~30 %) bedeutet, dass das Tool überlastet ist und eine Aufteilung verdient, oder seine Fehler werden auf nicht zusammenhängende Absichten verteilt sein. Geben Sie die Zahl an, und wenn die Top-Absicht dominant ist, nennen Sie sie neben dem Tool.

Toolübergreifende Workflows (sekundär): Einige Begründungen beschreiben ein toolübergreifendes Ziel („Chart-ID auflösen, bevor das Dashboard aktualisiert wird“). Wenn eine einzelne Absicht eindeutig Tools überspannt (z. B. search_events → create_chart → create_dashboard), heben Sie sie als Workflow im querschnittlichen Abschnitt hervor – es ist das Einzige, was eine reine Tool-für-Tool-Ansicht übersieht.

Phase 3 – Fehler-Drilldown pro Tool

Führen Sie für jedes Top-Tool aus (gefiltert auf dieses Tool + [MCP] Is Error is "true"):

• Gruppiert nach [MCP] Error Message → warum es fehlschlägt
• Optional aufgeteilt nach [MCP] Error Type (returned_error vs. thrown_exception), wenn eine Nachricht mehrdeutig ist – ein Absturz und eine wohlgeformte Ablehnung setzen beide [MCP] Is Error, aber nur einer ist ein Fehler im Tool.

Wenn ein Tool eine dominante Absichtsgruppe aus Phase 2 hat, qualifizieren Sie die Fehler nach Begründung (fügen Sie den contains-Filter für die Begründung hinzu), um den Satz „diese Absicht scheitert auf diese Weise“ zu erhalten.

Klassifizieren Sie jede signifikante Fehlermeldung in einen Archetyp – der Archetyp bestimmt die Korrektur:

Archetyp	Signatur	Korrekturmuster
Veralteter/halluzinierter Tool-Name	[MCP] Tool Call Rejected mit [MCP] Attempted Tool Name = ein umbenannter oder plausibel klingender Tool	Serverseitige Aliase für umbenannte Tools; Ablehnungsantworten, die den nächsten echten Tool nennen, damit Agents sich in einem Zug selbst korrigieren
Fehlender erforderlicher Parameter	Validierungsfehler, "Required", Pfad nennt einen Parameter	Schema lockern (Einzelwert oder Array akzeptieren, Standardwerte hinzufügen) oder die Tool-Beschreibung so gestalten, dass Agents die Anforderungen vor dem Start korrekt verstehen
Schemaform-Mismatch	„Expected object, received string“ usw.	Serverseitige Umwandlung oder ein Inline-Beispiel in der Tool-Beschreibung hinzufügen
Hartes Limit-Kollision	„Maximum of N …“, „too_big“	Limit erhöhen, serverseitig automatisch chunken oder das Limit in der Parameterbeschreibung angeben – Agents lernen Limits derzeit nur durch Fehlschläge
Bereichs-/Aufbewahrungsverletzung	„time range too large“, „does not retain data before …“	Automatische Umwandlung (z. B. Granularität herabsetzen) anstatt einen Fehler zu werfen; Aufbewahrungs-/Bereichslimits im Kontext-Payload bekannt geben
Henne-Ei-Parameter	Ein Kontext-/Ermittlungs-Tool erfordert genau die ID, die es bereitstellen soll	Ermittlungs-Tools mit null erforderlichen Argumenten arbeiten lassen, standardmäßig aus dem Auth-Token
Berechtigung verweigert	Rollen-/Berechtigungssprache	Eigene Fehlerklasse, damit „nicht erlaubt“ von „kaputt“ trennbar ist; oft auch eine Dokumentations-/Onboarding-Lücke
Wiederkehrender geplanter Fehler	Dieselbe Nachricht, die sich täglich auf demselben Tool wiederholt	Den Aufrufer des Jobs reparieren, falls intern; für das Produkt als leise degradierende Automatisierung kennzeichnen – niemand beobachtet ein Chat-Fenster
Transient/Upstream	5xx, Timeouts, Ratenlimits	Wiederholungs-Hinweise im Fehlertext; prüfen, ob Wiederholungen tatsächlich stattfinden (siehe Schleifentrichter)

Die besten Fehlermeldungen geben die Korrektur an („erneut ausführen mit start >= …“). Halten Sie jede hochvolumige Fehlermeldung an diesen Standard – „Machen Sie diesen Fehler so umsetzbar wie Ihren besten“ ist oft eine legitime Empfehlung.

Phase 4 – Optionale Kontextmetriken

Fügen Sie hinzu, wenn es die Zeit erlaubt; sie schärfen die Geschichte:

• Wiederholungsfehler-Schleife: 3-stufiger Trichter, jede Stufe [MCP] Tool Call Response mit [MCP] Is Error is "true", [MCP] Tool Name konstant haltend, ~1h Konvertierungsfenster. Zeigt, welcher Anteil der fehlernden Benutzer sich in Schleifen auf demselben Tool spiralförmig bewegt. (Die Schritte müssen keine aufeinanderfolgenden Ereignisse sein – sagen Sie „3+ Fehler auf demselben Tool innerhalb einer Stunde“, nicht „3 aufeinanderfolgende“.)
• Fehler → Erholung: 2-stufiger Trichter, Fehler dann Erfolg, Tool-Namen konstant haltend. Hohe Erholung + hohe Schleifenrate bedeuten zusammen, dass die Kosten in verschwendeten Tokens/Latenz liegen, nicht in Aufgabe – eine grundlegend andere Schlussfolgerung.
• Client-Mix: Eindeutige, gruppiert nach [MCP] Client Name. Großer „unbekannter“ Anteil oder fast identische Client-Namen (Groß-/Kleinschreibung, Plugin-präfixierte Varianten) sind Instrumentierungsbefunde, die es wert sind, berichtet zu werden.

Phase 5 – Überprüfen, dann schreiben

Überprüfen Sie vor dem Schreiben mindestens eine Hauptzahl auf einem zweiten Weg (z. B. Gesamtfehlerrate über eine separate Abfrage der Gesamtsummen zweier Ereignisse). Berechnen Sie jeden Prozentsatz, den Sie angeben, aus Rohsummen neu. Wenn eine Zahl nicht überprüft werden kann, streichen Sie sie oder kennzeichnen Sie sie als Schätzung.

Berichtsstruktur

Verwenden Sie diese Vorlage – organisiert zuerst nach Tool:

# MCP-Server-Analyse – <Server-/Projektname>

Daten: <Projekt>, <Datumsfenster>, <N> Tool-Aufrufe, Gesamtfehlerrate <X>%.
Methodenhinweis: Tool-Aufschlüsselungen sind exakte Abfrageergebnisse; absichtsbezogene Tool-Intents werden modellbasiert aus Begründungen abgeleitet (richtungweisend). Namen abgelehnter Aufrufe stammen von [MCP] Tool Call Rejected.

## Tools auf einen Blick
<table: Tool | Aufrufe | Fehler | Fehlerrate | Top-Absicht (Anteil %) | Begründungsabdeckung>
<eine Zeile zu abgelehnten/versuchten Tool-Namen, falls relevant; Junk-Begründungen nennen, falls relevant>

## Tiefergehende Analyse: Top 3–5 Tools (sortiert nach Fehlervolumen)
Für jedes Tool:
**Tool: <Name> — <Aufrufe>, <Fehlerrate> — wofür es ist: <ein Satz>**
- Absichten (Begründungen innerhalb dieses Tools): <Gruppe: Anteil>, …
- 1–4 nummerierte Empfehlungen. Jede enthält den Nachweis (Fehlermeldung + Anzahl),
  den Archetyp und die konkrete Korrektur. Beginnen Sie mit der Korrektur, die das meiste Fehlervolumen beseitigt.

## Querschnittliche Befunde
<Toolübergreifende Workflows, Schleifen-/Erholungsraten, Client-Namen-Hygiene, Begründungshygiene, interner Test-Traffic, …>

## Die Kernaussage in einem Satz
<die einzelne Änderung, die das meiste Fehlervolumen beseitigt, mit ihrer Zahl>

Stil: Zahlen neben jeder Behauptung; nennen Sie die Fehlermeldungen wörtlich (gekürzt), damit Ingenieure danach grep können; Empfehlungen als Handlungen formuliert („Alias für query_chart → query_charts ausliefern“), nicht als Beobachtungen („Tool-Namensgebung könnte verbessert werden“).

Diagramme in der Ausgabe

Rendern Sie unterstützende Amplitude-Diagramme, wo der Client dies unterstützt, indem Sie die Ad-hoc-Diagrammabfrage- und Render-Tools verwenden (eine eventsSegmentation/funnels-Definition erstellen, dann rendern). Seien Sie bewusst, was ein Diagramm sein kann und was nicht:

• Als Diagramm darstellbar – alles, was auf Abfragen basiert. Dies sind echte Amplitude-Segmentierungs-/Trichterergebnisse, rendern Sie sie also: Aufrufe und Fehler nach Tool (gruppiert nach [MCP] Tool Name), Fehlerrate im Zeitverlauf, abgelehnte Aufrufe nach [MCP] Attempted Tool Name, die Wiederholungsfehler-Schleife und Erholungstrichter pro Tool sowie Client-Mix nach [MCP] Client Name. Die Tool-Aufschlüsselung ist das natürliche Hauptdiagramm.
• Nicht als Diagramm darstellbar – die absichtsbezogenen Gruppen innerhalb eines Tools. Die Gruppierung von Begründungen in Absichten erfolgt in diesem Modell; diese Gruppierungen existieren nicht als Amplitude-Eigenschaft, daher gibt es kein gespeichertes Diagramm für „Aufrufe nach Absicht.“ Stellen Sie Absichten als Tabelle dar, die aus den Begründungssummen erstellt wurde, und sagen Sie klar, dass die Absichtszahlen modellbasiert sind (richtungweisend), während die Diagramme, die Sie rendern, exakte Abfrageergebnisse sind. Tun Sie nicht so, als ob ein gerendertes Diagramm die Absichtsgruppierung stützt.

Abfrage-Kochbuch

Alle Abfragen sind eventsSegmentation- oder funnels-Definitionen gegen die Projekt-ID aus Phase 0. Passen Sie Ereignis-/Eigenschaftsnamen an das an, was Phase 0 verifiziert hat. Formen, von denen bekannt ist, dass sie funktionieren:

Tool-Aufschlüsselung (Phase 1):

{"type":"eventsSegmentation","app":"<PROJECT_ID>","name":"[MCP] Calls by Tool",
 "params":{"range":"Last 30 Days",
  "events":[{"event_type":"[MCP] Tool Call Response",
    "group_by":[{"type":"event","value":"[MCP] Tool Name"}]}],
  "metric":"totals","countGroup":"User","groupBy":[],"int

...(gekürzt zur Übersetzung)