Skip to main content
Glama
umami-compass

umami-compass

by webcredo

Break down website metrics

get_metrics
Read-onlyIdempotent

Retrieves ranked aggregate Umami analytics breakdowns by metric type—paths, referrers, countries, devices, events, channels, or URLs—for a website and date range.

Instructions

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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "websiteId": "<websiteId>",
      "start": "<start>",
      "end": "<end>",
      "type": "<type>"
    },
    "name": "get_metrics"
  }
}

Input Schema

NameRequiredDescriptionDefault
endYesUnix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC)
typeYes
limitNo
startYesUnix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC)
offsetNo
searchNo
filtersNo
websiteIdYesUmami UUID

Output Schema

NameRequiredDescriptionDefault
dataYes
metaYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.5.2
    • addedOutput schema / properties / meta / properties / responseTruncated
      Added value: +{
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / meta / properties / sectionsTruncated
      Added value: +{
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / properties / meta / required
      Previous value: -[
      -  "dataStatus",
      -  "truncated"
      -]New value: +[
      +  "dataStatus",
      +  "truncated",
      +  "responseTruncated",
      +  "sectionsTruncated"
      +]
  2. First observedv0.4.1

TDQS

B3.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered structurally. The description adds two useful behavioral facts — results are ranked/aggregated, and visitor identifiers are excluded from the output — but says nothing about pagination behavior, the cost of large limits/offsets, or error conditions. The phrase 'excluded from the core toolset' is also ambiguous about whether identifier data exists elsewhere.

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?

Two sentences, front-loaded with the core action and immediately followed by the dimension examples. Nothing is padded, though the trailing scope sentence is slightly vague rather than crisply useful.

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?

This is a complex tool: 8 parameters, 4 required, nested filter objects with operators, and enum constraints. With an output schema present the return shape need not be explained, but the input side is severely under-described relative to that complexity, leaving the agent to reverse-engineer filters and pagination from the schema alone.

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 38% across 8 parameters, including a deeply nested filters object whose per-field operators and match semantics are undocumented in prose. The description only loosely mirrors the `type` enum values ('paths, referrers, countries...') and says nothing about limit, offset, search, filters, or the required start/end/websiteId semantics, so it fails to compensate for the coverage gap.

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 uses a specific verb and resource ('Get a ranked aggregate Umami metric breakdown') and enumerates the dimensions returned (paths, referrers, countries, devices, events, channels, URLs). It clearly conveys what the tool produces but never contrasts itself with close siblings such as get_website_stats or get_pageviews, leaving the agent to infer the boundary.

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?

Usage is only implied: the agent can infer it should call this when it wants a per-dimension ranked breakdown for a website. There is no explicit when-to-use, when-not-to-use, or pointer to an alternative tool, and the sibling list contains several plausible overlaps that go unaddressed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.