Mark

Get Visitor Locations

get_visitor_locations

Read-onlyIdempotent

Where your site's visitors were over a period, by country, from your PostHog project: the Performance page's Visitors tab. A visitor is a PostHog person; countries are every located country, most visitors first, each with its ISO alpha-2 code, name, visitors and pageviews. unknown counts visitors PostHog couldn't place (GeoIP off, a reverse proxy that hides visitor IPs, or cookieless mode, where PostHog drops the IP); unknown.cookieless is how many of them came in cookieless mode. total sums the rows, so someone seen in two countries counts twice. state is ready, no-posthog (not connected), no-signal (PostHog has received no events yet) or failed, with reason: busy means PostHog didn't answer in time (it runs 3 queries at once per project and queues the rest), so try again in a minute; the PostHog connection is fine. error is any other failure, such as lost access, so check the PostHog connection. source ai_referral keeps only visits opened from an AI assistant's answer (ChatGPT, Perplexity, Claude, Gemini, Copilot and others), matched by referring domain or utm_source: the AI referrals card on the AI assistants tab. It is a floor: assistant clicks that arrive with no referrer and no utm_source can't be counted. Rank AI referrals by visitors, not pageviews: on a single-page site every pageview of the visit keeps the AI referrer, on a multi-page site only the first does. Does not change anything. Related: get_ai_visibility, get_content_performance, get_setup_status.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_visitor_locations"
  }
}

Input Schema

Name	Required	Description
`to`	No	Range end YYYY-MM-DD.
`from`	No	Range start YYYY-MM-DD. Defaults to the last 28 settled days.
`source`	No	all (default): every visit. ai_referral: only visits from an AI assistant's answer.

Output Schema

Name	Required	Description	Default
`to`	Yes
`from`	Yes
`appUrl`	Yes
`visitors`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 20, 2026

addedInput schema / properties / source

Added value: +{
+  "description": "all (default): every visit. ai_referral: only visits from an AI assistant's answer.",
+  "enum": [
+    "all",
+    "ai_referral"
+  ],
+  "type": "string"
+}

AddedOct 9, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations already declare read-only/non-destructive, and the description goes well beyond them: it explains what `unknown` means (GeoIP off, proxy masking, cookieless), that `unknown.cookieless` is a subset, that `total` double-counts multi-country visitors, and it enumerates the `state` vocabulary with retry semantics for `busy` (3 concurrent queries per project, retry in a minute) versus `error` meaning check the connection. That is exactly the operational context an agent needs to interpret a response and decide whether to retry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded correctly with purpose and scope, and every sentence carries information. But it is one undifferentiated ~250-word block mixing output semantics, state-machine behavior, and a deep caveat about AI-referral attribution; sub-structure or trimming of the cookieless/proxy detail would make it far more scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/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-shape explanation is not owed; the description nevertheless supplies the interpretation layer (unknown/total/state/source caveats) that the schema cannot. Nothing an agent needs to call this correctly or to decide whether to retry is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description earns above that by adding real meaning to `source=ai_referral` — matched by referring domain or utm_source, explicitly a floor rather than a complete count, and the caveat to rank by visitors not pageviews because of multi-page referrer attribution. `from`/`to` are left entirely to the schema, which is acceptable given full coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource+scope: visitor geography by country for a date range from the PostHog project, anchored to a named UI surface (Performance page's Visitors tab). It names the distinct output fields (ISO alpha-2 code, name, visitors, pageviews) and the related-but-different tools (get_ai_visibility, get_content_performance, get_setup_status), so an agent can separate it from siblings without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Use context is clear (geographic visitor breakdown over a period, or AI-referral traffic when source=ai_referral) and the siblings are listed, so the agent knows what adjacent questions go elsewhere. It stops short of explicit routing language such as 'use get_ai_visibility instead when…', so it is strong but not complete guidance.

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

All Mark tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?