Skip to main content
Glama
umami-compass

umami-compass

by webcredo

Get active visitors

get_active_visitors
Read-onlyIdempotent

Retrieve the current number of active visitors for a specified Umami website by its ID to monitor live traffic.

Instructions

Get the current number of active visitors for a website.

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

Input Schema

NameRequiredDescriptionDefault
websiteIdYesUmami UUID

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
Behavior2/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety and repeatability are covered. The description adds almost nothing beyond that: it never clarifies what window 'active' covers (e.g., last 5/30 minutes), how fresh the count is, or what happens for an unknown websiteId.

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?

A single sentence, front-loaded with the verb and the resource, with no redundant or filler wording. Nothing could be removed without losing content.

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?

Output schema exists and annotations are rich, so return format and safety need not be described. However, for a real-time metric tool the undefined notion of 'active' (time window, sampling) is a meaningful interpretive gap that an agent would need in order to report the number correctly.

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% and the single websiteId parameter is documented in the schema as 'Umami UUID' with a UUID pattern, so the schema carries the parameter burden. The description adds no further meaning about that parameter, which is the correct baseline of 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 states a specific verb and resource ('Get the current number of active visitors') plus its scope ('for a website'), which clearly separates it from analytics siblings like get_pageviews or get_metrics that return historical aggregates. It stops short of explicitly naming a contrasting sibling, so it lands just under the top score.

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?

There is no when-to-use guidance: no mention of when an agent should call this instead of get_website_stats, get_pageviews, or a date-range tool. The word 'current' faintly implies real-time versus historical, but nothing states that trade-off or any prerequisite.

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