Clamp Analytics
Server Details
Privacy-first web analytics, exposed to your AI agent as a first-class data source. The agent sees your traffic, referrers, geos, devices, live visitors, and custom events, and can reason across them. Ask what changed since the last deploy, why a campaign underperformed, which segment of signups actually activated, or have it build a conversion funnel and alert you when bounce rate spikes.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.5/5 across 27 of 27 tools scored. Lowest: 3.9/5.
Each tool targets a distinct resource and action, with clear separation even within groups like traffic and errors. Descriptions are detailed and unique, preventing ambiguity.
All tool names follow a consistent 'resource.action' pattern using snake_case (e.g., alerts.create, traffic.overview), with no deviations or mixed conventions.
27 tools is on the higher end but well-justified for a comprehensive analytics platform covering alerts, cohorts, errors, events, funnels, pages, revenue, sessions, traffic, and users.
The tool surface is very complete, covering core analytics workflows (traffic, events, errors, funnels, cohorts, revenue) with no obvious gaps. Missing update/delete for some resources are acceptable given the domain.
Available Tools
27 toolsalerts.createAIdempotentInspect
Create a metric alert that fires when a condition crosses its threshold. The alert monitors one metric (pageviews, visitors, sessions, bounce_rate, or avg_duration) over a rolling period and is re-evaluated every time an MCP session connects — alerts surface in-thread when the agent next checks, not as background pushes. Use to set lightweight monitoring like "alert me if pricing pageviews drop 50% week-over-week" or "alert me if bounce rate exceeds 70%". Requires Pro plan.
Examples:
pricing pageview drop → metric="pageviews", condition="drops_by", threshold=50, pathname="/pricing"
bounce rate ceiling → metric="bounce_rate", condition="above", threshold=70, period="7d"
traffic surge → metric="visitors", condition="increases_by", threshold=100, period="1d"
minimum-floor → metric="sessions", condition="below", threshold=100, period="1d"
Limitations: evaluation is on MCP session connect, not background — there are no push notifications, emails, or webhooks. Threshold for above/below is the absolute metric value; for drops_by/increases_by it is the percentage change vs the previous period of the same length. One alert per call — create multiple alerts for multiple conditions.
| Name | Required | Description | Default |
|---|---|---|---|
| metric | Yes | The metric to monitor. "pageviews" = total page views, "visitors" = unique visitors, "sessions" = total sessions, "bounce_rate" = % of single-page sessions (0-100), "avg_duration" = average session length in seconds. | |
| period | No | Evaluation window. Use "7d", "30d", etc. Defaults to "7d". Compared against the previous period of the same length. | |
| pathname | No | Scope the alert to a specific page path (e.g. "/pricing"). Omit to monitor all pages. | |
| condition | Yes | Alert condition. "above" = metric exceeds threshold, "below" = metric falls below threshold, "drops_by" = metric drops by threshold % compared to previous period, "increases_by" = metric increases by threshold % compared to previous period. | |
| threshold | Yes | Threshold value. For "above"/"below": the absolute metric value (e.g. 1000 pageviews). For "drops_by"/"increases_by": the percentage change (e.g. 50 means 50% drop/increase). | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. |
Output Schema
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| metric | Yes | |
| period | Yes | |
| pathname | Yes | |
| condition | Yes | |
| threshold | Yes | |
| created_at | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotentHint=true and readOnlyHint=false, but the description does not clarify duplication behavior or whether the call is safe to retry. It adds evaluation timing and plan requirement, but misses potential side effects.
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 three sentences, each adding unique value: purpose, evaluation timing, plan requirement. It is front-loaded and contains no filler.
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 absence of an output schema, the description does not describe the return value or error handling. While the schema is complete, behavioral context like rate limits or project scoping is missing.
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 input schema covers all parameters with 100% description coverage, so the description adds no extra semantic meaning. The schema already provides clear enums and explanations.
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 creates a metric alert, specifying it monitors a metric over a period and fires on threshold crossing. It distinguishes from sibling tools (alerts.delete, alerts.list) by its create action.
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 mentions 'Requires Pro plan' and 'Evaluated on each MCP session connect', providing usage constraints. While it doesn't explicitly exclude alternatives, the context implies use for creating alerts versus listing/deleting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
alerts.deleteADestructiveIdempotentInspect
Delete an alert by its id. Find the id by calling alerts.list first. The deletion is irreversible — there is no soft-delete or undo, and the agent should confirm intent with the user before calling this on a non-trivial alert. Returns 404 if no alert with that id exists for the project.
Examples:
"remove the pricing alert" → alerts.list to find the matching id, then alerts.delete with that id
"clear all alerts" → alerts.list, then alerts.delete for each id
Limitations: irreversible. Does not return the deleted alert's prior configuration — capture it from alerts.list first if you may need to recreate it. The alert_id must be the UUID returned by alerts.list, not a metric name.
| Name | Required | Description | Default |
|---|---|---|---|
| alert_id | Yes | The alert id (UUID) to delete. Get this from alerts.list. | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. |
Output Schema
| Name | Required | Description |
|---|---|---|
| ok | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds 'Irreversible', reinforcing the destructive nature. No contradiction with annotations.
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 only, front-loaded with the action, no redundant information. Highly concise and well-structured.
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 simple delete operation, the description covers the core action, prerequisite, and irreversibility. No output schema needed; the description is complete.
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% with descriptions for both parameters. The description adds minimal value beyond the schema, only reiterating that the alert_id comes from alerts.list. Baseline 3 is appropriate.
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 deletes an alert by its id, using a specific verb and resource. It also instructs to call alerts.list first to find the id, distinguishing it from sibling tools like alerts.create and alerts.list.
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 a clear prerequisite: call alerts.list first to find the id. It does not explicitly state when not to use it, but for a delete operation the context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
alerts.listARead-onlyInspect
List all alerts configured for a project. Returns each alert's id (UUID), metric, condition, threshold, period, optional pathname scope, and created_at timestamp. Use before alerts.delete to find the id you want to remove, or to show the user every monitor currently active. Returns an empty array if no alerts have been created yet.
Examples:
"what alerts do I have" → no extra params beyond project_id
before deleting → call alerts.list, locate the id, pass it to alerts.delete
Limitations: alert state (currently firing vs not) is not included — that surfaces only when the alert is re-evaluated on MCP session connect. There is no pagination; projects with many alerts return all of them in one response.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. |
Output Schema
| Name | Required | Description |
|---|---|---|
| alerts | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the specific return fields beyond the `readOnlyHint` annotation. It does not mention pagination or rate limits, but these are minor omissions 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, no wasted words. Front-loaded with purpose, then lists fields and usage guidance.
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?
Adequately covers purpose, return fields, and usage context for this simple read-only tool. Lacks details on pagination but not critical for this case.
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% with a thorough description of `project_id`. The tool description repeats the suggestion to use `projects.list`, which is already in the schema, adding no new semantic value.
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 all alerts for a project, specifies the returned fields, and differentiates from siblings like `alerts.delete` by mentioning its use to find alert IDs.
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 when to use: 'Use before alerts.delete to find the alert id, or to show the user what alerts are currently configured.' This provides clear context and excludes other uses.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
cohorts.compareARead-onlyInspect
Compare two saved cohorts side-by-side on retention. Returns each cohort's size and retention curve over the same period set, so you can read "did this week's signups retain better than last week's?" or "is this experiment cohort behaving differently than control?" without composing the rates manually.
Examples:
"did April 14 signups retain better than April 7" → a="signups_apr_14", b="signups_apr_07"
"are pro-plan signups stickier than free" → a="pro_signups_q2", b="free_signups_q2"
"compare two onboarding variants out to 4 weeks" → a="onboarding_v1", b="onboarding_v2", periods="1w,2w,4w"
Limitations: only two cohorts at a time. The same retention windows are applied to both — there's no way to use different windows per side. Sample-size caveats apply per cohort; check both size values before reading the rate delta.
| Name | Required | Description | Default |
|---|---|---|---|
| a | Yes | Name of the first cohort. | |
| b | Yes | Name of the second cohort. | |
| periods | No | Comma-separated retention windows, same format as cohorts.retention. | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. |
Output Schema
| Name | Required | Description |
|---|---|---|
| a | Yes | |
| b | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds valuable behavioral context: returns size and retention curve for both cohorts, applies same windows to both, notes inability to use different windows per side, and warns about sample-size caveats.
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?
Well-structured: purpose first, then examples, then limitations. Every sentence adds value, no filler. Bullet-list examples are effective. Front-loading aids quick understanding.
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, description sufficiently explains return values (size and retention curve). Covers all parameters, limitations, and usage scenarios. Complete for a comparison 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% (all parameters described). Description adds meaning beyond schema by providing examples of how to use 'a' and 'b' (e.g., 'signups_apr_14'), clarifying 'periods' format references sibling tool, and explaining 'project_id' auto-selection behavior.
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 compares two saved cohorts side-by-side on retention, with specific verb 'compare' and resource 'cohorts'. It distinguishes from siblings like cohorts.retention by focusing on comparison.
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?
Provides multiple concrete examples and explicit limitations (only two cohorts, same windows, sample-size caveats). Lacks explicit when-not-to-use or alternatives, but examples strongly imply appropriate use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
cohorts.createAIdempotentInspect
Create and persist a named cohort — a group of visitors defined by an event in a period, optionally narrowed by a property filter. The cohort is stored by name; subsequent retention/compare queries reference it without re-specifying the definition. Membership is recomputed at query time, not materialised, so the same cohort always reflects current data. Requires Pro plan.
The 0.x cohort definition is event-based: the user fired event between the period boundaries, optionally with filter.property == filter.value.
Examples:
"users who signed up the week of April 14" → name="signups_apr_14", definition={ event: "signup_completed", period: "2026-04-14:2026-04-20" }
"free-plan signups last month" → name="free_signups_last_month", definition={ event: "signup_completed", period: "30d", filter: { property: "plan", value: "free" } }
"customers who completed checkout in March" → name="checkouts_march", definition={ event: "checkout_completed", period: "2026-03-01:2026-03-31" }
Limitations:
Event-based definitions only in 0.x. Behavior cohorts ("did X then Y in order"), exclusion cohorts ("fired X but not Y"), and time-relative cohorts ("did X within N days of signup") aren't supported. The triggering event + period + property-filter shape covers ~95% of practical use cases.
Membership is computed at query time, so very large cohorts cost on every retention call.
Names must be lowercase alphanumeric with hyphens / underscores.
Pairs with: cohorts.retention to read the curve once the cohort is created; cohorts.compare for two-cohort side-by-side reads; cohorts.list to discover existing cohort handles.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Cohort name. Lowercase alphanumeric, hyphens, underscores. Used as the handle for retention / compare / delete. | |
| definition | Yes | Event-based cohort definition. | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. |
Output Schema
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| name | Yes | |
| size | Yes | |
| definition | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotentHint=true and destructiveHint=false. The description adds key behavioral details: membership is recomputed at query time (not materialized), and definitions are event-based only in 0.x. No contradictions with annotations.
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?
Description is well-structured with clear sections: purpose, behavior, examples, limitations. Front-loaded with main action. A few sentences could be condensed, but overall efficient for the complexity.
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?
No output schema is provided, but the description explains persistence and recomputation behavior, which suffices for usage. Could be improved by mentioning the response format, but current detail is adequate.
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 3. The description adds value through examples showing valid combinations, naming constraints, period formats, and project_id handling. Enhances understanding beyond schema alone.
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 explicitly states 'Create and persist a named cohort' with specific verb and resource. It distinguishes from siblings like cohorts.list, cohorts.delete, cohorts.retention, and cohorts.compare by focusing on the creation action and persistence behavior.
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 explains when to use (for retention/compare queries) and what is not supported (behavior cohorts). It also mentions Pro plan requirement. However, it does not explicitly contrast with alternatives like alerts.create or funnels.create, but the siblings list clarifies the domain.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
cohorts.deleteADestructiveIdempotentInspect
Delete a saved cohort by name. Irreversible — the agent should confirm intent with the user before calling this. The underlying event data isn't touched; only the cohort definition row is removed.
Examples:
"delete the test cohort" → name="test_cohort"
Limitations: irreversible. Returns 404 if the cohort doesn't exist. Definition is not returned before deletion — capture it from cohorts.list first if you may need to recreate it.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Cohort name to delete. | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. |
Output Schema
| Name | Required | Description |
|---|---|---|
| ok | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses irreversibility, the scope of deletion (only definition row, not event data), error behavior (404 on missing cohort), and the fact that the definition is not returned. This goes beyond annotations which only indicate destructiveHint and idempotentHint.
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 well-structured: it starts with the core action, then important warnings, followed by examples and limitations. It is concise with no extraneous information, though slightly longer than strictly necessary.
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 delete tool without an output schema, the description fully covers the mutation effect, error conditions, and necessary precautions. It tells the agent what to expect and how to prepare (e.g., capture definition beforehand). 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 descriptions are already present, but the description adds value by providing an example for the 'name' parameter and explaining when 'project_id' is required and how to discover its value. This enhances understanding beyond the schema alone.
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 'Delete a saved cohort by name,' using a specific verb and resource. It distinguishes from sibling tools like cohorts.create and cohorts.list, which serve different purposes.
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?
Provides explicit guidance: 'Irreversible — the agent should confirm intent with the user before calling this.' Also notes that the event data is untouched and advises capturing the cohort definition from list first if needed for recreation. Lacks an explicit 'when not to use' statement, but context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
cohorts.listARead-onlyInspect
List saved cohorts for the project. With name, returns one cohort with its current size; without, returns every cohort with their definitions. Use to discover cohort handles before calling retention or compare.
Examples:
"what cohorts do I have" → no params
"show me the signups_apr_14 cohort" → name="signups_apr_14"
Limitations: size is recomputed at fetch time and reflects current data — a cohort defined as "last 30d" returns a moving size as new events land.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Cohort name to fetch one. Omit to list all. | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. |
Output Schema
| Name | Required | Description |
|---|---|---|
| cohorts | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds behavioral details beyond the readOnlyHint annotation: size is recomputed at fetch time and moves for temporal definitions. No contradiction with annotations.
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?
Three tight paragraphs: overview, usage note, examples, limitation. Front-loaded with the key verb and resource. Every sentence 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?
Covers purpose, parameter behavior, limitations, and use cases. For a simple read-only list tool without an output schema, the description is sufficiently complete.
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?
With 100% schema coverage, the description adds operational context: explains the effect of providing vs. omitting name, and notes that size is included when name is given. This goes beyond the schema definitions.
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 'List saved cohorts for the project' and distinguishes behavior with and without the name parameter, establishing it as a discovery tool distinct from siblings like cohorts.retention or cohorts.compare.
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 'Use to discover cohort handles before calling retention or compare,' providing clear context for when to use. No explicit when-not-to-use, but the sibling list and examples imply alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
cohorts.retentionARead-onlyInspect
Compute the retention curve for a saved cohort. For each requested window (e.g. day 1, 7, 14, 30 after the cohort's anchor event), returns how many cohort members fired any non-pageview-end event in that day's window, and the rate vs the cohort size.
Use this to answer "did this cohort stick around?" and to compare retention across cohorts (via cohorts.compare). The 1-day-window resolution means "7d retention" is "day 7 specifically", not "anywhere in the first 7 days" — the standard product-analytics definition.
Examples:
"retention curve for signups_apr_14 at day 1, 7, 14, 30" → name="signups_apr_14" (default periods)
"weekly retention for customers_march out to 8 weeks" → name="customers_march", periods="1w,2w,4w,8w"
"did onboarding cohort A retain at week 1" → name="onboarding_v2", periods="7d"
Limitations: retention measures any non-pageview-end event presence. Custom retention metrics (e.g. "retained = fired purchase event") are not in 0.x. The numerator is computed per-day, so windows like "30d" return only day-30 activity. Cohort size is the denominator and is included in the response so consumers can apply sample-size discipline.
Pairs with: cohorts.compare for two-cohort side-by-side; cohorts.list to discover available cohort names.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Cohort name to query. | |
| periods | No | Comma-separated retention windows. Each is `<n>d` or `<n>w` (e.g. "1d,7d,14d,30d" or "1w,2w,4w,8w"). Defaults to "1d,7d,14d,30d". | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. |
Output Schema
| Name | Required | Description |
|---|---|---|
| size | Yes | |
| cohort | Yes | |
| retention | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint=true, but the description adds critical behavioral details: it returns counts of members firing any non-pageview-end event per window, the rate vs cohort size, and explains the 1-day-window resolution meaning. This goes beyond the annotation, providing full 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 concise and well-structured: purpose, usage, examples, limitations. Each sentence adds value, and it's front-loaded with the main action. 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?
Despite no output schema, the description explains what the response contains (counts and rates per window, cohort size) and addresses limitations. For a tool with 3 parameters, this is comprehensive and leaves no major 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 100% field descriptions, but the description adds value by explaining format of periods (e.g., '1d,7d,14d,30d' or '1w,2w,4w,8w'), default behavior, and project_id handling. Examples illustrate usage, making parameter meaning clearer.
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 explicitly states 'Compute the retention curve for a saved cohort,' clearly identifying the verb (compute) and resource (retention curve for a cohort). It distinguishes from sibling tools like 'cohorts.compare' by mentioning it for comparing retention, and other tools like 'cohorts.list' are clearly different.
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 guidance: 'Use this to answer did this cohort stick around?' and mentions alternatives via 'cohorts.compare'. It also includes examples and limitations (e.g., not for custom retention metrics, 1-day-window resolution), giving clear when-to-use and when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
docs.searchARead-onlyInspect
Keyword-search the Clamp documentation index for setup, SDK, MCP, concepts, and skills pages. Returns ranked entries with url, title, and a short description. Each match scores higher when query terms appear in the title than the description; results are capped by limit (default 5, max 10). Use when the user asks how to do something — install Clamp in Next.js, add the section-views extension, set up Money revenue, write an alert — rather than what their data shows. For data questions use the analytics tools above.
Examples:
"how do I install Clamp in Vite" → query="vite install"
"how do I track revenue from Stripe" → query="stripe revenue server"
"what does the section-views extension do" → query="section views extension"
"how do I set up an alert" → query="alerts setup"
Limitations: keyword (substring) matching only — no semantic search, so synonyms ("webhook" vs "callback") will not match. The index is hand-maintained inside the MCP server and updates only when the server is redeployed. Returns an empty array if no matches; broaden the query rather than retrying with the same terms.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results. Defaults to 5. | |
| query | Yes | Search query. |
Output Schema
| Name | Required | Description |
|---|---|---|
| query | Yes | |
| results | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, and the description aligns with that. The description adds context about the documentation content but doesn't disclose result behavior or search features. With annotations covering safety, the bar is lower, and the description provides adequate but not rich behavioral context.
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 provides usage guidance. No wasted words, information 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?
For a simple search tool with two parameters and no output schema, the description covers purpose and usage adequately. Could benefit from mentioning result format or search operators, but overall sufficient given the tool's simplicity.
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 100% description coverage for both parameters, so the description adds no additional meaning beyond the schema. Baseline score is appropriate.
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 'search', the resource 'Clamp documentation', and the scope 'setup, SDK, and MCP help'. It effectively distinguishes from sibling tools which are primarily data analytics tools.
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 when to use ('when the user asks how to do something') and what not to use for ('rather than what their data shows'). While it doesn't name specific alternative siblings, the guidance is clear and helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
errors.contextARead-onlyInspect
Breadcrumbs leading to one error: the events from the same session, before the error timestamp, in chronological order. The "what was the user doing right before this broke" view that turns a stack trace into a story.
Given an anonymous_id and the error's timestamp, finds the session that was active at that timestamp and returns up to limit events from that session strictly earlier than the error. Each event row has its name, url, pathname, referrer — enough to reconstruct the path the user took.
Examples:
"what did this user do right before the error" → anonymous_id from errors.list, before_timestamp = the error's timestamp
"show me the last 10 actions before this crash" → limit=10
"did the user click anything before the unhandled rejection" → check the events list for cta_click / button_clicked names
Limitations: scoped to the single session that contained the error. If the error fired during a session the user later ended (closed tab), and you pass a timestamp in a later session, you'll get that later session's events instead. Returns events only — not their full property bags (use users.journey if you need the per-event context). Default limit 20, max 100.
Pairs with: errors.list (source of the anonymous_id and timestamp pair); users.journey (multi-session view of the same user, when one-session breadcrumbs aren't enough).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max events to return. Defaults to 20, max 100. Increase only if a longer breadcrumb is needed; agents typically read the most recent ones first. | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. | |
| anonymous_id | Yes | The visitor whose session leading up to the error you want to inspect. Pull this from an errors.list row. | |
| before_timestamp | Yes | ISO 8601 timestamp of the error itself. Returns events strictly earlier than this from the same session. |
Output Schema
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| events | Yes | |
| anonymous_id | Yes | |
| before_timestamp | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses behavioral traits beyond the `readOnlyHint` annotation: it returns events strictly earlier than the timestamp, scoped to the session, with default/max limit, and specific output fields. It also warns about potential pitfalls with session mismatches.
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 well-structured with clear sections (overview, parameter details, examples, limitations, pairings) and front-loaded purpose. While slightly long, every sentence adds value, so a 4 is appropriate.
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?
Despite no output schema, the description explains the output fields (name, url, pathname, referrer) and covers limitations, edge cases, and related tools. For a complex tool with 4 parameters and required inputs, this is fully 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?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining parameter usage in context (e.g., 'Pull this from an errors.list row' for anonymous_id, clarifying limit defaults and max, and explaining the before_timestamp logic). This extra context justifies a 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?
The description clearly states the tool retrieves breadcrumbs leading to an error, specifically events from the same session before an error timestamp. It distinguishes from siblings like `users.journey` by focusing on a single session.
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 when-to-use examples, including how to obtain `anonymous_id` from `errors.list` and set `before_timestamp`. It also lists limitations (single session scope) and paired tools (`errors.list`, `users.journey`), offering clear guidance on when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
errors.groupsARead-onlyInspect
Errors deduplicated by server-computed fingerprint, with counts and first/last-seen timestamps. The triage view: which bugs are firing most often, affecting the most users, or showing up newly in the period.
Each group is one fingerprint (a bug). count is total occurrences in the period; users_affected is unique anonymous_ids that hit it; first_seen and last_seen show the time window the bug appeared in. sample_message and sample_type are pulled from one occurrence in the group — useful for the agent to surface a readable label.
Examples:
"what's broken right now" → period="today", sort_by="count"
"regressions that started this week" → period="7d", sort_by="first_seen"
"bugs hitting the most users" → sort_by="users_affected"
"what just stopped firing" → check last_seen against expected freshness
Limitations: only fingerprintable errors are grouped; events with neither message nor stack get a null fingerprint and are excluded from this view (they still show up in errors.list). Default sort is by count; pass sort_by to change. Default limit 50, max 200.
Pairs with: errors.list (drill into a fingerprint to see individual occurrences with full context); errors.timeline (chart the rate of one fingerprint to spot regressions or post-deploy regressions); traffic.compare (correlate a count spike with a deploy or campaign).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max rows to return (1-50). Defaults to 10. | |
| period | No | Time period. Use "today", "yesterday", "7d", "30d", "90d", or a custom range as "YYYY-MM-DD:YYYY-MM-DD" (e.g. "2026-01-01:2026-03-31"). Defaults to "30d". | |
| sort_by | No | Order groups by total occurrences (default), unique users affected, most recent occurrence, or earliest occurrence. Sort is always descending. | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. |
Output Schema
| Name | Required | Description |
|---|---|---|
| groups | Yes | |
| period | Yes | |
| sort_by | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, but the description adds valuable context: defaults (limit 50, max 200, period 30d), sort options, and the fact that errors with null fingerprint are excluded.
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 well-structured with clear paragraphs for purpose, fields, examples, limitations, and related tools, though slightly verbose; it could be tightened but remains effective.
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?
Despite no output schema, the description fully explains the returned fields, default behavior, edge cases, and complementary tools, making it comprehensive for the tool's 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?
While schema coverage is 100%, the description adds significant meaning by explaining output fields (count, users_affected, sample_message) and providing usage examples for each parameter option, exceeding the 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 defines the tool as a triage view for deduplicated errors with aggregated statistics, and it distinguishes itself from sibling tools like errors.list and errors.timeline.
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 provides explicit when-to-use guidance via examples (e.g., 'what's broken right now'), limitations (null fingerprint excluded), and pairs with alternatives for drill-down or trend analysis.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
errors.listARead-onlyInspect
Recent error events with full context. One row per occurrence, returned newest-first. Each row carries the error itself (message, type, stack, fingerprint, handled flag) plus the standard event context (url, browser/OS/device, country, anonymous_id, session_id) — same shape ingest enriches every other event with, so an agent can correlate "errors here, traffic there" without joining a second tool.
Errors are written to the events table with name = "$error" by the SDKs' captureError() / window.onerror auto-capture. The server adds a stable error.fingerprint at ingest (sha256 of normalized message + first stack frame), so the same bug groups across occurrences regardless of which session or SDK reported it.
Examples:
"what errors fired today" → period="today" (no other filters)
"show me all TypeError occurrences this week" → message="", or use errors.groups first to find the fingerprint
"errors on Safari only" → browser="Safari"
"errors on the same fingerprint" → fingerprint=""
"only the auto-captured ones, not manual reports" → handled="false"
Limitations: returns up to limit rows (default 50, max 200). Stacks are stored verbatim from the SDK with no source-map resolution — production stacks will be minified for users on a build pipeline. For aggregate counts and dedup, use errors.groups; for breadcrumbs leading to one error, use errors.context.
Pairs with: errors.groups (find a noisy fingerprint, then list its occurrences here); errors.context (drill from one error row into the events from the same session that led to it); users.journey (full multi-session view of a user who hit an error).
| Name | Required | Description | Default |
|---|---|---|---|
| os | No | Filter by OS name (e.g. "macOS", "Windows", "iOS", "Android"). | |
| limit | No | Max rows to return (1-50). Defaults to 10. | |
| period | No | Time period. Use "today", "yesterday", "7d", "30d", "90d", or a custom range as "YYYY-MM-DD:YYYY-MM-DD" (e.g. "2026-01-01:2026-03-31"). Defaults to "30d". | |
| browser | No | Filter by browser name (e.g. "Chrome", "Safari", "Firefox"). Case-sensitive; use the exact value the SDK reports. | |
| country | No | Two-letter ISO country code (e.g. "US", "DE"). Useful when an error correlates with a CDN edge or a localization issue. | |
| handled | No | Filter to handled (manual captureError calls) or unhandled (window.onerror / unhandledrejection auto-capture). Omit to return both. | |
| message | No | Filter by exact error message (matches the `error.message` property). Use a known message verbatim; substring matching is not supported. | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. | |
| device_type | No | Filter by device type. Use this to isolate mobile-only bugs. | |
| fingerprint | No | Filter by server-computed fingerprint (16-char hex). Get fingerprints from errors.groups; same fingerprint groups all occurrences of the same bug. |
Output Schema
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| errors | Yes | |
| period | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details how errors are captured by SDK, server adds fingerprint, stacks are stored verbatim without source-map resolution, and the limit/max rows. Annotations provide readOnlyHint=true, which is consistent. The description adds significant behavioral context beyond annotations.
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 well-structured: starts with core purpose, then details, examples, limitations, and related tools. Each sentence adds value, and the most critical information is front-loaded. Length is justified by the complexity of the tool.
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 10 parameters and no output schema, the description is remarkably complete. It explains the return format, data shape, error capture process, fingerprinting, limitations, and pairs with siblings. An agent has sufficient context to use the tool correctly.
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% with detailed parameter descriptions. The description adds value through usage examples and explains the overall data shape (error + event context). While not essential, it enhances understanding of how parameters relate to the output.
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 lists recent error events with full context, returned newest-first, and specifies each row contains error details and standard event context. It distinguishes from siblings like errors.groups and errors.context, so an agent can easily understand its purpose.
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?
Explicit examples are given for various use cases (e.g., 'what errors fired today', 'errors on Safari only') and when not to use it (aggregate counts use errors.groups, breadcrumbs use errors.context). It also mentions limitations and pairs with related tools, providing clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
errors.timelineARead-onlyInspect
Error count over time, bucketed hourly or daily. Optionally scoped to one fingerprint. Use this to spot regressions ("when did this bug start firing?") or post-deploy spikes ("did the deploy at 14:00 break something?").
Returns a series of { bucket, count } rows. The bucket field is an ISO timestamp aligned to the start of the interval. Buckets with no errors are omitted (sparse series); the agent should treat missing buckets as zero.
Examples:
"error rate over the last week" → period="7d" (returns hourly buckets)
"did errors spike after yesterday's deploy" → period="2d", interval="hour"
"is this specific fingerprint getting worse" → fingerprint="", period="30d"
"yearly error trend" → period="365d", interval="day"
Limitations: interval defaults to "hour" for periods ≤ 7 days, "day" otherwise. Override only if the default produces too few or too many buckets for the question. No fingerprint filter returns the total error rate across all bugs.
Pairs with: errors.groups (find which fingerprint is worth charting); traffic.timeseries (compare error count to traffic count to see if the rate is real or just a traffic surge); traffic.compare (week-over-week or before-after-deploy comparison).
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | Time period. Use "today", "yesterday", "7d", "30d", "90d", or a custom range as "YYYY-MM-DD:YYYY-MM-DD" (e.g. "2026-01-01:2026-03-31"). Defaults to "30d". | |
| interval | No | Bucket size. Defaults to "hour" for periods ≤ 7 days, "day" otherwise. | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. | |
| fingerprint | No | Optional fingerprint (16-char hex from errors.groups) to scope the chart to one bug. Omit for total error rate. |
Output Schema
| Name | Required | Description |
|---|---|---|
| period | Yes | |
| series | Yes | |
| interval | Yes | |
| fingerprint | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and description adds critical behavior: sparse series (missing buckets = zero), ISO timestamp alignment, and interval default logic. No contradictions.
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?
Well-structured: concise definition, usage context, examples, limitations, and pairings. Every sentence adds value without redundancy.
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?
Fully explains return format (bucket, count), sparse series behavior, and pairing with other tools. No output schema needed given the clear description.
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 covers 100% of parameters, but description enriches with concrete examples (e.g., '7d', '2d') and clarifies defaults and scoping behavior (no fingerprint = total error rate).
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?
Clearly states it provides error count over time with optional hourly/daily bucketing and fingerprint scoping. Distinguishes from siblings like errors.groups and traffic.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?
Explicitly describes when to use (regression spotting, deploy spike detection) and provides examples for different scenarios. Lists paired tools for alternative uses and limitations of interval defaults.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
events.listARead-onlyInspect
Get custom event counts. Without a name filter, returns every event name in the period with its total count and unique-visitor count (excludes "pageview" and the SDK-internal "pageview_end"). With a name filter, returns the count for that single event, optionally filtered by a custom property key/value pair and grouped by another property key. Custom events are tracked client-side via clamp.track("event_name", { key: "value" }) or server-side via @clamp-sh/analytics/server.
Property values can be strings, numbers, or booleans (each stored in a separate column). When filtering or grouping by a numeric or boolean property, set value_type / group_by_type so the lookup hits the right column — otherwise the default ("string") will silently miss native number/boolean data. Use the project's event-schema.yaml to know each property's type.
Examples:
"what events are being tracked" → no params (lists all event names)
"how many signups this week" → name="signup", period="7d"
"signups grouped by plan" → name="signup", group_by="plan"
"paid signups only" → name="signup", property="plan", value="pro"
"checkouts where item count was 5" → name="checkout", property="count", value="5", value_type="number"
"events grouped by a numeric tier_id" → name="upgrade", group_by="tier_id", group_by_type="number"
Limitations: only one property/value pair per call. group_by only works when a name filter is set. Returns at most limit rows per group (default 10, max 50). For revenue use revenue.sum, which understands the Money type.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Filter to a specific event name (e.g. "signup", "checkout_completed", "button_clicked"). Event names are case-sensitive strings set by the developer. | |
| limit | No | Max rows to return (1-50). Defaults to 10. | |
| value | No | Filter to events where the property key equals this value. Must be used together with the "property" parameter. Pass the value as a string regardless of underlying type; combine with "value_type" for numbers/booleans. | |
| period | No | Time period. Use "today", "yesterday", "7d", "30d", "90d", or a custom range as "YYYY-MM-DD:YYYY-MM-DD" (e.g. "2026-01-01:2026-03-31"). Defaults to "30d". | |
| channel | No | Traffic channel. One of: "direct", "organic_search", "organic_social", "paid", "email", "referral". | |
| country | No | ISO 3166-1 alpha-2 country code, uppercase (e.g. "US", "GB", "DE", "NL", "JP"). Filter results to visitors from this country. | |
| group_by | No | Group results by this custom property key (e.g. "plan" to see signups broken down by plan). Returns each unique value with its count. Must be used with a name filter. | |
| pathname | No | Filter to a specific page path (e.g. "/pricing", "/blog/my-post"). Must start with /. | |
| property | No | A custom property key to filter or group by (e.g. "plan", "source", "button_id"). Property keys are strings, max 128 chars. Only works when a name filter is set. | |
| utm_term | No | Filter by UTM term (e.g. "running+shoes"). Case-sensitive. | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. | |
| utm_medium | No | Filter by UTM medium (e.g. "cpc", "email", "social"). Case-sensitive. | |
| utm_source | No | Filter by UTM source (e.g. "google", "twitter", "newsletter"). Case-sensitive, must match the value in the tracking URL. | |
| value_type | No | Type of the value being filtered. Defaults to "string". Set to "number" or "boolean" when the property is declared as such in event-schema.yaml — otherwise the lookup hits the wrong column and returns no matches. | |
| device_type | No | Device category. One of: "desktop", "mobile", "tablet". | |
| utm_content | No | Filter by UTM content (e.g. "hero-cta", "sidebar-banner"). Case-sensitive. | |
| utm_campaign | No | Filter by UTM campaign name (e.g. "spring-launch", "product-hunt"). Case-sensitive. | |
| group_by_type | No | Type of the group_by property. Defaults to "string". Set to "number"/"boolean" for numeric/boolean properties; results come back stringified ("5", "true") for transport. | |
| referrer_host | No | Filter by referrer hostname (e.g. "news.ycombinator.com", "twitter.com", "github.com"). Use this to see what traffic from a specific source did. Must match the value returned by `traffic.breakdown(dimension="referrer_host")` exactly (lowercase, no protocol or path). |
Output Schema
| Name | Required | Description |
|---|---|---|
| events | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true. The description adds behavioral details: returns counts, excludes 'pageview', supports filtering and grouping. It does not mention rate limits or auth, but the addition of custom event tracking context and exclusion behavior is valuable.
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 main purpose. It covers key behaviors efficiently. Slightly more structure could improve readability, but it is well above average.
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 17 parameters and no output schema, the description provides a high-level overview that covers essential behavior (with/without name filter, exclusion of pageview, filtering/grouping). It does not detail all parameters but schema covers them. The added context on event tracking makes it fairly complete.
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%. The description adds meaning by explaining custom event tracking via clamp.track and the grouping/filtering behavior, which complements schema descriptions. The baseline of 3 is elevated because the description provides useful context not in 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 'Get custom event counts' and explains behavior with and without a name filter. It distinguishes from sibling tools by focusing on custom events tracked via clamp.track, excluding 'pageview', which is a different category from traffic or pages tools.
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 clear context on when to use the name filter vs not, and mentions filtering by custom property, grouping, and the exclusion of pageview. It does not explicitly mention alternatives or when not to use this tool, but the context is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
events.observed_schemaARead-onlyInspect
Return what's actually firing into ingest as a structured signature, for diffing against the project's authored event-schema.yaml. Different shape from the YAML — this is observation, not declaration.
Response shape:
{
period: "30d",
events: [
{ name: "checkout", count: 42,
properties: {
plan: [{ type: "string", occurrences: 42 }],
count: [{ type: "number", occurrences: 39 },
{ type: "string", occurrences: 3 }] // ← drift!
}}
]
}Each property value is an array of typed observations. One entry = the key consistently fired with one type. Two-plus entries = same key fired under multiple storage columns in the period, which is exactly the silent-type-drift signal you want to surface (one call site sending count: 5, another sending count: "5").
Use it to compare declared vs reality:
Events declared, missing here → dead instrumentation
Events here, not declared → unauthored events firing
Properties on a declared event missing from the schema → silent property drift
properties[key].length > 1→ type-column collision; one of the call sites is sending the wrong type
Examples:
"what events are firing in production" → no params (defaults to 30d, excludes pageview/pageview_end)
"did the spec drift this week" → period="7d"
"include automatic pageview events too" → include_pageviews=true
Limitations: returns keys + types only, no property values. occurrences is row-level (each event firing counts), not unique visitors. Excludes pageview and pageview_end by default since the SDK extension owns their schema.
Pairs with: events.list for per-event volume context (this tool also returns count, but events.list supports filters and grouping); the local event-schema.yaml for declared-vs-observed diff.
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | Time period. Use "today", "yesterday", "7d", "30d", "90d", or a custom range as "YYYY-MM-DD:YYYY-MM-DD" (e.g. "2026-01-01:2026-03-31"). Defaults to "30d". | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. | |
| include_pageviews | No | Include pageview and pageview_end in the output. Defaults to false. |
Output Schema
| Name | Required | Description |
|---|---|---|
| events | Yes | |
| period | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds behavioral context: returns keys+types only, occurrences is row-level, excludes pageview/pageview_end by default. No contradictions.
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?
Well-structured: front-loaded purpose, then response shape, use cases, examples, limitations. Every sentence is informative with no waste.
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 tool complexity (schema diffing, 3 params, no output schema), description is complete: explains response structure, use cases, limitations, and provides examples. 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?
Schema coverage is 100% with descriptions, but the description adds meaning: explains period defaults, exclude pageview default, project_id required for multi-project, and shows usage examples. Goes beyond 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 the tool returns actual ingested event schema as a structured signature for diffing against declared schema. It distinguishes itself from siblings like events.list by focusing on schema shape rather than raw events.
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?
Provides explicit when-to-use scenarios: comparing declared vs reality, detecting dead instrumentation, unauthored events, silent property drift, type-column collisions. Includes concrete examples and mentions limitations like no property values.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
funnels.createAIdempotentInspect
Create and immediately evaluate a conversion funnel. A funnel measures how many unique visitors complete an ordered sequence of steps. Returns step-by-step counts, per-step conversion rates (vs the previous step), and overall conversion (last step / first step). The funnel is saved by name and can be re-evaluated later or for different periods via funnels.list.
Step format: a custom event name like "signup", a pathname-scoped pageview like "pageview:/pricing", and optionally one or more property predicates appended in brackets — "cta_click[location=hero_primary]" matches only cta_click events whose location property equals "hero_primary". Stack predicates to AND them: "cta_click[location=hero_primary][plan=pro]". Predicates work on pageview steps too: "pageview:/pricing[utm_source=google]". Requires Pro plan.
Predicates default to string-typed comparisons (the property is read from the string column). For number- or boolean-typed properties (declared as such in event-schema.yaml), append a type tag: "purchase[count:n=5]" matches numeric 5; "checkout[refunded:b=false]" matches boolean false; "purchase[plan:s=5]" forces string matching when the value looks numeric. Tags: ":n" number, ":b" boolean (true|false|1|0), ":s" string (default).
Examples:
pricing-to-signup → name="pricing-to-signup", steps=["pageview:/pricing", "signup"]
which CTA actually converts → name="hero-cta-funnel", steps=["cta_click[location=hero_primary]", "signup_completed"]
onboarding flow → name="onboarding", steps=["signup", "onboarding_started", "onboarding_completed", "first_purchase"]
multi-item checkouts only → name="multi-item-checkout", steps=["pageview:/cart", "checkout_completed[items:n=3]"]
non-refunded purchases → name="purchase-net", steps=["pageview:/pricing", "purchase[refunded:b=false]"]
blog-to-newsletter → name="blog-newsletter", steps=["pageview:/blog", "newsletter_subscribed"]
Limitations: between 2 and 10 steps; step strings ≤500 chars; names ≤200 chars. Step order matters — once a session skips a step, it cannot complete later steps. Pageview pathnames match exact strings only (no wildcards). Predicate keys must be snake_case; string values may not contain ']' or '['. Number predicates require a finite value; boolean predicates require true|false|1|0. Funnel evaluation is per-session, not per-user across devices.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | A descriptive name for this funnel (e.g. "pricing-to-signup", "onboarding-flow"). Used to retrieve it later. Max 200 chars. | |
| steps | Yes | Ordered array of 2-10 funnel steps. Each step: a custom event name ("signup"), a pathname-scoped pageview ("pageview:/pricing"), or either form with property predicates appended in brackets ("cta_click[location=hero_primary]", "pageview:/pricing[utm_source=google]"). Stack predicates to AND them: "cta_click[location=hero_primary][plan=pro]". Predicates default to string matching; append ":n" for number ("checkout[items:n=3]"), ":b" for boolean ("purchase[refunded:b=false]"), or ":s" to force string when the value looks numeric ("plan:s=5"). | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. |
Output Schema
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| name | Yes | |
| steps | Yes | |
| period | Yes | |
| overall_conversion | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the funnel is saved for later retrieval and returns step-by-step counts, conversion rates, and overall conversion. Annotations already indicate idempotentHint=true, readOnlyHint=false, destructiveHint=false. No contradiction, but idempotency behavior could be clarified.
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?
Three concise sentences with no wasted words. The description is front-loaded with the core action and immediately provides key details about steps and return values.
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?
Despite no output schema, the description covers what is returned (step-by-step counts, conversion rates, overall conversion) and mentions the funnel is saved for later retrieval and the Pro plan requirement. All relevant aspects are addressed.
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 meaningful context beyond schema: explaining step format (event name or 'pageview:/path') and project_id usage (required for multi-project access, references projects.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 creates and immediately evaluates a conversion funnel, tracking unique visitors through steps. It differentiates from siblings like funnels.get which retrieves existing funnels.
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 explains the tool is for tracking unique visitors through a sequence of steps and mentions the Pro plan requirement. It implies usage context but does not explicitly state when not to use it or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
funnels.listARead-onlyInspect
Retrieve and re-evaluate a previously created funnel against current data for the specified period. Without a name, lists all funnels saved for the project. With a name, returns the same step-by-step counts and conversion rates as funnels.create, recomputed for the requested period and any cohort filters. Cohort filters (channel, country, device_type, utm_*) let you compare conversion across segments — e.g. mobile users from the US who came via organic search.
Examples:
list all funnels → no params
"how is pricing-to-signup converting this month" → name="pricing-to-signup", period="30d"
"mobile conversion for onboarding" → name="onboarding", device_type="mobile"
"paid traffic vs organic conversion" → call twice with channel="paid" then channel="organic_search"
Limitations: returns 404 if no funnel exists by that name — call funnels.list with no name first to enumerate. Cohort filters apply at the session level, not retroactively per step. Funnel definitions are immutable after creation (re-create with a new name to change steps).
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | The funnel name to retrieve. Omit to list all funnels for the project. | |
| period | No | Time period. Use "today", "yesterday", "7d", "30d", "90d", or a custom range as "YYYY-MM-DD:YYYY-MM-DD" (e.g. "2026-01-01:2026-03-31"). Defaults to "30d". | |
| channel | No | Traffic channel. One of: "direct", "organic_search", "organic_social", "paid", "email", "referral". | |
| country | No | ISO 3166-1 alpha-2 country code, uppercase (e.g. "US", "GB", "DE", "NL", "JP"). Filter results to visitors from this country. | |
| pathname | No | Filter to a specific page path (e.g. "/pricing", "/blog/my-post"). Must start with /. | |
| utm_term | No | Filter by UTM term (e.g. "running+shoes"). Case-sensitive. | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. | |
| utm_medium | No | Filter by UTM medium (e.g. "cpc", "email", "social"). Case-sensitive. | |
| utm_source | No | Filter by UTM source (e.g. "google", "twitter", "newsletter"). Case-sensitive, must match the value in the tracking URL. | |
| device_type | No | Device category. One of: "desktop", "mobile", "tablet". | |
| utm_content | No | Filter by UTM content (e.g. "hero-cta", "sidebar-banner"). Case-sensitive. | |
| utm_campaign | No | Filter by UTM campaign name (e.g. "spring-launch", "product-hunt"). Case-sensitive. | |
| referrer_host | No | Filter by referrer hostname (e.g. "news.ycombinator.com", "twitter.com", "github.com"). Use this to see what traffic from a specific source did. Must match the value returned by `traffic.breakdown(dimension="referrer_host")` exactly (lowercase, no protocol or path). |
Output Schema
| Name | Required | Description |
|---|---|---|
| funnels | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors beyond readOnlyHint: 404 on missing name, immutability of funnel definitions, cohort filters apply at session level. These add significant context not in annotations.
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?
Well-structured with paragraphs for description, examples, and limitations. Every section adds value, though slightly verbose. Front-loads key info.
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 13 optional params and no output schema, the description covers usage patterns and limitations adequately. Lacks detailed output shape or pagination info, but examples compensate. Could mention response format briefly.
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 3. Description adds usage examples showing parameter combinations (e.g., name + device_type) and explains cohort filter behavior. This provides meaningful extra 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 retrieves and re-evaluates a funnel, with or without a name. It distinguishes from funnels.create by noting it returns the same data recomputed. The verb 'Retrieve' and resource 'funnel' are explicit.
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?
Provides explicit when to use: to list or retrieve a funnel. Includes limitations (404 if not found, enumeration first) and examples with parameter combinations. Could improve by directly contrasting with sibling tools like funnels.create, but enough guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pages.engagementARead-onlyInspect
Per-page metrics with a selectable detail level. The view parameter chooses what comes back:
view="summary" (default): pathname, pageviews, visitors. Cheap; use as the standard "top pages" call.
view="engagement": adds avg_engagement_seconds (active tab time from the SDK's pageview_end beacon) and bounce_rate (% of single-page sessions that started on this path). Use to answer "which pages hold attention" or "which pages bounce".
view="sections": returns per-section view counts for the specified pathname. Requires
pathnameto be set. Each section is a data-clamp-section element on that page, counted once per session when at least 40% scrolls into view. Use to answer "which parts of /pricing get seen" or "is the FAQ being read".
Examples:
"top pages this week" → view omitted (or "summary"), period="7d"
"which pages bounce hardest" → view="engagement", then sort by bounce_rate
"how far down /pricing do people scroll" → view="sections", pathname="/pricing"
Limitations: avg_engagement_seconds is null for pages without pageview_end data (SDK <0.3 or pages closed during navigation). view="sections" requires the section-views SDK extension installed (see /docs/sdk/extensions/section-views) and only counts elements with the data-clamp-section attribute — pages with no instrumented sections return []. view="sections" without pathname returns 400.
| Name | Required | Description | Default |
|---|---|---|---|
| view | No | Detail level. "summary" (default) returns pathname/pageviews/visitors only. "engagement" adds avg_engagement_seconds and bounce_rate. "sections" returns per-section view counts for the pathname (requires pathname). | |
| limit | No | Max rows to return (1-50). Defaults to 10. | |
| period | No | Time period. Use "today", "yesterday", "7d", "30d", "90d", or a custom range as "YYYY-MM-DD:YYYY-MM-DD" (e.g. "2026-01-01:2026-03-31"). Defaults to "30d". | |
| channel | No | Traffic channel. One of: "direct", "organic_search", "organic_social", "paid", "email", "referral". | |
| country | No | ISO 3166-1 alpha-2 country code, uppercase (e.g. "US", "GB", "DE", "NL", "JP"). Filter results to visitors from this country. | |
| pathname | No | Filter to a specific page path (e.g. "/pricing", "/blog/my-post"). Must start with /. | |
| utm_term | No | Filter by UTM term (e.g. "running+shoes"). Case-sensitive. | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. | |
| utm_medium | No | Filter by UTM medium (e.g. "cpc", "email", "social"). Case-sensitive. | |
| utm_source | No | Filter by UTM source (e.g. "google", "twitter", "newsletter"). Case-sensitive, must match the value in the tracking URL. | |
| device_type | No | Device category. One of: "desktop", "mobile", "tablet". | |
| utm_content | No | Filter by UTM content (e.g. "hero-cta", "sidebar-banner"). Case-sensitive. | |
| utm_campaign | No | Filter by UTM campaign name (e.g. "spring-launch", "product-hunt"). Case-sensitive. | |
| referrer_host | No | Filter by referrer hostname (e.g. "news.ycombinator.com", "twitter.com", "github.com"). Use this to see what traffic from a specific source did. Must match the value returned by `traffic.breakdown(dimension="referrer_host")` exactly (lowercase, no protocol or path). |
Output Schema
| Name | Required | Description |
|---|---|---|
| pages | No | |
| sections | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description aligns with readOnlyHint annotation (true) by confirming it returns metrics, not modifying data. Adds behavioral details: data source (SDK's pageview_end beacon) and null behavior for pages without engagement. No contradiction.
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?
Four sentences, front-loaded with key output fields and use cases. Every sentence adds value: what it returns, why to use it, data source caveat, and null handling. No fluff.
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 13 optional parameters and no output schema, the description covers what to expect (fields) and edge cases (null). Could clarify that results are aggregated per page and if limit applies to total pages. Still fairly complete for a read-only data 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?
Input schema has 100% description coverage, so baseline 3 applies. Description doesn't add significant parameter-level meaning beyond schema, but it implies pathname filtering in the use-case examples. Adequate.
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?
Clearly specifies it returns per-page engagement metrics like pageviews, unique visitors, avg engagement seconds, and bounce rate. Distinguishes from sibling tools like pages.top (likely top pages list) and traffic.* tools by focusing on engagement metrics.
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?
Provides explicit use cases: 'which pages hold attention', 'which pages bounce', 'are people actually reading the blog'. Notes that pages with no engagement data return null for avg_engagement_seconds. Could add guidance on when not to use (e.g., for real-time data use traffic.live), but context signals help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
projects.listARead-onlyInspect
List all Clamp projects this credential can access. Returns each project's id, name, and plan ('free', 'pro', or 'growth'). Use this when the user asks "which sites do you see" or when the agent needs a project_id to disambiguate before calling another tool — most other tools auto-resolve when the credential has access to exactly one project, so explicit calls are only needed for multi-project setups.
Examples:
"which sites are tracked" → projects.list
before drilling into a specific project's data when several exist
Limitations: returns an empty array if the credential is org-scoped but has no projects yet. The plan field is the current billing plan, not a permission level.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| projects | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint. Description adds return fields and notes that it lists all accessible projects, but no additional behavioral details beyond annotations.
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?
Three sentences covering purpose, output, usage context, and disambiguation; 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?
Complete for a no-parameter tool; describes output, use case, and relationship to other tools.
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 0 parameters, schema coverage is 100%; description doesn't need to add parameter info, baseline 4 applies.
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?
Clearly states 'List all projects this credential can access' with specific verb and resource, distinguishes from siblings by mentioning it returns project IDs for use in other tools.
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 says when to use: to discover project IDs, and when auto-resolve works, providing clear context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
revenue.sumARead-onlyInspect
Sum revenue from Money-typed event properties. Returns per-currency totals, optionally grouped by a traffic dimension (referrer_host, channel, country, device_type, pathname, utm_source/medium/campaign). Different currencies are never mixed in a single sum — each row is one (group, currency) pair. Money properties are tracked via clamp.track("purchase", { total: { amount: 29, currency: "USD" } }) — see /docs/concepts/revenue for the full Money type.
Attribution: attribution_model="last_touch" (default) groups revenue by the dimensions of the session where the revenue event fired — answers "what surface was active at conversion?". attribution_model="first_touch" joins each revenue event with the visitor's earliest-known session and groups by that session's acquisition dimension — answers "where did my paying customers actually come from?". For multi-visit funnels (typical B2B SaaS), first-touch is usually the more honest read on which channels actually drive revenue.
Examples:
"total revenue this month" → no group_by, period="30d"
"revenue by channel" → group_by="channel", period="30d"
"where did paying customers actually come from" → group_by="channel", attribution_model="first_touch"
"first-touch revenue per UTM campaign" → group_by="utm_campaign", attribution_model="first_touch"
"how much did Stripe purchases bring in from organic search" → event="purchase", channel="organic_search"
"top revenue countries" → group_by="country"
Limitations: events without any Money property contribute zero. If property is set, only that one Money key is summed; omitted, every Money property on matched events is included. Stripe-typed revenue (recommended) flows through server-side webhooks; client-only revenue is subject to ad-blocker loss. attribution_model="first_touch" only supports acquisition-dimension group_by (channel, referrer_host, utm_*); first-touch country / device / pathname are rejected because they're rarely what people actually mean by them. First-touch breakdowns are extremely sensitive to small samples — at single-digit paying-customer counts the per-channel rate is dominated by 1-2 users' acquisition history; check visitors before reading the rate, or pair with users.journey to validate against specific customers.
| Name | Required | Description | Default |
|---|---|---|---|
| event | No | Filter to a specific event name (e.g. "purchase", "checkout_completed"). Omit to sum Money properties across all events. | |
| limit | No | Max rows to return (1-50). Defaults to 10. | |
| period | No | Time period. Use "today", "yesterday", "7d", "30d", "90d", or a custom range as "YYYY-MM-DD:YYYY-MM-DD" (e.g. "2026-01-01:2026-03-31"). Defaults to "30d". | |
| channel | No | Traffic channel. One of: "direct", "organic_search", "organic_social", "paid", "email", "referral". | |
| country | No | ISO 3166-1 alpha-2 country code, uppercase (e.g. "US", "GB", "DE", "NL", "JP"). Filter results to visitors from this country. | |
| group_by | No | Group revenue by a traffic dimension. Returns one row per (dimension, currency) pair. Omit for a single total per currency. | |
| pathname | No | Filter to a specific page path (e.g. "/pricing", "/blog/my-post"). Must start with /. | |
| property | No | Restrict the sum to a single Money property key on the event (e.g. "total", "mrr", "ltv"). Omit to sum every Money-typed property on matched events. | |
| utm_term | No | Filter by UTM term (e.g. "running+shoes"). Case-sensitive. | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. | |
| utm_medium | No | Filter by UTM medium (e.g. "cpc", "email", "social"). Case-sensitive. | |
| utm_source | No | Filter by UTM source (e.g. "google", "twitter", "newsletter"). Case-sensitive, must match the value in the tracking URL. | |
| device_type | No | Device category. One of: "desktop", "mobile", "tablet". | |
| utm_content | No | Filter by UTM content (e.g. "hero-cta", "sidebar-banner"). Case-sensitive. | |
| utm_campaign | No | Filter by UTM campaign name (e.g. "spring-launch", "product-hunt"). Case-sensitive. | |
| referrer_host | No | Filter by referrer hostname (e.g. "news.ycombinator.com", "twitter.com", "github.com"). Use this to see what traffic from a specific source did. Must match the value returned by `traffic.breakdown(dimension="referrer_host")` exactly (lowercase, no protocol or path). | |
| attribution_model | No | Attribution model. "last_touch" (default) groups by the dimensions of the session where revenue fired. "first_touch" joins each revenue event with the visitor's earliest session and groups by that session's acquisition dim. First-touch only supports group_by in acquisition dimensions (channel, referrer_host, utm_*). |
Output Schema
| Name | Required | Description |
|---|---|---|
| rows | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. The description adds behavioral details such as different currencies never being mixed, per-currency totals, and the tracking method (clamp.track), which provides value beyond 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 four concise sentences, front-loaded with the main purpose, and every sentence adds value. No unnecessary wording.
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 has many optional parameters and no output schema. The description covers core functionality, currency behavior, and examples. It lacks return format details but is still fairly complete for the 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% with all 16 parameters described. The description mentions grouping by traffic dimensions but adds no new information beyond the schema. Baseline score of 3 is appropriate.
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 sums Money-typed event properties and returns per-currency totals with optional grouping. It provides specific example questions and distinguishes itself from sibling tools by being the only revenue summation 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 gives explicit use cases like 'which source generated the most revenue' and explains currency handling. Although it does not explicitly state when not to use it, the context is clear and no alternatives are needed among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
sessions.pathsARead-onlyInspect
Aggregate (entry_page → exit_page) session pairs. Returns the top pairs with how many sessions followed each path, average pages per session, average duration in seconds, and a bounce flag. Use to answer "what do visitors do after landing on /pricing", "where do sessions end", or "which entry pages lead to the deepest engagement". Aggregate-only — no per-user traces, no full pageview chains, no individual session reconstruction.
Examples:
"top entry → exit pairs last week" → period="7d"
"longest sessions starting from the blog" → pathname="/blog", min_pages=3
"where do paid-traffic visitors end up" → channel="paid"
Limitations: shows entry and exit only, not the full pageview chain in between (use events.list for granular event analysis). min_pages=1 (default) includes single-page sessions which always show as bounces; set min_pages=2 to exclude them. Sessions ending without a pageview_end beacon (e.g. browser crash) may have null durations.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max rows to return (1-50). Defaults to 10. | |
| period | No | Time period. Use "today", "yesterday", "7d", "30d", "90d", or a custom range as "YYYY-MM-DD:YYYY-MM-DD" (e.g. "2026-01-01:2026-03-31"). Defaults to "30d". | |
| channel | No | Traffic channel. One of: "direct", "organic_search", "organic_social", "paid", "email", "referral". | |
| country | No | ISO 3166-1 alpha-2 country code, uppercase (e.g. "US", "GB", "DE", "NL", "JP"). Filter results to visitors from this country. | |
| pathname | No | Filter to a specific page path (e.g. "/pricing", "/blog/my-post"). Must start with /. | |
| utm_term | No | Filter by UTM term (e.g. "running+shoes"). Case-sensitive. | |
| min_pages | No | Minimum pageviews in a session to include it. Defaults to 1 (include bounces). Set to 2 to exclude single-page sessions. | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. | |
| utm_medium | No | Filter by UTM medium (e.g. "cpc", "email", "social"). Case-sensitive. | |
| utm_source | No | Filter by UTM source (e.g. "google", "twitter", "newsletter"). Case-sensitive, must match the value in the tracking URL. | |
| device_type | No | Device category. One of: "desktop", "mobile", "tablet". | |
| utm_content | No | Filter by UTM content (e.g. "hero-cta", "sidebar-banner"). Case-sensitive. | |
| utm_campaign | No | Filter by UTM campaign name (e.g. "spring-launch", "product-hunt"). Case-sensitive. | |
| referrer_host | No | Filter by referrer hostname (e.g. "news.ycombinator.com", "twitter.com", "github.com"). Use this to see what traffic from a specific source did. Must match the value returned by `traffic.breakdown(dimension="referrer_host")` exactly (lowercase, no protocol or path). |
Output Schema
| Name | Required | Description |
|---|---|---|
| paths | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is clear. The description adds context about aggregate-only behavior and no per-user traces, which sets expectations. No contradictions.
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?
Extremely concise: two sentences. First sentence states purpose and output, second gives usage examples and limitation. Every word earns its place, no fluff.
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?
Despite lack of output schema, the description details the return structure (fields) and usage context. It covers limitations and gives examples. Minor gap: could mention that results are top pairs, but the word 'top' is there.
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 baseline is 3. The description does not repeat parameter info, which is appropriate. It adds no additional semantic context beyond what the schema already 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 aggregates session paths and returns specific metrics (entry-exit pairs, counts, avg pages, duration, bounce flag). It provides example questions it answers, and distinguishes from siblings with 'Aggregate-only; no per-user traces'.
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 when to use (e.g., 'what do visitors actually do after landing on X') and implies when not to use (no per-user traces). Could be improved by naming alternative tools for per-user traces, but good overall.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
traffic.breakdownARead-onlyInspect
Aggregate visitors and pageviews grouped by a single dimension. The dimension parameter chooses what to group by — page paths, traffic sources, geography, devices, or marketing attribution. Results are sorted by visitors descending and capped by limit (default 10, max 50). Some dimensions return additional joined columns: dimension="referrer_host" includes the channel for each referrer; dimension="city" includes the ISO country code. All other dimensions return only {name, pageviews, visitors}. Filters narrow the set before aggregation.
Examples:
"top pages last week" → dimension="pathname", period="7d"
"who is sending traffic" → dimension="referrer_host"
"mobile vs desktop split" → dimension="device_type"
"best UTM campaigns" → dimension="utm_campaign"
"top cities in Germany" → dimension="city", country="DE"
"browser version distribution" → dimension="browser_version"
Limitations: aggregates pageview events only — for custom event breakdowns use events.list with group_by. The name column is the raw stored value (lowercase ISO codes for country, exact pathname strings including trailing slash). Per-page time-on-page or bounce rate is not included here — use pages.engagement for that.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max rows to return (1-50). Defaults to 10. | |
| period | No | Time period. Use "today", "yesterday", "7d", "30d", "90d", or a custom range as "YYYY-MM-DD:YYYY-MM-DD" (e.g. "2026-01-01:2026-03-31"). Defaults to "30d". | |
| channel | No | Traffic channel. One of: "direct", "organic_search", "organic_social", "paid", "email", "referral". | |
| country | No | ISO 3166-1 alpha-2 country code, uppercase (e.g. "US", "GB", "DE", "NL", "JP"). Filter results to visitors from this country. | |
| pathname | No | Filter to a specific page path (e.g. "/pricing", "/blog/my-post"). Must start with /. | |
| utm_term | No | Filter by UTM term (e.g. "running+shoes"). Case-sensitive. | |
| dimension | Yes | What to group by. Page paths: "pathname", "entry_page", "exit_page". Traffic sources: "referrer_host" (returns channel too), "channel", "utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term". Geography: "country", "region", "city" (returns country too). Devices: "device_type", "browser", "browser_version", "os", "os_version". | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. | |
| utm_medium | No | Filter by UTM medium (e.g. "cpc", "email", "social"). Case-sensitive. | |
| utm_source | No | Filter by UTM source (e.g. "google", "twitter", "newsletter"). Case-sensitive, must match the value in the tracking URL. | |
| device_type | No | Device category. One of: "desktop", "mobile", "tablet". | |
| utm_content | No | Filter by UTM content (e.g. "hero-cta", "sidebar-banner"). Case-sensitive. | |
| utm_campaign | No | Filter by UTM campaign name (e.g. "spring-launch", "product-hunt"). Case-sensitive. | |
| referrer_host | No | Filter by referrer hostname (e.g. "news.ycombinator.com", "twitter.com", "github.com"). Use this to see what traffic from a specific source did. Must match the value returned by `traffic.breakdown(dimension="referrer_host")` exactly (lowercase, no protocol or path). |
Output Schema
| Name | Required | Description |
|---|---|---|
| rows | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds minimal behavioral context beyond stating it provides pageviews and unique visitors. No contradiction, but no additional traits disclosed.
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 efficient sentences, front-loaded with purpose followed by usage guidance. 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?
With full schema coverage and read-only annotation, the description provides sufficient context for an agent to select and use the tool appropriately. Could mention output structure but not required given simplicity.
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 3. Description adds context by listing dimensions appropriate for this tool, but does not elaborate on parameter syntax beyond what the 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 states 'Generic single-dimension breakdown of pageviews and unique visitors', clearly identifying the tool's purpose and resource. It distinguishes from sibling tools by listing specialized alternatives.
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 recommends specialized tools ('pages.top', etc.) for certain dimensions and lists the remaining dimensions for this tool. Clear context on when to use, though no explicit 'when not to' statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
traffic.compareARead-onlyInspect
Compare one metric across two arbitrary periods side-by-side. Returns both period values plus absolute delta and percentage delta. Periods do not need to be the same length — the percentage delta normalizes by ratio so longer/shorter comparisons remain meaningful. Use when the user asks month-over-month, before-vs-after-launch, or "how does this week compare to last".
Examples:
"this month vs last month" → metric="visitors", a="2026-04-01:2026-04-25", b="2026-03-01:2026-03-31"
"is /pricing converting better since the redesign" → metric="pageviews", a="2026-04-16:2026-04-25", b="2026-04-01:2026-04-15", pathname="/pricing"
Limitations: one metric per call — for multi-metric comparison either call repeatedly or use traffic.overview (which always includes the previous period). Period strings must be a preset ("today", "yesterday", "7d", "30d", "90d") or a YYYY-MM-DD:YYYY-MM-DD range; relative phrases like "last quarter" are not parsed.
| Name | Required | Description | Default |
|---|---|---|---|
| a | Yes | First period. Use "today", "yesterday", "7d", "30d", "90d", or a custom range "YYYY-MM-DD:YYYY-MM-DD". | |
| b | Yes | Second period. Same format as `a`. | |
| metric | Yes | The metric to compare. | |
| channel | No | Traffic channel. One of: "direct", "organic_search", "organic_social", "paid", "email", "referral". | |
| country | No | ISO 3166-1 alpha-2 country code, uppercase (e.g. "US", "GB", "DE", "NL", "JP"). Filter results to visitors from this country. | |
| pathname | No | Filter to a specific page path (e.g. "/pricing", "/blog/my-post"). Must start with /. | |
| utm_term | No | Filter by UTM term (e.g. "running+shoes"). Case-sensitive. | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. | |
| utm_medium | No | Filter by UTM medium (e.g. "cpc", "email", "social"). Case-sensitive. | |
| utm_source | No | Filter by UTM source (e.g. "google", "twitter", "newsletter"). Case-sensitive, must match the value in the tracking URL. | |
| device_type | No | Device category. One of: "desktop", "mobile", "tablet". | |
| utm_content | No | Filter by UTM content (e.g. "hero-cta", "sidebar-banner"). Case-sensitive. | |
| utm_campaign | No | Filter by UTM campaign name (e.g. "spring-launch", "product-hunt"). Case-sensitive. | |
| referrer_host | No | Filter by referrer hostname (e.g. "news.ycombinator.com", "twitter.com", "github.com"). Use this to see what traffic from a specific source did. Must match the value returned by `traffic.breakdown(dimension="referrer_host")` exactly (lowercase, no protocol or path). |
Output Schema
| Name | Required | Description |
|---|---|---|
| a | Yes | |
| b | Yes | |
| metric | Yes | |
| pct_delta | Yes | |
| absolute_delta | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, and the description does not contradict this. It adds value by detailing the output format (values plus absolute and percentage delta), which is beyond the annotation alone.
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 explains core function and output, second gives usage examples. No wasted words, front-loaded with key 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 14 parameters (all documented in schema), no output schema, and read-only nature, the description covers the tool's purpose and when to use it. It does not list optional filters, but the schema handles that.
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% with detailed parameter descriptions (e.g., format hints for a, b, enum for metric). The tool description adds no additional parameter-level detail beyond the schema, so baseline 3 is appropriate.
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 compares a metric across two time periods, returns values and delta, and gives concrete examples (month-over-month, promo week vs baseline). This distinguishes it from siblings like traffic.breakdown and traffic.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 explicitly says 'Use when the user asks about month-over-month...' providing clear when-to-use guidance. It does not mention alternatives or when not to use, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
traffic.liveARead-onlyInspect
See who is on the site in the last N minutes. Returns the active visitor count plus top pages, top referrers, and top countries within that window. Defaults to 5 minutes; max 60. Use during incidents ("is anyone hitting the broken page right now"), launches ("is the new post getting traffic"), or whenever the user asks "who is on the site".
Examples:
"who is on the site right now" → window_minutes=5
"has anyone visited in the last hour" → window_minutes=60
"is the launch page getting hits" → window_minutes=15
Limitations: ingestion lag is ~30 seconds, so "live" is approximate. Visitor count is unique anonymous_ids in the window, not active sessions. For historical questions ("who visited last week"), use traffic.overview instead.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. | |
| window_minutes | No | Lookback window in minutes. Defaults to 5, max 60. |
Output Schema
| Name | Required | Description |
|---|---|---|
| visitors | Yes | |
| pageviews | Yes | |
| top_pages | Yes | |
| top_sources | Yes | |
| top_countries | Yes | |
| window_minutes | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows it is safe. The description adds behavioral context: it returns a summary (visitor count, top pages, referrers, countries) within a configurable time window, going beyond 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 a single, efficient sentence that front-loads the purpose and lists key outputs. No redundant or tangential 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?
For a simple tool with two optional parameters, the description covers the core functionality. However, it lacks details like result limits (e.g., number of top pages), ordering, and whether the data is cached, which could help the agent set expectations.
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% with good parameter descriptions. The description adds the default for window_minutes (5) but otherwise does not enhance the schema's information. Baseline score of 3 is appropriate.
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 uses a specific verb ('Who's on the site') and resource ('right now'), clearly indicating it provides live visitor data. It distinguishes itself from sibling tools like traffic.overview and traffic.timeseries by emphasizing real-time scope.
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 implies real-time use ('right now') but does not explicitly state when to use this tool versus alternatives (e.g., traffic.timeseries for historical trends). No guidance on when not to use or prerequisites is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
traffic.overviewARead-onlyInspect
High-level snapshot of website traffic over a period: total pageviews, unique visitors, sessions, bounce rate (%), and average session duration (seconds). Always includes a comparison block with the same metrics for the previous period of equal length plus the absolute and percentage delta. Use this as the first call when the user asks how the site is doing, before drilling into channels, pages, or funnels.
Examples:
"how is traffic this week" → period="7d"
"overview for last month" → period="30d"
"organic search performance this quarter" → period="90d", channel="organic_search"
Limitations: bounce_rate and avg_duration are derived from the SDK's pageview_end beacon — for SDK <0.3 they return null. Custom date ranges must be in YYYY-MM-DD:YYYY-MM-DD format. Maximum range is 365 days.
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | Time period. Use "today", "yesterday", "7d", "30d", "90d", or a custom range as "YYYY-MM-DD:YYYY-MM-DD" (e.g. "2026-01-01:2026-03-31"). Defaults to "30d". | |
| channel | No | Traffic channel. One of: "direct", "organic_search", "organic_social", "paid", "email", "referral". | |
| country | No | ISO 3166-1 alpha-2 country code, uppercase (e.g. "US", "GB", "DE", "NL", "JP"). Filter results to visitors from this country. | |
| pathname | No | Filter to a specific page path (e.g. "/pricing", "/blog/my-post"). Must start with /. | |
| utm_term | No | Filter by UTM term (e.g. "running+shoes"). Case-sensitive. | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. | |
| utm_medium | No | Filter by UTM medium (e.g. "cpc", "email", "social"). Case-sensitive. | |
| utm_source | No | Filter by UTM source (e.g. "google", "twitter", "newsletter"). Case-sensitive, must match the value in the tracking URL. | |
| device_type | No | Device category. One of: "desktop", "mobile", "tablet". | |
| utm_content | No | Filter by UTM content (e.g. "hero-cta", "sidebar-banner"). Case-sensitive. | |
| utm_campaign | No | Filter by UTM campaign name (e.g. "spring-launch", "product-hunt"). Case-sensitive. | |
| referrer_host | No | Filter by referrer hostname (e.g. "news.ycombinator.com", "twitter.com", "github.com"). Use this to see what traffic from a specific source did. Must match the value returned by `traffic.breakdown(dimension="referrer_host")` exactly (lowercase, no protocol or path). |
Output Schema
| Name | Required | Description |
|---|---|---|
| sessions | Yes | |
| visitors | Yes | |
| pageviews | Yes | |
| comparison | Yes | |
| bounce_rate | Yes | |
| avg_duration | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with readOnlyHint=true and adds behavioral context: it includes comparison with previous period, which is not disclosed by annotations or schema. No contradictions.
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, no wasted words. Front-loaded with the key metrics, then usage guidance. Highly concise and well-structured.
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?
Despite no output schema, the description fully explains the return values and the comparison feature. With 12 optional parameters fully described in schema, the description is complete for a high-level overview 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 description coverage is 100%, so baseline is 3. The description does not add additional parameter meaning beyond what the schema already provides, so score remains at 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 the tool provides a high-level overview of website analytics with specific metrics (pageviews, unique visitors, sessions, bounce rate, session duration) and comparison with previous period. It distinguishes itself from siblings by advising to use it first before drilling into specifics.
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 says 'Use this first to understand overall traffic before drilling into specifics,' providing clear context for when to use it and implying alternatives. However, no explicit when-not statements are included.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
traffic.timeseriesARead-onlyInspect
Event counts over time as date buckets. Returns [{ date, count }] sorted ascending. Granularity is automatic based on period length (hourly for ≤2 days, daily for ≤90 days, weekly for ≤365 days, monthly beyond) and can be overridden via granularity. Filterable to a specific event name (defaults to "pageview") and a single custom property key/value pair.
Examples:
"pageview trend last week" → period="7d"
"signups per day this month" → event="signup", period="30d", granularity="day"
"hourly pageviews yesterday" → period="1d", granularity="hour"
Limitations: forcing granularity="hour" over a 90-day period produces hundreds of buckets and may be truncated server-side. Buckets with no matching events return zero (the series does not skip missing dates).
| Name | Required | Description | Default |
|---|---|---|---|
| event | No | Event name to chart. Defaults to "pageview". Use any custom event name to see its trend over time. | |
| value | No | Filter to events where the property key equals this value. | |
| period | No | Time period. Use "today", "yesterday", "7d", "30d", "90d", or a custom range as "YYYY-MM-DD:YYYY-MM-DD" (e.g. "2026-01-01:2026-03-31"). Defaults to "30d". | |
| channel | No | Traffic channel. One of: "direct", "organic_search", "organic_social", "paid", "email", "referral". | |
| country | No | ISO 3166-1 alpha-2 country code, uppercase (e.g. "US", "GB", "DE", "NL", "JP"). Filter results to visitors from this country. | |
| pathname | No | Filter to a specific page path (e.g. "/pricing", "/blog/my-post"). Must start with /. | |
| property | No | Filter by this custom property key (used with value). | |
| utm_term | No | Filter by UTM term (e.g. "running+shoes"). Case-sensitive. | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. | |
| utm_medium | No | Filter by UTM medium (e.g. "cpc", "email", "social"). Case-sensitive. | |
| utm_source | No | Filter by UTM source (e.g. "google", "twitter", "newsletter"). Case-sensitive, must match the value in the tracking URL. | |
| device_type | No | Device category. One of: "desktop", "mobile", "tablet". | |
| granularity | No | Override the automatic granularity. "hour" for hourly buckets, "day" for daily, "week" for weekly, "month" for monthly. If omitted, chosen automatically based on the period length. | |
| utm_content | No | Filter by UTM content (e.g. "hero-cta", "sidebar-banner"). Case-sensitive. | |
| utm_campaign | No | Filter by UTM campaign name (e.g. "spring-launch", "product-hunt"). Case-sensitive. | |
| referrer_host | No | Filter by referrer hostname (e.g. "news.ycombinator.com", "twitter.com", "github.com"). Use this to see what traffic from a specific source did. Must match the value returned by `traffic.breakdown(dimension="referrer_host")` exactly (lowercase, no protocol or path). |
Output Schema
| Name | Required | Description |
|---|---|---|
| series | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the readOnlyHint annotation: automatic granularity logic based on period length, return format as an array of date-count objects, and optional granularity overrides. This fully informs an agent of the tool's behavior.
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?
Five sentences, each purposeful. The core action and return format are front-loaded, followed by essential details on granularity and optional features. No redundancy or fluff.
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 16 parameters (all described in schema) and no output schema, the description covers the return format and key behavior (granularity). It lacks explanation of all filter parameters but schema fills that gap. Agent can understand the tool's overall function and output.
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 summarizing automatic granularity rules, the default event ('pageview'), and the ability to override granularity and filter by event name, which enhances 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 retrieves event counts over time as date buckets, specifies granularity logic, return format, and use case for visualizing trends. It distinguishes itself from sibling tools like traffic.breakdown and traffic.compare 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?
It explicitly says 'Use to visualize trends and spot patterns,' which gives clear when-to-use guidance. It does not directly contrast with alternatives, but the context of sibling tools and the tool's nature make usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
users.journeyARead-onlyInspect
Chronological session history for a single visitor (anonymous_id). Each session collapses to one row showing the start and end timestamps, entry page, channel, referrer host, UTMs, country, device type, pageview count, and the distinct custom event names fired in that session. The first row is flagged with is_first_touch: true.
Use this when an aggregate query can't answer the question — multi-touch attribution analysis, support / debugging investigations ("what did this user do before signing up?"), or sanity-checking a specific account's journey before drawing conclusions about a cohort.
Examples:
"show me what this user did across all their visits" → anonymous_id="anon_xxx"
"where did this paying customer first come from?" → anonymous_id="anon_xxx", read sessions[0].channel
"did they convert on their first visit or come back later?" → check if signup-event sessions match is_first_touch=true
Limitations: requires the visitor's anonymous_id, which the SDK exposes via getAnonymousId() on the browser side. Aggregate questions ("which channels drive my best users") use revenue.sum with attribution_model="first_touch" — don't loop this tool over thousands of users. Defaults to a 365-day lookback so first-touch is meaningful; tighten with period if needed.
Pairs with: revenue.sum(attribution_model="first_touch") to validate the aggregate first-touch read against specific high-value customers' actual paths.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max sessions to return. Defaults to 50, max 200. | |
| period | No | Time period. Use "today", "yesterday", "7d", "30d", "90d", or a custom range as "YYYY-MM-DD:YYYY-MM-DD" (e.g. "2026-01-01:2026-03-31"). Defaults to "30d". | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. | |
| anonymous_id | Yes | The visitor's anonymous_id. From the browser SDK's getAnonymousId() / localStorage clamp_aid; from server-side tracks, whatever you passed as anonymousId. |
Output Schema
| Name | Required | Description |
|---|---|---|
| sessions | Yes | |
| anonymous_id | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds rich behavioral context: session aggregation, first-touch flag, 365-day default lookback (though schema says 30d), and the need for anonymous_id from the SDK. No contradictions with annotations.
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 well-structured with examples and limitations, but slightly longer than necessary. Key details are front-loaded, and every sentence 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 no output schema, the description adequately explains the return format (columns, is_first_touch flag). The 4-parameter tool is well-covered overall, though the period default inconsistency may cause confusion.
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 the description adds meaningful context for parameters like limit defaults and anonymous_id source. However, there is a minor inconsistency: description states '365-day lookback' while schema defaults period to '30d'. This reduces clarity slightly.
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 chronological session history for a single visitor, with specific columns and a first-touch flag. It distinctly separates this from aggregate tools like revenue.sum, making its purpose unambiguous.
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 provides when-to-use (multi-touch attribution, debugging) and when-not-to-use (aggregate questions, avoid looping over thousands). Names an alternative tool (revenue.sum with attribution_model) and gives concrete examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!