A
licenseC
qualityB
maintenanceMCP server exposing Umami analytics (Cloud + self-hosted)
5
MIT
umami-compass
by webcredo
Umami Compass is a secure, read-only MCP server for Umami Analytics (cloud or self-hosted, 3.2+) that enables AI agents to query and analyze web analytics data without exposing the underlying database.
Core Analytics (enabled by default)
get_server_info— Retrieve package version, enabled toolsets, safety limits, and capabilitieslist_websites— List all visible websites with optional search and paginationget_website— Fetch metadata for a specific website by UUIDget_website_stats— Aggregate stats (visits, visitors, pageviews, bounce rate, duration) for a time range with filtersget_pageviews— Pageview and session time-series data with configurable time units and filtersget_metrics— Ranked metric breakdowns by dimension (path, referrer, country, device, browser, channel, event, etc.)get_active_visitors— Real-time active visitor countget_website_date_range— Earliest and latest analytics timestamps for a website
Decision-Ready Insights (enabled by default)
resolve_website— Resolve a website UUID from a domain, URL, or nameget_portfolio_overview— Summarize traffic across all visible websites, highlighting growth/decline leaders, stale tracking, and anomaliesexplain_traffic_change— Compare traffic vs. a previous, year-over-year, or custom period and rank changes across pages, referrers, countries, devices, channels, and eventscompare_traffic_series— Aligned current vs. comparison time-series buckets to pinpoint when traffic changedanalyze_release_impact— Compare pre/post-release windows across traffic and Core Web Vitals; detect confounded releasestracking_health_check— Audit for stale/missing traffic, drops, domain mismatches, referral spam, and recorder configuration issues
Optional Toolsets (opt-in via UMAMI_TOOLSETS)
Events — Row-level custom event data
Sessions — Session-level data and activity
Performance — Core Web Vitals, breakdowns, cross-tabs, and route group performance
Reports — Funnels, journeys, retention, UTM, attribution, and multi-field breakdown reports
Revenue — Revenue stats and metrics
Replay — Session replay metadata (never raw payloads)
Heatmaps — Click/scroll heatmap data
Safety & Security
Entirely read-only — no create, update, or delete operations
Structured filters with operators (
equals,contains,regex,IN, etc.) and channel/traffic-segment filteringReferral spam detection via
trafficSegment: "human"Configurable limits: request timeout, max range days, max response bytes, HTTPS enforcement
Website and team allowlists for access scoping
Provides read-only tools to query Umami Analytics data, including website stats, pageviews, metrics, active visitors, events, sessions, performance (Core Web Vitals), reports (funnels, journeys, retention, UTM, attribution, revenue), replay metadata, and heatmaps from Umami Cloud or self-hosted instances.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@umami-compasslist my websites"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Umami Compass
Open-source MCP server for Umami Analytics — Cloud and self-hosted.
Distribution: umami-compass on npm · io.github.webcredo/umami-compass in the official MCP Registry
Umami Compass is a secure, read-only Model Context Protocol server for Umami Analytics. It gives MCP clients accurate Umami 3.2 analytics without exposing a database or allowing arbitrary network requests.
Version 0.5.1 is the current source release. See Compatibility before using it with older Umami versions.
The
npxexamples follow the stable npm release channel and check it whenever the MCP process starts. For source-based evaluation, clone this repository, runpnpm install --frozen-lockfile && pnpm build, and usenode /absolute/path/to/umami-compass/dist/cli.jsas the MCP command.
Why this project
Existing Umami MCP servers each cover part of the problem, but our July 2026 review found gaps around Umami 3.2 response correctness, Cloud authentication, safety boundaries, or extensibility. Umami Compass sets a higher, testable quality bar:
Correct auth for both products:
x-umami-api-keyfor Umami Cloud and Bearer/login auth for self-hosted instances.Umami 3.2-aware responses, including both
pageviewsandsessions, Core Web Vitals, funnels, journeys, attribution, retention, revenue, bounded heatmaps, and replay metadata.Read-only by construction: every tool declares MCP safety annotations; no create, update, delete, raw HTML, or arbitrary URL tool exists.
Defense in depth: fixed upstream origin, HTTPS policy, website and team allowlists, range/page/response-byte caps, request timeout, cancellation propagation, and redacted errors.
Decision-ready insights: bounded traffic and performance portfolio overviews, traffic-change evidence, release-impact analysis, tracking-health audits, and website resolution without arbitrary API access.
Agent-friendly output: machine-readable
structuredContent, a common status/range/truncation envelope, two resources, and six guided prompts.Contributor-friendly architecture: endpoint modules, dependency-injected HTTP, a central access policy, ADRs, and real MCP integration tests.
See the dated landscape review for the evidence and methodology.
Related MCP server: Umami MCP Server
Quick start
Requirements: Node.js 22 or newer and an Umami identity with view-only access where possible.
The examples use the auto-updating stable launcher:
npx --yes --prefer-online umami-compass@latest@latest selects the stable npm channel and --prefer-online makes npm check the registry even when package metadata is cached. npm still reuses the cached package when that exact release is already present. Updates take effect the next time the MCP process starts; an already running local server cannot replace itself.
Use umami-compass@next instead to opt into preview releases. For reproducible CI or centrally managed environments, pin an exact release and omit the online check, for example npx --yes umami-compass@0.5.1. Never use the preview channel for an unattended production setup.
Umami Cloud
{
"mcpServers": {
"umami": {
"command": "npx",
"args": ["--yes", "--prefer-online", "umami-compass@latest"],
"env": {
"UMAMI_API_KEY": "replace-with-your-api-key"
}
}
}
}With UMAMI_API_KEY and no URL, the API root defaults to https://api.umami.is/v1.
Self-hosted Umami
{
"mcpServers": {
"umami": {
"command": "npx",
"args": ["--yes", "--prefer-online", "umami-compass@latest"],
"env": {
"UMAMI_URL": "https://analytics.example.com",
"UMAMI_USERNAME": "mcp-viewer",
"UMAMI_PASSWORD": "replace-me",
"UMAMI_WEBSITE_IDS": "6b2c8c10-908c-4a8e-a924-4049eb3bde8c"
}
}
}
}UMAMI_URL is an instance origin; /api is appended. Use UMAMI_API_URL instead when a reverse proxy exposes a custom, exact API root.
UMAMI_WEBSITE_IDS is an optional safety allowlist, not a credential. Replace the example UUID with a website ID from Umami (or from list_websites), separate multiple IDs with commas, or remove the variable to discover every website visible directly or through a team membership.
UMAMI_TEAM_IDS is a strict team boundary for discovery and direct website/report access. When it is set, user-owned websites without one of the selected team IDs are excluded. If UMAMI_WEBSITE_IDS is also set, a website must pass both allowlists.
Do not commit real credentials. Prefer a dedicated view-only Umami account and the client/OS secret store when available.
Tools
The least-privilege default enables core,insights: eight primitive aggregate tools plus seven decision-ready aggregate workflows. Row-level events, sessions, replay, heatmaps, and other more sensitive modules remain opt-in.
Toolset | Tools | Default |
|
| Yes |
|
| Yes |
|
| No |
|
| No |
|
| No |
| Saved reports and segments plus goal, funnel, journey, retention, UTM, attribution, and multi-field breakdown reports | No |
|
| No |
|
| No |
|
| No |
Set UMAMI_TOOLSETS=all or a comma-separated subset. The default has 15 aggregate tools; all has 42. Multi-website insights are bounded to 50 websites with four concurrent website workers. High-cardinality report, performance, heatmap, channel fan-out, and activity results carry explicit limits and truncation metadata.
get_performance_breakdown requires at least 20 performance events per row by default for page, page-title, device, and browser rankings. This is an exploratory p75 quality guard, not a claim of statistical significance. Umami 3.2 calculates these counts with count(*), not count(metric), so Compass labels them as event counts and never presents them as metric-specific samples. Set minimumSampleCount explicitly to tighten the guard or lower it to 1 to include every otherwise valid row.
Umami 3.2 caps page, page-title, and browser candidates at 500 before Compass can apply the sample guard. Breakdown responses therefore report the effective minimum, excluded-row counts, candidate coverage, and whether that upstream cap may make the filtered ranking incomplete. If all complete candidates are undersized, emptyReason is insufficient_sample_size; if the candidate cap prevents that conclusion, dataStatus is unknown.
Successful tool responses preserve the existing data field and add a common meta envelope. Depending on the request it includes dataStatus, emptyReason, websiteId, requestedRange, and timezone. Truncation is split into responseTruncated for an incomplete primary result and sectionsTruncated for bounded nested sections; the aggregate truncated field remains for compatibility.
The server exposes umami://websites and the sanitized umami://capabilities resource. Website discovery returns only id, name, and domain; request get_website explicitly when detailed metadata is required. get_server_info returns the same local version, enabled toolsets, limits, and feature flags as a tool. Guided prompts cover an analytics report, weekly portfolio briefing, traffic investigation, release impact, tracking health, and conversion audit; each prompt is registered only when its required toolset is enabled. Scheduling a recurring briefing remains the MCP client's responsibility; the local stdio server does not run a background scheduler or send messages.
Performance analysis and upstream limits
analyze_performance_portfolio performs two bounded performance requests and two aggregate traffic requests per selected website, with four website workers. verbosity="compact" is the default decision summary; standard adds concise per-site rows and metric-specific drill-downs; full returns complete normalized per-site evidence. Drill-down websites are selected only by detailMetric. Performance events per pageview are returned as a ratio that may exceed 1; true collection coverage remains unknown_upstream because Umami does not return distinct covered pageviews. Portfolio p75 values are ranked but never averaged because percentiles from separate websites are not composable.
compare_web_vitals compares all five summary metrics. compare_performance_breakdown aligns page, title, device, or browser rows, returns comparable rows first, excludes rows below minimumSampleCount by default, and omits candidates whose absence is uncertain because an upstream top-500 list was capped. Set includeInsufficient=true to append undersized rows after useful comparisons. get_performance_cross_tab derives combinations through at most ten filtered fan-out requests and reports whether candidates came from performance events or traffic metrics. get_route_group_performance accepts caller-defined path regexes and queries every route group directly; route groups may overlap and PostgreSQL/ClickHouse regex dialect details can differ.
Performance tools accept only page/title and persisted environment filters that are consistent across Umami's supported database backends. excludeBounce, referrer, UTM, hostname, query, event, tag, and other non-persisted performance fields are rejected instead of ignored. In particular, Umami 3.2 builds but does not use its excludeBounce join in the performance report.
Umami 3.2 does not return metric-specific sample counts or counts in chart buckets. Compass therefore returns count: null for a chart point when the field is absent, includes sampleCounts.status="unavailable_upstream", and marks incomplete requested/current buckets with partial: true. Overall counts are named performanceEventCount. Non-CLS all-zero percentile placeholders are treated as unavailable; a zero CLS remains valid.
LCP decomposition, LCP element/resource attribution, cache status, and edge region are explicitly reported as unavailable because Umami's aggregate performance report does not collect or expose them. Compass does not infer a decomposition by subtracting unrelated aggregate percentiles.
Filters, direct traffic, channels, and traffic quality
Plain string filters remain compatible. Structured filters add equals, not_equals, contains, not_contains, regex, not_regex, is_empty, and is_not_empty. Equality operators accept an array for native IN or NOT IN behavior:
{
"filters": {
"referrer": { "operator": "is_empty" },
"path": { "operator": "not_equals", "value": ["/admin", "/internal"] }
}
}For compatibility, {"referrer": ""} also isolates rows whose referrer domain is empty. This is not always the same as Umami's direct channel: a no-referrer visit with campaign parameters can be attributed to affiliate, email, paid, or another channel. Use filters.channel: "direct" when exact Umami channel attribution matters. Compass uses Umami's neutral referrer-domain column for structured and empty-referrer filters so internal/no-referrer traffic is not accidentally removed by Umami's external-referrer behavior.
explain_traffic_change, analyze_release_impact, and run_breakdown_report accept filters.channel, including direct. run_breakdown_report also accepts channel as a field, so requests such as channel × device work. Umami 3.2 does not natively expose channel as a filter or breakdown field; Compass derives these results through bounded expanded-metric fan-out and reports candidate coverage, omitted rows, request count, and truncation under dataQuality. Channel cross-tabs cannot be combined with custom events or with filters.match: "any", because Umami cannot express the required candidate predicate outside that OR group; Compass rejects these requests instead of returning overlapping totals.
Traffic-change, release-impact, comparison-series, and breakdown results conservatively flag referral-spam candidates using the combined pattern of a generated-looking domain, very high bounce rate, near-zero visit duration, and minimum traffic. Set trafficSegment to human to exclude only those candidates from traffic results with native negative filters. The preset fails closed when both periods cannot be assessed or when mandatory exclusions would be weakened by filters.match: "any". Findings remain heuristics, not a definitive bot classification, and include their evidence and thresholds. Referrer exclusions cannot be applied to Umami 3.2 performance events; release-impact analysis marks that performance evidence scope_mismatch rather than comparing a different audience silently.
analyze_release_impact returns a compact executive summary, exact comparison periods, and recommended checks by default while avoiding breakdown fan-out; set detailLevel to full for breakdowns, traffic-quality evidence, and complete Web Vital changes. Pass known neighboring deployments through otherReleases so Compass can mark the result as confounded instead of attributing the whole window to one release. When Web Vital samples are insufficient, the primary verdict is insufficient_data and sampleReadiness reports traffic and performance deficits, an estimated recheckAt, and a longer equal window when the observed rate makes one feasible.
compare_traffic_series fills sparse rows against real buckets in the requested timezone, including DST transitions. If current and comparison periods contain different numbers of local-time buckets, it returns the raw series with alignedChangesAvailable: false and omits derived bucket deltas instead of shifting the comparison.
Structured filters retain field-specific length limits, at most 20 values per condition, 30 conditions and 100 values across one request, and a 16 KiB serialized-query budget.
Configuration
Choose exactly one authentication mode.
Authentication
UMAMI_API_KEY— Umami Cloud/client API key. It is sent only asx-umami-api-key.UMAMI_ACCESS_TOKEN— existing Bearer token.UMAMI_USERNAME+UMAMI_PASSWORD— lazy self-hosted login with a cached token and one refresh on 401.
Authentication variables have no default. Configure only one of the three modes above.
Endpoint and access scope
UMAMI_URL— self-hosted instance origin;/apiis appended. With API-key auth and no URL, the default is the Umami Cloud API root.UMAMI_API_URL— exact API root; takes the place ofUMAMI_URL. No default.UMAMI_WEBSITE_IDS— comma-separated website UUID allowlist. Defaults to every site visible directly or through a team membership.UMAMI_TEAM_IDS— comma-separated strict team UUID allowlist for discovery and direct website/report access; at most 25 IDs. User-owned websites are excluded while it is set, andUMAMI_WEBSITE_IDSis intersected when both are configured.UMAMI_TOOLSETS— comma-separated toolsets orall. Available values arecore,insights,events,sessions,performance,reports,revenue,replay, andheatmaps. Defaults tocore,insights.
Safety limits
UMAMI_REQUEST_TIMEOUT_MS— per-request timeout from 1,000 to 120,000 ms. Defaults to30000.UMAMI_MAX_RANGE_DAYS— maximum analytics range from 1 to 3,650 days. Defaults to366.UMAMI_MAX_RESPONSE_BYTES— maximum decoded upstream JSON body from 102,400 to 52,428,800 bytes. Defaults to10485760.UMAMI_ALLOW_INSECURE_HTTP— permits non-loopback HTTP when set totrue. Defaults tofalse.
HTTPS is mandatory by default. Plain HTTP is accepted automatically only for localhost, 127.0.0.1, and ::1.
Client setup
All examples below use Umami Cloud. Export the secret in the environment that launches your client:
export UMAMI_API_KEY="replace-with-your-api-key"For self-hosted Umami, replace UMAMI_API_KEY with the variables shown in Self-hosted Umami. Add UMAMI_TOOLSETS=all only if the account has the matching Umami section permissions and you want the optional data surfaces.
Codex CLI, IDE extension, and ChatGPT desktop
Codex clients and ChatGPT desktop on the same host share ~/.codex/config.toml. env_vars forwards the secret without writing its value into the config:
[mcp_servers.umami-compass]
command = "npx"
args = ["--yes", "--prefer-online", "umami-compass@latest"]
env_vars = ["UMAMI_API_KEY"]Run codex mcp list or /mcp to verify it. In the Codex IDE extension or ChatGPT desktop, you can also open MCP servers, add a STDIO server with command npx --yes --prefer-online umami-compass@latest, then restart the client. See the official Codex and ChatGPT MCP guide.
ChatGPT web does not read local Codex config. The current package is local stdio; a hosted plugin requires the future authenticated remote transport.
Claude Code
Use user scope to keep the personal server outside the repository:
claude mcp add --scope user --transport stdio \
--env UMAMI_API_KEY="$UMAMI_API_KEY" \
umami-compass -- npx --yes --prefer-online umami-compass@latestVerify with claude mcp list or /mcp. For a team-safe .mcp.json, Claude Code supports ${UMAMI_API_KEY} expansion; never commit the actual value. See the official Claude Code MCP guide.
Claude Desktop
Open Settings → Developer → Edit Config. On macOS the file is ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows it is %APPDATA%\Claude\claude_desktop_config.json.
{
"mcpServers": {
"umami-compass": {
"command": "npx",
"args": ["--yes", "--prefer-online", "umami-compass@latest"],
"env": {
"UMAMI_API_KEY": "replace-with-your-api-key"
}
}
}
}Protect the config file because this client format stores the value, then fully quit and restart Claude Desktop. See the official local MCP server guide.
Cursor
Put this in the private global ~/.cursor/mcp.json, or in .cursor/mcp.json only when it contains no real credentials:
{
"mcpServers": {
"umami-compass": {
"command": "npx",
"args": ["--yes", "--prefer-online", "umami-compass@latest"],
"env": {
"UMAMI_API_KEY": "replace-with-your-api-key"
}
}
}
}Enable the server in Cursor Settings → MCP. See the official Cursor MCP documentation.
VS Code / GitHub Copilot
Use MCP: Open User Configuration for a personal config, or .vscode/mcp.json for a shared command. VS Code uses servers (not mcpServers) and can prompt for a masked secret:
{
"inputs": [
{
"type": "promptString",
"id": "umami-api-key",
"description": "Umami API key",
"password": true
}
],
"servers": {
"umami-compass": {
"type": "stdio",
"command": "npx",
"args": ["--yes", "--prefer-online", "umami-compass@latest"],
"env": {
"UMAMI_API_KEY": "${input:umami-api-key}"
}
}
}
}Run MCP: List Servers to start, inspect, or troubleshoot it. See the official VS Code MCP guide.
Gemini CLI
Add this to the user-level ~/.gemini/settings.json (or project .gemini/settings.json). Gemini expands shell variables in env:
{
"mcpServers": {
"umami-compass": {
"command": "npx",
"args": ["--yes", "--prefer-online", "umami-compass@latest"],
"env": {
"UMAMI_API_KEY": "$UMAMI_API_KEY"
},
"trust": false
}
}
}Verify with gemini mcp list or /mcp. See the official Gemini CLI MCP guide.
Troubleshooting
Run
npx --yes --prefer-online umami-compass@latest --versionfirst; Node.js 22+ is required.After a package update, restart the MCP server so the client requests the new tool list. A client still showing an old or empty list may also need its cached tools cleared.
401means the credential or auth mode is wrong;403can mean the Umami account lacks permission for that website section.For self-hosted local development,
http://localhost:3000is allowed. Other plain HTTP origins require the explicit unsafe opt-in.Start with the default toolsets. Enable
performance,reports,revenue,replay, orheatmapsonly as needed.Enable
eventsorsessionsonly when the client needs row-level data and the Umami identity is allowed to expose it.
Architecture
flowchart LR
Client["MCP client"] -->|stdio / JSON-RPC| Server["MCP server"]
Server --> Policy["Module + access policy"]
Policy --> Modules["Core / Events / Sessions / Performance / Reports / Revenue / Replay / Heatmaps"]
Modules --> API["Typed, fixed-origin Umami client"]
API -->|"API key / Bearer / lazy login"| Umami["Umami Cloud or self-hosted 3.2+"]The package intentionally ships stdio first. A public HTTP transport needs OAuth 2.1, tenant isolation, rate limits, and an operational threat model; binding an unauthenticated endpoint would weaken the project.
Future management tools are anticipated but cannot slip into the read-only build accidentally. Every module declares access: "read" | "write", and the server rejects write modules under the default policy. See architecture and ADR-0001.
See the Umami 3.2 API coverage matrix for what is implemented, deliberately excluded, and prioritized next.
Development
corepack enable
pnpm install --frozen-lockfile
pnpm check
pnpm devTo add an endpoint, follow Adding a tool. For project expectations and pull requests, see CONTRIBUTING.md.
Compatibility
Umami 3.2.x is the reference implementation and test target.
Older Umami releases may work for unchanged endpoints but are not promised yet.
Node.js 22, 24, and 26 are tested in CI.
MCP SDK v1 is used because it is the stable production line as of July 2026; the v2 branch is still pre-release.
Security and privacy
Analytics, session metadata, revenue, and replay metadata can be sensitive. Use least-privilege credentials, an allowlist, the smallest toolset, and short time ranges. Read SECURITY.md before production use.
Umami Compass is an independent community project and is not affiliated with Umami Software.
Support the project
Umami Compass is free and open source. If it saves you time or improves your analytics workflow, you can support the project by buying me a coffee on Ko-fi.
License
MIT © 2026 webcredo and Umami Compass contributors.
Available Tools
14 toolsanalyze_release_impactAnalyze release impactARead-onlyIdempotent
Compare equal pre- and post-release windows across traffic breakdowns and Core Web Vitals. Returns a compact executive summary by default; request full detail for drill-down evidence. Recent releases use a partial post window and an equally shortened pre window.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| filters | No | ||
| timezone | No | UTC | |
| releaseAt | Yes | Unix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC) | |
| websiteId | Yes | Umami UUID | |
| dimensions | No | ||
| windowDays | No | ||
| detailLevel | No | summary | |
| otherReleases | No | ||
| trafficSegment | No | all | |
| includePerformance | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| data | Yes | JSON analytics data returned by Umami Compass |
| meta | Yes |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive hints. The description adds behavioral context beyond annotations: default return format (compact summary vs full detail) and partial-window handling for recent releases, which are valuable for agent behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each adding value: purpose, return format options, edge-case behavior. No wasted words, front-loaded with key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters, nested filters, output schema), the description covers essential behavior and key decision points (summary vs full, partial windows). It could mention available filters, but the output schema exists so return values are not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (18%). The description adds meaning for core parameters (e.g., releaseAt, windowDays, detailLevel) and the comparison concept, but many complex filter fields remain undocumented. It partially compensates but is insufficient for full clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it compares equal pre- and post-release windows across traffic breakdowns and Core Web Vitals, with a specific verb and resource. It distinguishes from siblings like compare_traffic_series by focusing on release impact analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes clear it is for analyzing release impact by comparing time windows, but does not explicitly state when not to use it or mention alternatives. Context is clear but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
compare_traffic_seriesCompare traffic time seriesARead-onlyIdempotent
Return aligned current and comparison traffic buckets to locate the exact day or hour when traffic changed.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Unix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC) | |
| unit | No | day | |
| start | Yes | Unix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC) | |
| filters | No | ||
| timezone | No | UTC | |
| websiteId | Yes | Umami UUID | |
| comparisonEnd | No | Unix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC) | |
| comparisonMode | No | previous | |
| trafficSegment | No | all | |
| comparisonStart | No | Unix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC) |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| data | Yes | JSON analytics data returned by Umami Compass |
| meta | Yes |
TDQS
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds that it returns 'aligned buckets', which is minimal. It does not contradict annotations, but it does not enrich behavioral context (e.g., no mention of rate limits, data freshness, or handling of missing data).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, immediately stating the action and purpose. It is efficiently front-loaded and every phrase contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema (so return value details are covered) and moderate schema coverage, the tool is highly complex (10 parameters, nested filters, multiple enums). The description only provides a high-level purpose and lacks details on alignment semantics, bucket granularity, comparison modes, or how filters apply to both periods. This is insufficient for reliable agent selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (5 of 10 parameters have descriptions in the schema). The tool description does not add any parameter-specific information beyond the schema. It does not explain the meaning of 'current' vs 'comparison' periods or how filters interact. Baseline 3 due to moderate coverage, but description should have compensated more.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and resource ('aligned current and comparison traffic buckets'), and states the outcome ('to locate the exact day or hour when traffic changed'). It clearly distinguishes itself from siblings like 'explain_traffic_change' and 'get_metrics' by focusing on pinpointing the timing of changes through comparison.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for comparing traffic time series to find change timing, but it does not provide explicit guidance on when to use it versus alternatives or when not to use it. For example, no mention of comparison modes (previous, year_over_year, custom) or when each is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
explain_traffic_changeExplain a traffic changeARead-onlyIdempotent
Compare traffic with a previous, year-over-year, or custom period and rank observed changes across pages, referrers, countries, devices, channels, and events. Results describe association, not causation.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Unix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC) | |
| limit | No | ||
| start | Yes | Unix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC) | |
| filters | No | ||
| timezone | No | UTC | |
| websiteId | Yes | Umami UUID | |
| dimensions | No | ||
| comparisonEnd | No | Unix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC) | |
| comparisonMode | No | previous | |
| trafficSegment | No | all | |
| comparisonStart | No | Unix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC) |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| data | Yes | JSON analytics data returned by Umami Compass |
| meta | Yes |
TDQS
A3.8/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds the important caveat that results describe association, not causation, which is valuable behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, front-loaded with core action. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (11 parameters, nested filters, multiple comparison modes) and low schema coverage, the description is too sparse. It covers high-level purpose but lacks guidance on required parameters, how to set comparison mode, and interpretation of results. The output schema is present but not described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 45%, and the tool has 11 parameters. The description adds no parameter-level information (e.g., no explanation of websiteId, start, end, comparisonStart, etc.). It only lists possible dimensions but not how to specify them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool compares traffic across periods and ranks changes across specific dimensions (pages, referrers, countries, devices, channels, events). It distinguishes from sibling 'compare_traffic_series' by focusing on explaining changes rather than time series visualization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions comparison modes (previous, year-over-year, custom) and dimensions, but does not explicitly state when to use this tool versus alternatives like compare_traffic_series or get_metrics. There is no guidance on when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_active_visitorsGet active visitorsARead-onlyIdempotent
Get the current number of active visitors for a website.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| websiteId | Yes | Umami UUID |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| data | Yes | JSON analytics data returned by Umami Compass |
| meta | Yes |
TDQS
A3.5/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no additional behavioral context beyond 'get the number', such as what constitutes an active visitor, time window, or real-time nature. The description does not contradict annotations (false).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, no fluff, and directly states the tool's purpose. It is appropriately front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, no nested objects, output schema exists but not shown), the description is minimally adequate. However, it lacks explanation of what 'active visitors' means or any time window, which could help the agent understand the metric better.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has full coverage (100%) with a single parameter 'websiteId' described as 'Umami UUID' with format and pattern. The tool description does not add any further meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and resource 'current number of active visitors for a website.' It clearly distinguishes from sibling tools like 'get_pageviews' or 'get_website_stats' by focusing on active visitors count.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives are mentioned. The description implies usage for retrieving active visitor counts, but does not guide the agent on when to prefer this over sibling tools like 'get_metrics' or 'get_website_stats'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_metricsBreak down website metricsARead-onlyIdempotent
Get a ranked aggregate Umami metric breakdown such as paths, referrers, countries, devices, events, channels or URLs. Visitor identifiers are excluded from the core toolset.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Unix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC) | |
| type | Yes | ||
| limit | No | ||
| start | Yes | Unix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC) | |
| offset | No | ||
| search | No | ||
| filters | No | ||
| websiteId | Yes | Umami UUID |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| data | Yes | |
| meta | Yes |
TDQS
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds that visitor identifiers are excluded, which is a behavioral detail. However, no other behaviors (e.g., pagination, rate limits) are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, efficiently conveying the core purpose and a key exclusion. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the output nature and exclusion of visitor identifiers, but omits guidance on filtering, pagination, and the extensive capabilities implied by the schema. With 8 parameters and nested objects, more context is needed for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (38%), but the description does not describe any parameters beyond listing possible values for the 'type' parameter. It does not explain the meaning of required parameters like websiteId, start, end, or the complex filters object, leaving the agent underinformed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a 'ranked aggregate Umami metric breakdown' for dimensions like paths, referrers, countries, etc. It also notes what is excluded ('visitor identifiers'), making the purpose unambiguous and distinct from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for obtaining metric breakdowns but does not explicitly state when to use this tool versus alternatives like get_pageviews or get_website_stats. No when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_pageviewsGet pageview and session seriesBRead-onlyIdempotent
Get Umami 3.2 pageview and session time series. Both arrays are preserved in the response.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Unix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC) | |
| unit | No | ||
| start | Yes | Unix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC) | |
| filters | No | ||
| timezone | No | UTC | |
| websiteId | Yes | Umami UUID |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| data | Yes | |
| meta | Yes |
TDQS
B3.1/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, establishing safe read behavior. The description adds minimal behavioral context by noting that both arrays are preserved and specifying the Umami version, but does not disclose rate limits, authentication needs, or response size constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at two sentences, front-loading the purpose and key response detail. Every sentence contributes meaningful information, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having a complex schema with 6 parameters including a rich filters object, the description provides no context on how unit affects granularity, timezone handling, filter composition, or response structure beyond mentioning two arrays. It is insufficient for an agent to fully understand the tool's capabilities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is approximately 67% (4 of 6 parameters have descriptions). The description adds no further parameter details beyond what the schema provides, so it meets the baseline without adding extra value for parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves pageview and session time series from Umami 3.2 and mentions response preservation of both arrays. It is specific about the resource and action, though it does not explicitly differentiate from sibling tools like get_metrics or get_website_stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description does not mention prerequisites, excluded scenarios, or contextual triggers, leaving the agent to infer usage from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_portfolio_overviewGet a portfolio analytics overviewBRead-onlyIdempotent
Summarize bounded aggregate traffic across visible websites, including period changes, growth and decline leaders, stale tracking, failures, and suspicious jumps.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Unix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC) | |
| start | Yes | Unix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC) | |
| websiteLimit | No | ||
| staleAfterHours | No | ||
| anomalyMinimumPageviews | No | ||
| anomalyThresholdPercent | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| data | Yes | JSON analytics data returned by Umami Compass |
| meta | Yes |
TDQS
B3.3/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral context by detailing what the summary includes (e.g., period changes, leaders), which is valuable beyond annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that packs key information. Could be slightly more structured, but it is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters and an output schema, the description only gives a high-level summary of outputs. It lacks details on parameter usage or output structure, though the output schema exists. Adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (33%), and the description adds no parameter information. It does not explain the purpose of websiteLimit, staleAfterHours, anomalyMinimumPageviews, or anomalyThresholdPercent, leaving agents uninformed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool summarizes bounded aggregate traffic across visible websites, listing specific outputs like period changes, growth/decline leaders, stale tracking, failures, and suspicious jumps. This distinguishes it from sibling tools that focus on single websites or specific metrics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites, exclusions, or context for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_server_infoGet Umami Compass server informationARead-onlyIdempotent
Get the local package version, enabled toolsets, safety limits, and supported analysis capabilities without exposing credentials.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| data | Yes | |
| meta | Yes |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. Description adds that it doesn't expose credentials, which is a security-relevant behavioral detail beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, efficient, front-loaded with key information. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters and an output schema present, the description adequately covers what the tool returns. Could potentially mention it's non-destructive, but annotations already cover that. Security note adds value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, schema coverage 100% (vacuous). Description adds meaning by listing the contents (version, toolsets, etc.) beyond the empty schema. Baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool retrieves local package version, enabled toolsets, safety limits, and analysis capabilities without exposing credentials. This is distinct from sibling tools like get_website or get_metrics which focus on website data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use versus alternatives. Context implies it's for initial setup or health check, but lacks when-not or specific alternative naming.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_websiteGet an Umami websiteBRead-onlyIdempotent
Get metadata for one website.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| websiteId | Yes | Umami UUID |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| data | Yes | |
| meta | Yes |
TDQS
B3.3/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds no behavioral details beyond confirming it is a read operation ('Get metadata'). It does not disclose any edge cases, permissions, or other traits not already captured by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It is front-loaded with the key action and resource. While it could perhaps add slightly more context, it remains concise and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only 1 parameter (fully described in the schema), rich annotations, and an output schema (not shown but present), the description is adequate for a simple read tool. It does not need to explain return values because the output schema exists. However, it could mention what specific metadata fields are returned to improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the single parameter 'websiteId' is described as 'Umami UUID'). The tool description does not add any additional meaning or context about the parameter beyond what the schema already provides. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Get metadata for one website.' It specifies the action (get) and the object (metadata for a single website), which effectively distinguishes it from sibling tools like 'list_websites' (multiple websites) and 'resolve_website' (likely resolves a domain).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of when-not-to-use or any similar contextual rules. Sibling tools are listed but not referenced or differentiated beyond the single sentence. The agent receives no explicit usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_website_date_rangeGet website data rangeARead-onlyIdempotent
Get the earliest and latest analytics timestamps available for a website.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| websiteId | Yes | Umami UUID |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| data | Yes | JSON analytics data returned by Umami Compass |
| meta | Yes |
TDQS
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds minimal behavioral context beyond confirming the return of timestamps. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is front-loaded and immediately clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to explain return values. It is complete for a simple read-only tool with comprehensive annotations, though it could mention the return format briefly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents the single parameter websiteId fully. The description adds no additional meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'analytics timestamps', and the scope 'for a website'. It distinguishes this tool from siblings like get_website or get_website_stats by specifying the return of earliest and latest timestamps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_website_stats or get_pageviews. The description only explains what it does, not the context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_website_statsGet website statisticsBRead-onlyIdempotent
Get visits, visitors, pageviews, bounces, visit duration and Umami's comparison values for a time range.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Unix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC) | |
| start | Yes | Unix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC) | |
| filters | No | ||
| websiteId | Yes | Umami UUID |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| data | Yes | |
| meta | Yes |
TDQS
B3.3/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, etc., so the safety profile is clear. The description adds the specific metrics returned and the time range parameter but does not disclose additional behavioral traits like rate limits, aggregation behavior, or data freshness. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the tool's function without superfluous words. It is front-loaded with the key action and resource, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and detailed annotations, the description is adequate but not fully comprehensive. It lists the returned metrics and mentions 'for a time range' but omits mention of the optional filters parameter and does not clarify the nature of 'comparison values'. More context about the tool's scope and limitations would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 75% description coverage across 4 parameters (websiteId, start, end described; filters not described). The tool description lists the metrics returned but does not elaborate on any parameter beyond what the schema provides. Since schema coverage is high, the description adds marginal value, meeting the baseline for 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves various website metrics such as visits, visitors, pageviews, bounces, and comparison values for a time range. It uses a specific verb ('Get') and resource ('website stats'), making the purpose obvious. However, it does not explicitly differentiate from sibling tools like get_metrics or get_pageviews, which could be similar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, context, or exclusion criteria. Given the sibling tools list includes similar analytics tools, this omission is a significant gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_websitesList Umami websitesARead-onlyIdempotent
List websites visible directly or through any team membership of the configured Umami identity. If UMAMI_WEBSITE_IDS is set, returns only that exact allowlist.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| search | No | ||
| pageSize | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| data | Yes | |
| meta | Yes |
TDQS
A3.8/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about environment variable behavior, which goes beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no extraneous information. Every sentence is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Context signals indicate an output schema exists, so return format may be covered there. However, with three parameters and zero description coverage, the description is incomplete for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It does not mention page, search, or pageSize at all. Without this, an agent may not understand how to use them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists websites visible to the Umami identity, with specific behavior when UMAMI_WEBSITE_IDS is set. This distinguishes it from sibling tools like get_website which returns a single website.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes the effect of environment variable UMAMI_WEBSITE_IDS, which guides usage. However, it does not explicitly state when to use alternatives or mention any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
resolve_websiteResolve an Umami websiteARead-onlyIdempotent
Resolve a website UUID from a UUID, domain, URL, or website name. Ambiguous matches return bounded candidates instead of guessing.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| candidateLimit | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| data | Yes | JSON analytics data returned by Umami Compass |
| meta | Yes |
TDQS
A4.3/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, and non-destructive nature. The description adds valuable context about ambiguous matches returning bounded candidates instead of guessing, which is not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no extraneous words. Front-loaded with verb and resource, efficiently conveying purpose and a key behavioral detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple lookup tool with 2 clearly described parameters and an output schema present, the description provides sufficient context. No additional explanation needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds meaning to the 'query' parameter by listing acceptable input types (UUID, domain, URL, name). The 'candidateLimit' parameter is explained via 'bounded candidates'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool resolves a website UUID using various identifiers (UUID, domain, URL, name) and handling ambiguous matches. This distinctively separates it from siblings like get_website (retrieve data given UUID) and list_websites (list all).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for resolving a website to its UUID, but does not explicitly state when to use this tool versus alternatives (e.g., get_website when UUID known). No exclusions or when-not conditions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tracking_health_checkCheck analytics tracking healthARead-onlyIdempotent
Audit visible websites for stale or missing traffic, traffic drops, domain mismatches, referral-spam patterns, custom-event availability, recorder configuration, and section permission failures. Disabled optional features are warnings only when marked as expected.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| checks | No | ||
| expectEvents | No | ||
| expectReplay | No | ||
| websiteLimit | No | ||
| expectHeatmap | No | ||
| lookbackHours | No | ||
| staleAfterHours | No | ||
| minimumPageviews | No | ||
| dropThresholdPercent | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| data | Yes | JSON analytics data returned by Umami Compass |
| meta | Yes |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, non-destructive, and open-world. The description adds a behavioral note about disabled optional features being warnings only when marked as expected, but overall does not significantly expand beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at two sentences, with the first sentence listing core checks and the second clarifying behavior for disabled features. It is front-loaded and efficient, though slightly more clarity on parameters could improve.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters and no required ones, the description provides a high-level overview but lacks details on input constraints and output. The presence of an output schema partially compensates, but the description does not mention the lookback window or website limit scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the burden on the description is high. However, it only loosely references some parameters (e.g., 'custom-event availability' for 'expectEvents', 'recorder configuration' for 'expectReplay') but fails to explain key parameters like 'websiteLimit', 'lookbackHours', 'staleAfterHours', 'minimumPageviews', and 'dropThresholdPercent'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool audits visible websites for specific issues like stale traffic, traffic drops, domain mismatches, etc., using a specific verb ('Audit') and a distinct resource ('visible websites'). It distinguishes itself from sibling tools like 'get_metrics' or 'get_pageviews' which are for data retrieval, not health checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for auditing tracking health but does not explicitly state when to use or when not to use this tool versus alternatives. No direct comparison with sibling tools or conditions for usage are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
14 tool updates
v0.4.1- First observed
analyze_release_impact - First observed
compare_traffic_series - First observed
explain_traffic_change - First observed
get_active_visitors - First observed
get_metrics - First observed
get_pageviews - First observed
get_portfolio_overview - First observed
get_server_info - First observed
get_website - First observed
get_website_date_range - First observed
get_website_stats - First observed
list_websites - First observed
resolve_website - First observed
tracking_health_check
TDQS
A3.8/5.0
Disambiguation5/5
Each tool has a clearly distinct purpose: metrics retrieval, traffic comparison, health auditing, and server information are all separated. Even similar functions like 'explain_traffic_change' and 'analyze_release_impact' target different analytical contexts.
Naming Consistency4/5
Most tools follow a verb_noun snake_case pattern (e.g., get_*, list_websites, resolve_website). The exception is 'tracking_health_check', which uses a noun_noun form, causing slight inconsistency.
Tool Count5/5
14 tools is well within the ideal 3-15 range for a focused analytics domain. Each tool covers a specific analytical need without redundancy, making the set appropriately scoped.
Completeness4/5
The toolset covers core analytics operations: data retrieval, comparison, health checks, and metadata. Minor gaps exist (e.g., no create/update/delete for websites), but these are likely intentional for a read-only analytics interface.
Maintenance
ActivitySlowing
ResponsivenessNo issues
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Cloud-hosted MCP server for URnetwork VPN and Proxy
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
- SupabaseOAuthcom.supabase
MCP server for interacting with the Supabase platform
Clamp Analytics MCP server: traffic, revenue, funnels, cohorts, errors, and search, for AI agents.
Related MCP Servers
- AlicenseAqualityDmaintenanceRead-only MCP server for Umami analytics. It talks to the Umami REST API directly over HTTP, supporting self-hosted and cloud setups.817MIT
- AlicenseNot gradedqualityBmaintenanceMCP server for Umami Analytics that provides read-only tools to query website stats, events, sessions, reports, and more, enabling natural language analytics queries.303MIT
- AlicenseAqualityBmaintenanceA security-first MCP server for Umami analytics (Cloud and self-hosted v3) enabling analytics, reporting, and administration with least privilege and credential-safe design.3217MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/webcredo/umami-compass'
If you have feedback or need assistance with the MCP directory API, please join our Discord server