Exploring MCP tool usage

Any MCP server instrumented with the @posthog/mcp SDK emits a $mcp_tool_call event every time an agent invokes a tool. This skill is the front door for a user who knows they want to look at their MCP tool usage but hasn't picked a specific question. Offer the menu below, then route to the tool — or the focused skill — that answers what they choose.

Governed metric first

When the question asks for an MCP failure rate or percentage, call posthog:metric-list before any typed tool or SQL recipe and look for mcp_tool_call_fail_pct. Run an approved, non-drifted match with posthog:data-catalog-metric-run for the canonical headline. If the user also asks which tool or harness drives failures, answer the headline first, then use the per-tool workflows below for a noncanonical breakdown. If no governed metric matches, say so and label the derived rate noncanonical.

Every per-tool tool here takes a toolName (the effective tool name — resolved server-side, so pass the name the agent actually invokes — except posthog:query-mcp-tool-failures, which matches $exception events and so takes the raw registered $mcp_tool_name) plus a dateRange, and runs the same query runner the tool-detail UI uses. So results match the UI, and you never hand-write the HogQL.

Suggested questions

Lead with these when the user is unsure what to ask:

Ask the user…	Answered by
"Which tools fail most, or are slowest?"	exploring-mcp-tool-quality (ranks all tools), then posthog:query-mcp-tool-stats to drill in
"How is tool X doing overall?"	posthog:query-mcp-tool-stats — calls, errors, p50/p95, users, sessions, intents
"How has tool X trended?"	posthog:query-mcp-tool-daily-stats — day-by-day series
"Why is tool X failing?"	posthog:query-mcp-tool-failures — top error messages, by harness (raw tool name)
"Who uses tool X the most?"	posthog:query-mcp-tool-top-users — top callers (incl. person email/name)
"What gets called right before/after tool X?"	posthog:query-mcp-tool-neighbors (neighborDirection: before/after)
"What are agents trying to do with tool X?"	posthog:query-mcp-tool-sample-intents — recent agent intents
"What description is tool X registered with?"	posthog:query-mcp-tool-descriptions — distinct descriptions seen
"Which harnesses use my MCP, how reliably?"	posthog:query-mcp-harness-breakdown — calls/errors/sessions per client
"What are agents trying to do, across all tools?"	exploring-mcp-intent-clusters — semantic goal clusters
"Who is connecting, and how active are they?"	posthog:mcp-analytics-sessions-list — one row per session, with client and person
"What did this one session do?"	exploring-mcp-sessions — a single agent run's tool sequence

Finding the tool name

The per-tool tools need a toolName. If the user named a tool, pass it. If they asked a broad "which tool…" question, start with exploring-mcp-tool-quality to rank the tools, pick the one that stands out, then drill in with the per-tool tools above. The name to pass is the effective tool name (the inner tool for single-exec wrapper calls) — the same string the tool-quality ranking returns. The one exception is posthog:query-mcp-tool-failures, which matches $exception events by the raw registered $mcp_tool_name, not the effective inner tool.

How to use a per-tool tool

Call it with the tool name and a window, e.g. for the headline numbers of a tool:

posthog:query-mcp-tool-stats  { "toolName": "<tool>", "dateRange": { "date_from": "-7d" } }

Then offer a natural follow-up from the menu — e.g. after posthog:query-mcp-tool-stats shows a high error rate, reach for posthog:query-mcp-tool-failures; after it shows broad reach, reach for posthog:query-mcp-tool-top-users or posthog:query-mcp-tool-neighbors.

When to drop to SQL

Covered by a typed tool — don't hand-write SQL for these:

Question	Tool
One tool's headline numbers	posthog:query-mcp-tool-stats
One tool's day-by-day trend	posthog:query-mcp-tool-daily-stats
One tool's top errors	posthog:query-mcp-tool-failures
One tool's top callers	posthog:query-mcp-tool-top-users
Tools called before/after one tool	posthog:query-mcp-tool-neighbors
One tool's recent agent intents	posthog:query-mcp-tool-sample-intents
One tool's registered descriptions	posthog:query-mcp-tool-descriptions
Usage split by client harness	posthog:query-mcp-harness-breakdown
List sessions	posthog:mcp-analytics-sessions-list
One session's tool calls	posthog:mcp-analytics-sessions-tool-calls

Not covered — use posthog:execute-sql:

• Cross-tool rankings (the tool-quality matrix — "which tool errors most?")
• Errored-session filtering (the session list has no error filter or error count)
• Effective tool names inside a session (posthog:mcp-analytics-sessions-tool-calls returns the raw $mcp_tool_name, not the inner tool of a wrapper call)
• Any custom breakdown

posthog:execute-sql is also the fallback when the tools in the table above aren't in your tool list. Query $mcp_tool_call directly; the schema and recipes are in models-mcp.md.

Related skills

• exploring-mcp-tool-quality — rank tools by error rate / latency / reach, then drill in
• exploring-mcp-sessions — a single agent run and its tool sequence
• exploring-mcp-intent-clusters — agent goals grouped by semantic similarity