Skip to main content
Glama

query

Read-only

Run a flexible ad-hoc analytics query with custom metrics, filters, grouping, date ranges, and privacy-first customer email lookup. This is the most powerful endpoint — use it when other tools don't answer the question.

Examples of questions this tool answers:

  • "How many signups from Germany this week?" → filters: [{field:"event",op:"eq",value:"signup"},{field:"country",op:"eq",value:"DE"}]

  • "Which events contain 'page' in the name?" → filters: [{field:"event",op:"contains",value:"page"}], group_by: ["event"]

  • "Daily unique users for the last 30 days" → metrics: ["unique_users"], group_by: ["date"], date_from: "30d"

  • "Events per country" → group_by: ["country"]

  • "Signups by path and day" → metrics: ["event_count"], filters: [{field:"event",op:"eq",value:"signup"}], group_by: ["date", "properties.path"]

  • "p75 of LCP" → use the web_vitals tool (p75 is the headline). For an ad-hoc percentile on hosted, metrics: ["p75"], property: "cwv_lcp", filters: [{field:"event",op:"eq",value:"page_view"}]

  • "Revenue collected" → metrics: ["sum"], property: "revenue"

Filter operators: eq, neq, gt, lt, gte, lte, contains Filterable fields: event, user_id, date, country, session_id, timestamp, and any properties.* field (e.g. properties.path) For customer-specific reads, use the top-level email input instead of hashing locally. Raw email is sent only in the authenticated HTTPS POST body; the server matches via a project-scoped HMAC index and does not store raw email in event rows or profile traits. Built-in fields are a closed list. Event properties such as referrer, utm_source, path, browser, and hostname must be queried as properties.referrer, properties.utm_source, properties.path, properties.browser, and properties.hostname. Invalid filter fields fail loudly and return /properties-style guidance instead of being silently ignored. Group by: event, date, user_id, session_id, country, and at most one properties.. The key matches ^[A-Za-z0-9_]{1,128}$, the same rule as property filters. Result rows use the column name properties.. A null or missing property value is grouped as null. Two properties.* entries return 400 INVALID_GROUP_BY. Metrics: event_count, unique_users, session_count, bounce_rate, avg_duration, sum, avg, p50, p75, p95 Numeric property metrics sum, avg, p50, p75, and p95 are Pro, with the same gating as this query. A free account gets 403 PRO_REQUIRED and that rejection is not metered. property is the event property key and is required when any of those metrics is requested. On hosted, cwv_lcp, cwv_inp, cwv_cls, cwv_fcp, and cwv_ttfb are properties on page_view when the tracker snippet includes data-track-vitals="true". Use the web_vitals tool for the p75 headline, ratings, and good/needs-improvement/poor shares. For an ad-hoc query, filter event to page_view. property must match ^[A-Za-z0-9_]+$ and be at most 128 characters. Missing property is 400 MISSING_FIELDS. An invalid key is 400 INVALID_PROPERTY_KEY. Only JSON numbers are aggregated. Numeric strings, booleans, nulls, and missing keys are skipped. Each row includes the requested metrics plus n (numeric values used) and skipped whenever an aggregation metric is requested. Percentiles are nearest-rank: percentile_method is nearest_rank when a percentile is requested and null for sum or avg only. avg is rounded to 6 decimal places. order_by may be a requested aggregate, for example p75. Count modes: raw, session_then_user. The default for event_count is session_then_user for activation-safe counting: session-backed rows count by session, no-session rows fall back to user only when that user has no session-backed row in the same group, and fully anonymous rows fall back to event id. count_mode is ignored when event_count is not requested.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "project": "<project>"
    },
    "name": "query"
  }
}

Input Schema

