Realtime count of unique visitors active in the last 5 minutes for a site. Returns {"site_id":123,"visitors":N}.
| Name | Required | Description | Default |
|---|---|---|---|
| site | No | Numeric site_id (preferred, from list_sites) or a domain, e.g. example.com — scheme, www. and path are ignored when matching. If several sites share the domain the call fails and lists their site_ids. Omit for a single-site key. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint:true already signals a safe read operation, lowering the bar. The description adds useful context by specifying the realtime nature and the exact return format, which is not redundant. However, it does not mention potential failure modes or rate limits, but these are not critical given the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences: one for the function, one for the return shape. The parameter description is also succinct but informative. No redundant or verbose wording is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and lack of an output schema, the description provides enough context: it states the input parameter's format, the return object, and that it is realtime. The absence of error handling or response status details is acceptable for a straightforward read-only metric.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'site' is described in detail: preferred numeric site_id, alternative domain format, handling of scheme/www/path, and failure behavior when multiple sites share a domain. This goes beyond the schema and provides complete guidance for correct usage, so the parameter semantics are excellent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: counting unique visitors active in the last 5 minutes for a site. It specifies the resource (visitors), the timeframe (realtime, 5 minutes), and the return shape. This distinguishes it from other analytics tools like query_stats or top_pages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool over alternatives. It mentions 'realtime' but does not provide guidance such as 'Use this for current visitor counts, and query_stats for historical data.' An agent could infer, but the instruction is not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Most tools map cleanly to distinct resources and actions: sites, goals, funnels, tracking settings, filters, and statistics. Some ambiguity exists between the generic query_stats and the many top_* / visitors_over_time convenience queries, but the descriptions mostly clarify when each should be used.
The CRUD tools consistently use create_, get_, list_, and update_ prefixes, but a sizable minority deviate: top_* forms a separate pattern, and current_visitors, funnel_report, and visitors_over_time are noun-phrase names rather than verb_noun.
25 tools sits at the heavy end for an analytics server. Many top_* tools overlap with what query_stats could do, making the count feel somewhat inflated, though the domain is broad enough that the number is not unreasonable.
The tool set covers site management, goals, funnels, tracking, filters, and statistics well. However, there are no delete operations for sites, goals, or funnels, leaving an obvious lifecycle gap and no way to clean up configured resources.
