Explorer les clusters d'intentions MCP

Le clustering d'intentions prend les valeurs libres $mcp_intent que les agents attachent à leurs appels d'outils, les intègre, et groupe les objectifs sémantiquement similaires en clusters. L'attribution se fait par appel : chaque appel est crédité à sa propre intention (les appels sans en avoir héritent de l'intention la plus récente dans la même session), donc les compteurs d'un outil reflètent l'intention qu'il a réellement servie. Chaque cluster porte sa distribution d'outils, ses comptages d'appels et ses taux d'erreur — répondant à « que cherchent les gens à faire, et ça marche-t-il ? » plutôt qu'à « quel outil a été appelé ». Le snapshot porte aussi un pivot centré sur les outils répondant à la question inverse : pour un outil donné, quelles intentions font son usage, à quelle fréquence les agents le trouvent-ils, et avec quoi est-il en concurrence ?

Contrairement à la qualité des outils et aux sessions (qui agrègent finalement $mcp_tool_call), le clustering nécessite des embeddings et n'est pas expressible en SQL. Il est servi par deux outils typés soutenus par un snapshot stocké.

Outils

Workflow : lire les clusters actuels

posthog:mcp-analytics-intent-clusters-retrieve
{}

Retourne un snapshot avec status, last_computed_at, computed_with (le modèle d'embedding, les paramètres de clustering et les pourcentages de couverture d'échantillon), un tableau clusters, un tableau tools (le pivot outil), et tool_overlaps. Chaque cluster a un label, intent_count, call_count, error_count, error_rate_pct, routing_entropy, une tool_distribution (quels outils cette intention route, avec les taux d'erreur par outil), sample_intents, plus switches (appel erroné immédiatement suivi d'un outil différent pour la même intention — la plus forte preuve « les agents confondent ces outils ») et self_retries (appel erroné immédiatement retesté avec le même outil — un signe que les messages d'erreur de l'outil n'aident pas les agents à s'autocorriger).

Lisez les clusters par call_count pour « que font surtout les agents », ou par error_rate_pct pour « quels objectifs échouent » — un taux d'erreur élevé sur un cluster pointe une classe d'objectifs d'agents que les outils servent mal.

routing_entropy est à quel point l'usage des outils d'un cluster est dispersé : une entropie faible signifie qu'un objectif mappe de manière fiable à un outil ; une entropie élevée signifie que les agents cherchent l'outil approprié pour cet objectif (souvent un signal de capacité manquante).

Workflow : répondre à « mon outil est-il découvrable ? » depuis le pivot outil

Chaque entrée dans tools porte :

• clusters — les clusters d'intentions que l'outil sert, chacun avec capture_pct (sa part des appels du cluster), rank, top_competitor (l'autre outil le plus fort et sa part), et description_fit (similarité cosinus entre la description de l'outil et le centroïde du cluster ; null jusqu'à ce que les descriptions soient capturées). Les entrées portent seulement cluster_id, pas le label ou les totaux du cluster — joignez-les contre le tableau clusters de niveau supérieur sur cet id
• n_clusters_served — combien de clusters l'outil sert au total. La liste d'entrées ci-dessus est plafonnée, donc comparez les deux avant de dire « cet outil sert N intentions »
• discovery_rate_pct — des sessions échantillonnées dont le catalogue $mcp_tools_list annonçait l'outil, la part qui l'a réellement appelé ; null quand l'outil a été annoncé dans moins de 5 sessions échantillonnées
• contested_score — entropie moyenne pondérée par appel de ses clusters : à quelle fréquence ses intentions sont partagées avec d'autres outils

Un description_fit élevé avec un capture_pct faible est l'échec de découvrabilité : les agents devraient trouver l'outil pour cette intention mais en choisir un autre. Un fit faible avec une capture élevée signifie que la description sous-vend ce que l'outil fait réellement. tool_overlaps liste les paires en concurrence pour les mêmes intentions ; utilisez sessions_with_both vs sessions_with_either pour séparer les workflows (utilisés ensemble) de la confusion (l'un ou l'autre).

Lisez la couverture avant de citer des nombres : computed_with.sampled_sessions / session_coverage_pct disent combien de la fenêtre le corpus représente, et advertisement_coverage_pct borne ce que les taux de découverte peuvent voir. Seules les sessions avec un catalogue de listes d'outils observé entrent dans les dénominateurs de découverte, et les sessions en mode exec-wrapper n'annoncent que le wrapper, donc la découverte par outil est mesurée sur des sessions de catalogue complet.

computed_with n'est cependant pas une vérification de complétude pour tout. Seuls les plafonds d'outils de niveau supérieur et de paires de chevauchement rapportent ce qu'ils ont abandonné, via dropped_tools et dropped_overlap_pairs. Les listes par cluster sont plafonnées silencieusement, donc traitez un cluster affichant 10 switches ou 5 self-retries comme « au moins autant », pas « exactement ». Les entrées cluster d'un outil sont aussi plafonnées, mais là n_clusters_served vous donne le vrai comptage.

Le clustering lit seulement les événements. Les résumés de session à la demande (MCPSession.intent, ce que « generate intent » écrit) sont délibérément laissés de côté : un résumé décrit une session entière, et l'étaler sur les appels de cette session est la mauvaise attribution que le corpus par appel existe pour supprimer. Ainsi une session dont l'intention n'a été que résumée n'est dans aucun cluster — vérifiez intent_coverage_pct pour voir combien de la fenêtre cela laisse de côté, et lisez directement les résumés de session quand vous en avez besoin.

Workflow : gérer un snapshot vide ou obsolète

• Vide / inactif sans clusters (status: idle, clusters: []) : aucun run n'a encore eu lieu. Déclenchez-en un (ci-dessous) et dites à l'utilisateur qu'il se calcule en arrière-plan.
• last_computed_at obsolète : proposez de recalculer.

Workflow : recalculer

posthog:mcp-analytics-intent-clusters-recompute
{}

Retourne immédiatement avec status: computing (HTTP 202) ; le travail s'exécute en arrière-plan. Sondez posthog:mcp-analytics-intent-clusters-retrieve jusqu'à ce que status revienne à idle (terminé) ou error. Ne bloquez pas en attendant — dites à l'utilisateur de redemander dans une minute.

Construire des liens UI

• Intent clustering : https://app.posthog.com/project/<project_id>/mcp-analytics/intent-clustering

Conseils

• Les clusters ne sont aussi bons que la couverture $mcp_intent — si peu d'appels portent une intention, les clusters seront épars ; recoupez la couverture d'intention avec un rapide countIf(toString(properties.$mcp_intent) != '') sur $mcp_tool_call
• Un cluster avec un error_rate_pct élevé plus une routing_entropy élevée est le plus fort signal « les outils ne servent pas bien cet objectif » — vaut le coup de regarder de plus près ses sample_intents et sa tool_distribution
• Le recalcul est limité à un run à la fois par projet ; un 202 alors qu'il calcule déjà juste confirme le run en vol

Skills associées

• exploring-mcp-tool-quality — taux d'erreur et latence par outil
• exploring-mcp-sessions — les runs individuels derrière les intentions