Skip to main content
Glama
umami-compass

umami-compass

by webcredo

Compare traffic time series

compare_traffic_series
Read-onlyIdempotent

Compare current and comparison traffic series bucket by bucket to pinpoint the exact day or hour when traffic changed.

Instructions

Return aligned current and comparison traffic buckets to locate the exact day or hour when traffic changed.

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": "compare_traffic_series"
  }
}

Input Schema

NameRequiredDescriptionDefault
endYesUnix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC)
unitNoday
startYesUnix milliseconds, ISO 8601 with timezone, or YYYY-MM-DD (UTC)
filtersNo
timezoneNoUTC
websiteIdYesUmami UUID
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

B3.1/5.0
Behavior3/5

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

Annotations already establish this is a read-only, idempotent, non-destructive query, so the safety profile is covered. The description adds genuine behavioral value by saying the two series are 'aligned' buckets, which tells the agent the comparison periods line up point-for-point — but it never states how the comparison window is derived (default 'previous'), how the unit affects alignment, or timezone handling.

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?

One sentence with no filler, and the result-then-purpose ordering is front-loaded and readable. It is efficient but so short that the compression costs useful detail given the parameter complexity.

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?

An output schema exists, so return values needn't be described, but for a 10-parameter tool with three comparison-related modes and a nested filter graph, the definition leaves the agent without enough to construct a comparison window or choose a granularity. The alignment claim implies a contract the description never spells out.

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 10 parameters and only 50% schema description coverage, the description needs to compensate and does not. It mentions comparison implicitly but never explains comparisonMode ('previous' vs 'year_over_year' vs 'custom'), comparisonStart/comparisonEnd, unit granularity, timezone, trafficSegment, or the large nested filters object — the very parameters that determine what 'aligned' means.

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 states a specific verb and output shape ('Return aligned current and comparison traffic buckets') plus the diagnostic intent ('locate the exact day or hour when traffic changed'), which is far more than a restatement of the name. It stops short of distinguishing itself from the nearby explain_traffic_change sibling, which an agent could easily confuse with this one.

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 the goal phrase 'to locate the exact day or hour when traffic changed' — an agent can infer this is for pinpointing the timing of a shift. There is no explicit when-not guidance and no named alternative for the closely related question of *why* traffic changed, so the agent must guess between this and explain_traffic_change.

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