Skip to main content
Glama
Sign In

Fathom Analytics MCP by usefulapi

by io.usefulapi
OverviewDiscussionsAdmin

Run a traffic or event report

fathom_get_aggregation
Read-only

Fathom's custom report (the dashboard's numbers): aggregate pageviews or one event over a date range, optionally grouped by date and/or fields and filtered. Pageviews: aggregates visits (unique site visits), uniques (unique page visits), pageviews, avg_duration (seconds), bounce_rate. Events (entity event + event_name): conversions, unique_conversions, value (in cents). Examples: top pages = field_grouping [pathname], sort_by pageviews:desc; traffic sources = [referrer_source] or [referrer_hostname]; AI referrals = [ai_source]; daily trend = date_grouping day. All numbers come back as strings. Dates are in the site's timezone; hour grouping only for ranges up to 7 days. Grouped reports return at most 500 rows unless limit is set (max 1000, no paging), so narrow with filters or dates. Data before March 2021 cannot be grouped/filtered. GET /aggregations.

Input Schema

NameRequiredDescriptionDefault
limitNoRow cap, 1-1000 (default 500 when grouping by fields).
entityYespageview = site traffic; event = one event's conversions (needs event_name).
date_toNoEnd, YYYY-MM-DD (end of day) or "YYYY-MM-DD HH:MM:SS", in the site's timezone. Default: now.
filtersNoFilters, all applied (AND). Example: [{"property":"country_code","operator":"is","value":"GB"}].
site_idYesThe site id, the same string as in the tracking code (e.g. CDBUGS). fathom_list_sites lists them.
sort_byNo"<field>:asc|desc" with a field from aggregates or field_grouping (or timestamp with date_grouping), e.g. pageviews:desc.
date_fromNoStart, YYYY-MM-DD (start of day) or "YYYY-MM-DD HH:MM:SS", in the site's timezone. Default: the first recorded data.
aggregatesYesMetrics. pageview: visits, uniques, pageviews, avg_duration, bounce_rate. event: conversions, unique_conversions, value.
event_nameNoFor entity event: the event's name, as listed by fathom_list_events.
date_groupingNoGroup by time (omit for one total). hour only for ranges up to 7 days.
field_groupingNoGroup by these fields, e.g. [pathname] or [referrer_source, utm_campaign].

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only declare readOnlyHint/openWorldHint, but the description discloses unusual behaviors well beyond that: numbers returned as strings, site-timezone dates, hour grouping limited to ≤7-day ranges, a 500-row default with 1000 max and no paging, and the pre-March-2021 grouping/filtering restriction. These are exactly the traps an agent needs to know.

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

Conciseness4/5

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

Front-loaded with the core action and entity distinction, then layers constraints and examples. It is a dense run-on paragraph with a couple of fragment-style examples ('AI referrals = [ai_source]'), but no sentence is filler.

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

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries return-value burden itself and does: it states string-typed numbers, row caps, no paging, and date-coverage limits. For an 11-parameter reporting tool this is complete enough to call correctly.

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

Parameters4/5

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

Schema coverage is already 100%, but the description adds mapping value: it enumerates which aggregates belong to pageview vs event, and gives worked examples tying parameters together (top pages = field_grouping [pathname] + sort_by pageviews:desc). It stops short of explaining each parameter's semantics individually, so it edges above the baseline without being exhaustive.

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

Purpose5/5

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

States a specific verb and resource ('aggregate pageviews or one event over a date range') and immediately distinguishes the two entity modes. The agent can tell this is the custom reporting tool versus siblings like fathom_get_current_visitors or fathom_list_events without opening the schema.

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

Usage Guidelines4/5

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

Provides concrete use-case examples (top pages, traffic sources, AI referrals, daily trend) that clearly signal when to reach for this tool, and names constraints that steer usage (narrow with filters/dates, no paging). It never explicitly names an alternative sibling (e.g., current-visitors for real-time), so it stops short of full when-not guidance.

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

All Fathom Analytics MCP by usefulapi toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources