Skip to main content
Glama
umami-compass

umami-compass

by webcredo

Explain a traffic change

explain_traffic_change
Read-onlyIdempotent

Compare traffic against prior, year-over-year, or custom periods and rank shifts by page, referrer, country, device, channel, and event. Results show association, not causation.

Instructions

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.

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>"
    },
    "name": "explain_traffic_change"
  }
}

Input Schema

NameRequiredDescriptionDefault
endYesUnix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC)
limitNo
startYesUnix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC)
filtersNo
timezoneNoUTC
websiteIdYesUmami UUID
dimensionsNo
comparisonEndNoUnix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC)
comparisonModeNoprevious
trafficSegmentNoall
comparisonStartNoUnix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC)

Output Schema

NameRequiredDescriptionDefault
dataYesJSON analytics data returned by Umami Compass
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

A3.6/5.0
Behavior4/5

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

Annotations already establish that this is a safe, idempotent read, so the description is not required to restate that. It instead adds genuinely non-obvious behavioral context: results are ranked observations across dimensions and reflect 'association, not causation,' which materially constrains how an agent should report the output. It still omits how ranking is computed (absolute vs relative change, tie-breaking) and what the default limit of 10 with a max of 20 means for coverage.

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, both load-bearing, with the core comparison-and-rank action front-loaded before the caveat. No filler or restatement of the title; the only mild inefficiency is that the dimension list could have been left to the schema, though it usefully reveals supported groupings.

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?

An output schema exists, so return-value documentation is not required, and the description fairly covers purpose, dimensions, and comparison modes. For a tool with 11 parameters including a deeply nested filters object, it is still thin on filtering semantics, default behavior, and comparison-window alignment, which an agent must infer from the schema alone.

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 11 parameters and only 45% schema description coverage, the description must carry weight, and it does partially: the dimension list mirrors the dimensions enum (path, referrer, country, device, channel, event) and the three period modes mirror comparisonMode. It says nothing about filters (a large nested object), limit, timezone, trafficSegment, or how comparisonStart/comparisonEnd align to start/end, leaving the highest-cost parameters unexplained.

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 gives a specific verb-plus-resource ('Compare traffic with a previous, year-over-year, or custom period') and states the output shape ('rank observed changes across pages, referrers, countries, devices, channels, and events'), so an agent knows exactly what comes back. It stops short of naming a sibling such as compare_traffic_series to delineate the boundary between ranked-change explanation and raw series 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?

Usage is implied by enumerating the three comparison-period modes (previous, year-over-year, custom), which maps onto the comparisonMode enum and signals the intended diagnostic scenario. However, there is no explicit when-to-use versus alternatives guidance, no statement of prerequisites (e.g., a websiteId with sufficient historical data), and no exclusions or minimum-data caveats.

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