list_sitesList the analytics sites this token can access. Returns a site handle to pass to the other tools. Call this first if you don't already have a site handle.
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals a safe read operation. The description adds valuable context by explaining the return value (a site handle) and its intended use, but doesn't disclose additional behavioral details like ordering or empty-list behavior, which are unlikely to be critical for such a simple tool.
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 sentences, front-loaded with the core purpose, followed by actionable guidance. Every sentence earns its place with no redundant information.
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 (no parameters, no output schema), the description fully covers what it does, when to call it, and what it returns. It is a complete and self-contained explanation.
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 tool has zero parameters, so the schema fully covers parameter semantics. The description doesn't need to explain parameters, and it appropriately focuses on the return value and usage, matching the baseline for a 0-parameter tool.
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 lists accessible analytics sites, which is a specific verb+resource. It also differentiates itself from sibling get_* tools by being the discovery endpoint that returns a site handle.
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?
It explicitly instructs to call this first if a site handle is not already available, providing clear when-to-use guidance. This also implies alternatives (the get_* tools) require the handle, distinguishing it from siblings.
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.
Each tool addresses a distinct analytics facet (overview, traffic, geo, audience, pages, funnel, live, weekly report, site context, site list) with no overlapping purposes. An agent can easily choose the right tool based on the question.
All tools follow a consistent verb_noun pattern (get_*) except list_sites, which still uses a clear verb_noun structure. The naming is uniform and predictable.
With 10 tools, the set is well-scoped for an analytics server, covering both summary and breakdown views without unnecessary bloat. Each tool earns its place.
The tool set covers core analytics needs: overview, traffic sources, audience, geo, pages, funnel, live, and weekly comparisons. Minor gaps like custom date ranges or event detail drill-downs are not critical for standard store analytics.