Exploring MCP Tool Usage

From the author

Starting point for exploring how a PostHog MCP server's tools are used — routes a broad question to the typed tool that answers it. Use when the user asks "how is my MCP doing?", "what should I look at?", "explore my tool calls", "who uses my MCP tools?", "what are agents doing with the MCP?", or pastes an MCP analytics URL without a specific question. Offers a menu of questions, each backed by a query tool, then hands off to the focused skill.

— the description by PostHog

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill serves as the primary entry point for users looking to analyze how their MCP tools are being utilized by agents. It provides a structured menu of diagnostic questions and routes the user to the appropriate specialized tool or workflow to obtain answers. By standardizing the interaction with PostHog MCP analytics, it ensures consistent data retrieval for metrics such as tool performance, error rates, user behavior, and agent intent, while providing clear guidance on when to use specific tools versus custom SQL queries.

What it does

Routes broad user inquiries about MCP tool usage to specific diagnostic tools.
Provides a menu of common analytical questions to guide users through their investigation.
Enforces the use of governed metrics for failure rates and performance reporting.
Standardizes the parameters for per-tool analysis to ensure consistency with UI data.
Offers clear pathways for drilling down into tool stats, trends, errors, and user behavior.
Defines clear boundaries for when to use built-in tools versus custom SQL execution.

When to use it

When a user asks general questions like 'How is my MCP doing?' or 'What should I look at?'.
When a user wants to investigate specific tool performance, error rates, or usage patterns.
When a user needs to understand agent behavior or intent regarding MCP tool calls.
When a user is unsure which specific analytical tool is required to answer their question.

Advantages

Reduces user cognitive load by providing a guided menu for complex data exploration.
Ensures data consistency by leveraging predefined tools rather than ad-hoc SQL.
Promotes best practices by prioritizing governed metrics for reliability reporting.
Simplifies the discovery of specialized analytical workflows for MCP instrumentation.

Usage examples

“How is my MCP doing?”: The agent presents a menu of diagnostic options, such as checking failure rates, tool performance, or session activity, to help the user narrow down their focus.
“Why is my database-query tool failing?”: The agent identifies the tool name and routes the request to the appropriate failure analysis workflow to show top error messages.
“Who uses my MCP tools the most?”: The agent guides the user to the top-users analysis tool to identify the most active callers and their associated metadata.
“What are agents trying to do with my tools?”: The agent offers to run an intent analysis or sample recent agent intents to provide insight into tool usage goals.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/posthog/exploring-mcp-tool-usage/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip exploring-mcp-tool-usage.zip -d .agents/skills

Documentation by PostHog

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.

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.

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

Files

ATTRIBUTION.mdAdded by AutoGineer867 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md7.1 KiB

SKILL.md