Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@wireboard-mcp What's happening on my site right now?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Two ways to install, pick whichever fits your setup.
Download wireboard-mcp-x.y.z.mcpb from the GitHub releases page and double-click it. One file works on Windows, macOS, and Linux — Claude Desktop ships its own Node runtime, so there are no system dependencies to install.
Claude Desktop will prompt for your WireBoard API token, store it securely in your OS keychain, and the WireBoard tools become available immediately.
If double-click doesn't open the file, install it via Claude Desktop → Settings → Extensions → Advanced Settings → Install Extension.
npm install -g @wireboard/mcpRequires Node 18+. Then configure your MCP client of choice.
Edit claude_desktop_config.json (Settings → Developer → Edit Config):
{
"mcpServers": {
"wireboard": {
"command": "wireboard-mcp",
"env": {
"WIREBOARD_TOKEN": "your_token_here"
}
}
}
}Restart Claude Desktop. The WireBoard tools will appear automatically.
Use the same command + env-var pattern in your client's MCP config.
Related MCP server: rybbit-mcp
You need a WireBoard API token before either install path will work. Mint one at Settings → API with the analytics:read ability for REST tools and live:read for the live snapshot tool.
Once configured, ask Claude things like:
"How many visitors did my site get last week?"
"Show me the top 10 referrers for the past 30 days."
"What's happening on my site right now?"
"Which pages under /checkout have the worst bounce rate this month?"
"How many Purchase events fired from utm_source=newsletter yesterday?"
"Compare visitor counts day by day for the past two weeks."
Claude will pick the right tool, call it, and answer in natural language.
Tool | What |
| Every site in the account |
| Token-owner identity + abilities |
| Period totals: visitors, pageviews, bounce rate, duration |
| One metric (visitors or pageviews) bucketed by hour or day |
| Per-day visitors / returning / pageviews / bounce / duration |
| Top-N rows by dimension (country, device, browser, referrer, etc.) |
| Per-URL metrics with prefix / contains / exact filters |
| Custom event queries with grouping and filtering |
| Real-time snapshot (live visitor count, top pages, active sessions, etc.) |
| Meta: every dimension, metric, and limit the API supports |
All tools accept natural date ranges: "today", "yesterday", "last 7 days" (or "30d" shorthand), "this week", "last week", "this month", "last month", or explicit "YYYY-MM-DD..YYYY-MM-DD". Always UTC.
The MCP proactively caps itself at 100 requests/minute (under the API's 120/minute limit) so LLM bursts space themselves out instead of hitting 429s. Override with the WIREBOARD_MCP_RATE_PER_MINUTE env var if you have a use case that needs different pacing.
The underlying SDK still auto-retries on 429 as a backstop.
Treat your token like a credential. It has full analytics:read and live:read scope on every site in the account.
Don't commit your MCP client config to a public repo with the token in it. Use an env var or a secret manager and reference it from your config.
Revoke and rotate if a token leaks. Settings → API in your dashboard.
The MCP is read-only: it can fetch data, never modify it. The WireBoard public API itself is read-only in v1.
Logs go to stderr (so they don't interfere with the MCP protocol on stdout).
npm: @wireboard/mcp
Repository: github.com/wireboard/mcp
Releases (.mcpb downloads): github.com/wireboard/mcp/releases
Issues: github.com/wireboard/mcp/issues
Underlying SDK: @wireboard/api (source)
WireBoard docs: https://wireboard.io/docs/api-overview
npm install
npm test # run vitest
npm run build # bundle TS → dist/index.js (esbuild, ~600 KB)
npm run build:mcpb # also pack dist/wireboard-mcp-<version>.mcpbThe .mcpb is a zip of manifest.json, icon.png, and the single bundled dist/index.js. All runtime dependencies are inlined by esbuild.
MIT.
Get the team-owner identity (email, name) and the abilities of the token in use. Useful for verifying which account the MCP is connected to.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description indicates a read-only retrieval operation. No annotations are provided, but the description transparently discloses the non-destructive nature and what data is returned.
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?
Two concise sentences, front-loaded with the key action, no unnecessary words. Each word adds value.
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 zero parameters and no output schema, description adequately explains what is returned (email, name, abilities) and the use case. No gaps.
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?
Input schema has no parameters, so description does not need to explain them. Zero-parameter tools get baseline 4.
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?
Description clearly states it retrieves team-owner identity (email, name) and token abilities. It distinguishes itself from sibling tools which are analytics-focused, using a specific verb+resource.
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?
Explicitly states it's useful for verifying which account the MCP is connected to. No direct mention of when not to use, but with no parameters and clear purpose, it's sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Period totals for one site: visitors, pageviews, bounce_rate, visit_duration. Use this for 'how many visitors did site X get in date range Y' style questions.
| Name | Required | Description | Default |
|---|---|---|---|
| range | Yes | Date range. Accepts natural strings ('today', 'yesterday', 'last 7 days', 'last 30 days', 'this week', 'last week', 'this month', 'last month') or an explicit 'YYYY-MM-DD..YYYY-MM-DD' range. UTC. If you have separate from/to dates, use the explicit form. | |
| site_id | Yes | Site ID. Get it from list_sites if you don't know it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool returns aggregated metrics per site per period, implying a read-only query. However, it does not disclose potential edge cases (e.g., missing data, rate limits, or whether it's safe to call repeatedly). More details on non-destructive nature or data scope would have improved transparency.
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, highly concise. The first sentence front-loads the output and site constraint. The second provides a usage template. No unnecessary words, earning its place efficiently.
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?
With no output schema, the description should hint at the return format. It lists metrics but not their structure or data types. The schema covers parameters well. The description is adequate for a simple aggregate tool but could be improved by noting the output shape (e.g., a JSON object with those keys).
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?
Schema coverage is 100%—both parameters have detailed descriptions in the schema. The tool description adds no new parameter-specific information beyond what the schema already says. Baseline 3 is appropriate since the description meets but does not exceed the schema's guidance.
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 returns 'period totals for one site' with specific metrics (visitors, pageviews, bounce_rate, visit_duration). It provides a concrete usage example, making the purpose unambiguous. While sibling tools like get_timeseries and get_breakdown exist, the description's focus on aggregate totals and the example naturally differentiate it.
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 explicitly suggests using this tool for 'how many visitors did site X get in date range Y' style questions, providing clear context. However, it does not mention when to avoid this tool or list alternatives explicitly, which would make it a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Top-N rows by one dimension (country, device, browser, url, etc.). Use for 'top countries last week', 'most-used browsers', 'top referrer sources'. The dimension determines which field appears in each row alongside the visitor count.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max rows to return. Default 50, max 500. | |
| range | Yes | Date range. Accepts natural strings ('today', 'yesterday', 'last 7 days', 'last 30 days', 'this week', 'last week', 'this month', 'last month') or an explicit 'YYYY-MM-DD..YYYY-MM-DD' range. UTC. If you have separate from/to dates, use the explicit form. | |
| site_id | Yes | Site ID. Get it from list_sites if you don't know it. | |
| dimension | Yes | Which dimension to break down by. ref_url/ref_medium/ref_source/ref_search/ref_social are a partition of referrers (a referrer lands in exactly one). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies sorted results ('Top-N') and mentions visitor count, but lacks details on sorting direction, handling of invalid dimensions, or pagination. No annotations are provided, so the description carries the burden but only partially fulfills it.
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 concise with two sentences plus an explanatory note on referrer dimensions. It is front-loaded with the core purpose and no irrelevant 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?
While the description covers the main purpose and parameter semantics, it omits details about the output format (e.g., whether rows include only dimension value and count) and behavior for edge cases. Given no output schema, more completeness would help.
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?
Schema coverage is 100%, but the description adds value by explaining that the dimension determines the row field (e.g., 'country' appears as a column) and clarifies that referrer dimensions are a partition (mutually exclusive). This aids understanding beyond the enum list.
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 returns top-N rows by a selected dimension, with specific examples like 'top countries last week' and 'most-used browsers'. It distinguishes from siblings like get_aggregate (aggregate counts) and get_timeseries (time series) by focusing on breakdown by dimension.
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 provides explicit use cases ('Use for...') but does not explicitly state when not to use it or mention alternatives. However, the context and sibling tool names imply differentiation, and the guidance is sufficient for typical usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Per-day breakdown with visitors, returning_visitors, pageviews, bounce_rate, and avg_duration in a single call. Use when the user wants a 'daily report' or wants returning-visitor comparisons. Returns one row per UTC day in the range.
| Name | Required | Description | Default |
|---|---|---|---|
| range | Yes | Date range. Accepts natural strings ('today', 'yesterday', 'last 7 days', 'last 30 days', 'this week', 'last week', 'this month', 'last month') or an explicit 'YYYY-MM-DD..YYYY-MM-DD' range. UTC. If you have separate from/to dates, use the explicit form. | |
| site_id | Yes | Site ID. Get it from list_sites if you don't know it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states output granularity ('one row per UTC day') and lists the fields returned. It adds value beyond the schema by describing output structure, but omits details like authorization or rate limits.
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?
Two sentences, front-loaded with essential purpose and output details. No redundant or unnecessary text.
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 (2 parameters, no output schema, no annotations), the description is largely sufficient. It explains output and use case. Could be improved by mentioning any date range limits or result ordering, but overall provides good context.
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?
Schema coverage is 100%, baseline is 3. The description does not add new parameter-level information beyond what the schema already provides about range and site_id.
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 provides a per-day breakdown with specific metrics (visitors, returning_visitors, pageviews, bounce_rate, avg_duration). It also distinguishes from siblings by explicitly mentioning daily reports and returning-visitor comparisons.
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 gives explicit when-to-use guidance ('Use when the user wants a daily report or wants returning-visitor comparisons'). It does not explicitly mention when not to use, but the sibling context provides alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Current real-time snapshot for a site: live visitor count, top pages right now, current top referrers, active sessions, etc. Use for 'what's happening on the site right now', 'who's currently on the checkout page', 'how many visitors live'.
| Name | Required | Description | Default |
|---|---|---|---|
| site_id | Yes | Site ID. Get it from list_sites if you don't know it. | |
| categories | No | Subset of the 20 live categories to include. Omit to get all categories. Smaller subsets are faster. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It implies a read-only, non-destructive operation by describing a snapshot, but does not explicitly state safety or rate limits. Some behavioral context is missing.
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 concise: two sentences with no filler. The first sentence lists what the tool returns, the second provides example queries. Every word earns its place.
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?
For a real-time snapshot tool with no output schema, the description adequately lists the categories available. However, it does not describe the response structure (e.g., JSON shape), which slightly limits completeness.
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?
Schema description coverage is 100%, so the schema already documents both parameters well. The description adds value by suggesting where to get site_id, but does not significantly enhance understanding beyond the schema.
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 it provides a 'current real-time snapshot' with specific data like live visitor count and top pages. It distinguishes from siblings (e.g., get_aggregate, get_timeseries) by emphasizing real-time rather than historical or aggregate data.
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 includes explicit use cases ('what's happening on the site right now', 'who's currently on the checkout page'). While it doesn't explicitly state when not to use, the examples effectively convey appropriate contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One metric bucketed over time (hour or day). Use for 'plot pageviews per day this month' or 'visitors per hour today'. Returns an array of {time, value} points.
| Name | Required | Description | Default |
|---|---|---|---|
| range | Yes | Date range. Accepts natural strings ('today', 'yesterday', 'last 7 days', 'last 30 days', 'this week', 'last week', 'this month', 'last month') or an explicit 'YYYY-MM-DD..YYYY-MM-DD' range. UTC. If you have separate from/to dates, use the explicit form. | |
| metric | Yes | Which metric to plot. | |
| site_id | Yes | Site ID. Get it from list_sites if you don't know it. | |
| interval | Yes | Bucket size. Use 'hour' for short ranges, 'day' for longer. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It reveals the return format (array of {time, value} points) and notes bucket sizes, but does not mention ordering, pagination limits, or error handling. Adequate for 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?
Two sentences, zero waste. The first sentence states the core purpose, the second gives examples and return type. Efficient and front-loaded.
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?
The tool is simple with 4 parameters fully described in schema and guidance added in the description. Return format is explained. Lacks mention of error states or performance notes, but is otherwise complete for its complexity.
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?
Schema coverage is 100% and each parameter has a description. The description adds extra guidance (e.g., 'Use hour for short ranges, day for longer'), adding value beyond the schema. A minor improvement over baseline.
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 it returns one metric bucketed over time (hour or day), provides concrete examples ('plot pageviews per day', 'visitors per hour'), and distinguishes from sibling tools like get_aggregate or get_top_urls by focusing on time-series data.
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 gives explicit usage examples and implies when to use this tool (for plotting time-bucketed metrics). It lacks explicit exclusion statements but provides sufficient context for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Per-URL metrics (visitors, pageviews, bounce_rate, avg_duration) with optional filtering. Use for 'top pages under /blog', 'find the homepage's stats', 'which checkout pages have the worst bounce rate'. Paginated via limit and offset.
| Name | Required | Description | Default |
|---|---|---|---|
| exact | No | Match the URL that equals this string exactly. Like `prefix`, this is a full URL: scheme + host + path. | |
| limit | No | Max rows. Default 50, max 500. | |
| range | Yes | Date range. Accepts natural strings ('today', 'yesterday', 'last 7 days', 'last 30 days', 'this week', 'last week', 'this month', 'last month') or an explicit 'YYYY-MM-DD..YYYY-MM-DD' range. UTC. If you have separate from/to dates, use the explicit form. | |
| offset | No | Pagination offset. Default 0. | |
| prefix | No | Match URLs whose value starts with this string. URLs are stored as full URLs (scheme + host + path), so pass a full prefix like 'https://yoursite.com/blog/', NOT just '/blog/'. If you only have a path the user mentioned, use `contains` instead (matches the path as a substring anywhere in the URL). | |
| site_id | Yes | Site ID. Get it from list_sites if you don't know it. | |
| contains | No | Match URLs that contain this substring anywhere. Use this when the user gives you a path or a keyword without specifying the full URL (e.g. user says 'checkout pages' → contains='/checkout'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It mentions filtering options and pagination but does not address ordering of results, default behavior when no filter is applied, rate limits, or data freshness. The description is adequate but leaves some important behavioral aspects implicit.
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 exceptionally concise: two sentences summarizing the core functionality and filtering, followed by a list of clear use-case examples. Every sentence adds value, no wasted words, and the most important information is front-loaded.
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 complexity (7 parameters, no output schema, no annotations), the description covers the main metrics, filtering rules, and pagination. It could be more complete by mentioning the output format or default sorting, but the examples and schema details together provide sufficient context for most agent use cases.
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 schema has 100% coverage with already detailed descriptions for all 7 parameters. The description adds practical examples (e.g., 'checkout pages' → contains='/checkout') that clarify real-world usage and help differentiate between prefix and contains. This adds value beyond the schema without being redundant.
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 it provides per-URL metrics (visitors, pageviews, bounce_rate, avg_duration) with optional filtering, and gives concrete usage examples. While it effectively covers the tool's purpose, it does not explicitly differentiate from sibling tools like get_aggregate or get_breakdown, leaving some ambiguity.
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 provides explicit example queries ('top pages under /blog', 'find the homepage's stats', etc.) and mentions pagination via limit/offset. However, it does not specify when not to use this tool, nor does it suggest alternatives among siblings, which is a gap given the number of related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists every dimension, metric, and limit the API supports. Use as a self-discovery tool when the user asks something like 'what can you tell me about my analytics' or when you're unsure which dimension key to pass to get_breakdown.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool lists all supported dimensions, metrics, and limits, implying a read-only, safe operation. The behavioral scope is clear, though it does not mention return format or potential pagination.
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?
Two sentences: first defines purpose, second gives usage advice. No redundancy, every word earns its place.
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?
For a zero-parameter, no-output-schema tool, the description covers purpose and usage. It could hint at the output format (e.g., list of key-value pairs), but overall it is sufficient.
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 no parameters, so per guidelines the baseline is 4. The description correctly does not discuss parameters.
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 verb 'lists' and the objects 'every dimension, metric, and limit', establishing a specific purpose. It differentiates from sibling tools like get_breakdown by positioning itself as a self-discovery tool.
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 provides explicit usage scenarios ('when the user asks...' or 'when you're unsure which dimension key to pass'), giving clear context. However, it lacks explicit 'when not to use' guidance, which would elevate it to a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every site in the WireBoard account. Returns each site's ID, domain, and peak-concurrent-visitors over the last 30 days. Call this first if you don't know which site_id to use for the other tools.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses that it returns each site's ID, domain, and peak-concurrent-visitors over 30 days. Lacks details on performance or edge cases but sufficient for a simple list 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?
Two sentences, front-loaded with the operation and followed by usage advice. No redundancy, every word earns its place.
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 no output schema and zero parameters, the description explains the output and usage context well. Could mention potential large result sets but not critical for a simple list.
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?
No parameters exist, and schema coverage is 100%. The description adds meaning by explaining the return fields, which is beyond what the empty schema provides.
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 every site in the account and returns ID, domain, and peak-concurrent-visitors. It distinguishes from siblings which focus on aggregates, timeseries, etc.
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?
Explicitly advises to call this tool first if the site_id is unknown, providing direct guidance on when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query custom events (purchases, form submits, button clicks, etc.). Filter by category/action/label or UTM fields, group by any combination of those, paginate. Use for 'how many Purchase events from utm_source=newsletter last week' or 'top event categories this month'.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max rows. Default 50, max 1000. | |
| range | Yes | Date range. Accepts natural strings ('today', 'yesterday', 'last 7 days', 'last 30 days', 'this week', 'last week', 'this month', 'last month') or an explicit 'YYYY-MM-DD..YYYY-MM-DD' range. UTC. If you have separate from/to dates, use the explicit form. | |
| filter | No | Filters as {field: value}. Allowed top-level fields: category, action, label, utm_*. Event props go under {'props': {'key': 'value'}} which translates to filter[props.key]=value on the wire. | |
| offset | No | Pagination offset. Default 0. | |
| site_id | Yes | Site ID. Get it from list_sites if you don't know it. | |
| group_by | No | Fields to group by. Allowed: category, action, label, utm_campaign, utm_source, utm_medium, utm_content, utm_term. Default: ['category', 'action', 'label']. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It fails to mention that the tool is read-only, requires any specific permissions, or has rate limits or pagination behavior beyond offset/limit. The description focuses only on capabilities, not side effects or constraints.
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 concise (4 sentences), front-loads the purpose, and every sentence adds unique value—examples, filter/group capabilities, pagination mention. No wasted words.
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 no output schema and no annotations, the description adequately covers the tool's functionality, parameter semantics, and use cases. It lacks information about return format or expected behavior when no results are found, but overall it is reasonably complete for a query tool.
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?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the filter object structure (including props sub-object) and providing natural language date range examples that go beyond the schema's descriptions. This helps the agent understand parameter usage more effectively.
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 queries custom events with filters and grouping, and provides concrete examples like 'how many Purchase events from utm_source=newsletter last week', which distinguishes it from sibling tools like get_aggregate or get_timeseries.
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 gives explicit use cases ('use for...') that help the agent decide when to invoke this tool. However, it does not mention when not to use it or list alternative sibling tools, leaving some ambiguity about tool selection boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.3get_accountget_aggregateget_breakdownget_historyget_live_stateget_timeseriesget_top_urlslist_dimensionslist_sitesquery_eventsScored across 10 tools
Each tool targets a specific analytical need: period totals, time series, daily breakdown, top-N breakdown, real-time, URL stats, custom events, metadata, etc. Despite some overlapping metrics, the context and granularity are distinct, and descriptions clearly differentiate them.
All tools follow a consistent verb_noun pattern in snake_case, predominantly using 'get_' with a few 'list_' and one 'query_'. This minor variation is acceptable as 'list' and 'query' are appropriate for their functions.
With 10 tools, the set is well-scoped for a web analytics API. It covers essential operations without being excessive or insufficient, earning its place.
The tool set covers core analytics needs: site overview, time trends, daily reports, breakdowns, real-time, URL metrics, and custom events. Minor gaps like period-over-period comparison or advanced segmentation are not critical for general use.
Query your Betterlytics web analytics from AI agents: traffic, funnels, journeys, errors, uptime.
Real-time web analytics for AI agents: query traffic, funnels, revenue, and manage your sites.
AI access to Hitsteps analytics, live visitors, uptime, goals, alerts, and chats.
Privacy-first web analytics. Query pageviews, referrers, trends, and AI insights.