NameRequiredDescriptionDefault
emailNoFilter by server-side scoped HMAC email lookup. Raw email is sent only in the authenticated HTTPS POST body and is not stored in event rows or profile traits.
limitNoMax results (default 100, max 1000)
orderNoSort directiondesc
date_toNoEnd date (ISO 8601). Defaults to today.
filtersNoFilters to apply
metricsNoMetrics to compute. sum, avg, p50, p75, and p95 require property
projectYesProject name
group_byNoFields to group by. Each item is event, date, user_id, session_id, country, or properties.<key>. The key matches ^[A-Za-z0-9_]{1,128}$. At most one properties.<key>. The result column is properties.<key>, and null or missing values group as null.
order_byNoField to sort by. Aggregate metrics such as p75 are allowed when requested
propertyNoEvent property key to aggregate, for example cwv_lcp or revenue. Required when metrics include sum, avg, p50, p75, or p95. Must match ^[A-Za-z0-9_]+$ and be at most 128 characters
date_fromNoStart date (ISO 8601 or Nd shorthand like '30d'). Defaults to 7 days ago.
count_modeNoHow event_count is aggregated. Default for event_count: session_then_user. Session-backed rows count by session, no-session rows fall back to user only when that user has no session-backed row in the same group, and fully anonymous rows fall back to event id. Ignored for queries without event_count. Use raw for ingestion/debugging counts.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / group_by / description
      Previous value: -"Fields to group results by"New value: +"Fields to group by. Each item is event, date, user_id, session_id, country, or properties.<key>. The key matches ^[A-Za-z0-9_]{1,128}$. At most one properties.<key>. The result column is properties.<key>, and null or missing values group as null."
    • removedInput schema / properties / group_by / items / enum
      Removed value: -[
      -  "event",
      -  "date",
      -  "user_id",
      -  "session_id",
      -  "country"
      -]
    • addedInput schema / properties / group_by / items / pattern
      Added value: +"^(event|date|user_id|session_id|country|properties\\.[A-Za-z0-9_]{1,128})$"
  2. Changed5 schema fields changed
    • changedInput schema / properties / metrics / description
      Previous value: -"Metrics to compute"New value: +"Metrics to compute. sum, avg, p50, p75, and p95 require property"
    • changedInput schema / properties / metrics / items / enum
      Previous value: -[
      -  "event_count",
      -  "unique_users",
      -  "session_count",
      -  "bounce_rate",
      -  "avg_duration"
      -]New value: +[
      +  "event_count",
      +  "unique_users",
      +  "session_count",
      +  "bounce_rate",
      +  "avg_duration",
      +  "sum",
      +  "avg",
      +  "p50",
      +  "p75",
      +  "p95"
      +]
    • changedInput schema / properties / order_by / description
      Previous value: -"Field to sort by"New value: +"Field to sort by. Aggregate metrics such as p75 are allowed when requested"
    • changedInput schema / properties / order_by / enum
      Previous value: -[
      -  "event_count",
      -  "unique_users",
      -  "session_count",
      -  "date",
      -  "event"
      -]New value: +[
      +  "event_count",
      +  "unique_users",
      +  "session_count",
      +  "date",
      +  "event",
      +  "sum",
      +  "avg",
      +  "p50",
      +  "p75",
      +  "p95"
      +]
    • addedInput schema / properties / property
      Added value: +{
      +  "description": "Event property key to aggregate, for example cwv_lcp or revenue. Required when metrics include sum, avg, p50, p75, or p95. Must match ^[A-Za-z0-9_]+$ and be at most 128 characters",
      +  "pattern": "^[A-Za-z0-9_]{1,128}$",
      +  "type": "string"
      +}
  3. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already establish readOnly/no-destructive/no-open-world, and the description layers on substantial behavior beyond them: failure modes (403 PRO_REQUIRED is not metered, 400 INVALID_GROUP_BY, 400 MISSING_FIELDS, 400 INVALID_PROPERTY_KEY, loud failures on bad filter fields), aggregation semantics (only JSON numbers aggregated, n and skipped columns, nearest-rank percentiles, avg rounded to 6dp), and privacy handling of raw email. No statement conflicts with the readOnly annotation.

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 purpose then examples, then reference blocks — a sensible ordering for a query-DSL tool. It is long and contains internal repetition (group_by and property pattern rules restated after already appearing in the schema, operator and metric enums copied verbatim), so some sentences do not earn their place.

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?

For a 12-parameter, 3-enum analytical tool with no output schema, the definition covers input semantics, error behavior, gating, and even result shape (metrics plus n and skipped, percentile_method, properties.<key> column naming). Nothing material an agent needs to construct a correct call is missing.

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

Parameters4/5

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

With 100% schema coverage the baseline is 3, but the description adds meaning the schema does not: built-in fields are a closed list so referrer/utm_source/path must be properties.*, at most one properties.<key> in group_by, property is required for sum/avg/p50/p75/p95, and count_mode is ignored without event_count. Some of this is duplication of schema text (operator list, metric list, group_by pattern), which keeps it off a 5.

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

Purpose5/5

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

Opens with a specific verb and resource — 'Run a flexible ad-hoc analytics query' — and enumerates the capability surface (custom metrics, filters, grouping, date ranges, email lookup). It positions itself against siblings explicitly ('the most powerful endpoint — use it when other tools don't answer the question') and names web_vitals as the alternative for p75 headlines.

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

Usage Guidelines5/5

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

Gives an explicit routing rule ('use it when other tools don't answer the question'), a concrete deflection to web_vitals for the p75 headline, and instruction to use the top-level email input instead of hashing locally. The worked question-to-parameter examples make the when-to-use decision concrete rather than abstract.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources