Ask AI

query_metric_snapshots

Query recorded metric snapshots as a time series. Use to answer 'show me all CVR snapshots for UK over the last 6 months', 'how has ROAS evolved by month?', etc. Returns canonical snapshot data (matches the dashboard and monthly digest exactly) plus a charts array of ready-to-render line chart specs (one per metric; multi-series when the query spans multiple stores or segments). DEFAULT TO RENDERING THE CHART when the LLM is asked to show a metric over time — these are the SAME numbers the merchant sees on /dashboard/metrics. Call with no args (or just list: true) to get the full registry of canonical metric keys.

Input Schema

TableJSON Schema

Name	Required	Description
`list`	No	If true, returns the metric registry (canonical keys, units, descriptions). Use this when you don't know which metrics are available.
`limit`	No	Max snapshots to return (default 100, max 500)
`store`	No	Filter to a specific store/region key. Accepts short form ('acme-store') or full domain ('acme-store.myshopify.com') — both normalize to the short form used in storage.
`metric`	No	Canonical metric key. Omit to return snapshots across all metrics (filtered by other params).
`source`	No	Filter by source ('shopify', 'ga4', 'tw', etc.)
`_offset`	No	Pagination offset. If a response includes _pagination.hasMore=true, use _offset to fetch the next page.
`endDate`	No	Only include snapshots whose periodStart is <= this date (YYYY-MM-DD)
`segment`	No	Filter to a specific segment
`insightId`	No	Only snapshots linked to this insight
`startDate`	No	Only include snapshots whose periodEnd is >= this date (YYYY-MM-DD)
`confidence`	No	Filter by confidence. Pass 'high' / 'medium' / 'low' to match exactly, or 'minHigh' / 'minMedium' to require AT LEAST that level (treats null as 'high'). Useful for benchmarks where you only want trustworthy values.
`periodKind`	No	Filter by period anchoring. 'calendar' = discrete buckets only; 'rolling' = trailing windows only. Mixing the two in a single time series silently distorts trends.
`periodLength`	No	Filter by bucket size — combine with periodKind to e.g. fetch only calendar-month rows.

Schema Changelog

Changes observed during successful MCP inspections.

AddedSep 13, 2026
RemovedAug 30, 2026
AddedAug 23, 2026

TDQS

A4.4/5.0

Behavior4/5

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that the numbers match the dashboard and monthly digest exactly, that the output contains a charts array with multi-series semantics, and the list-mode special behavior. It does not mention rate limits, auth requirements, or pagination beyond the schema's own _offset description.

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 return-value and default-action guidance. All sentences earn their place; the 'SAME numbers the merchant sees' emphasis is somewhat redundant with the earlier 'matches the dashboard and monthly digest exactly' claim.

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 13-param tool with no annotations and no output schema, the description covers purpose, usage triggers, default charting behavior, list mode, and return shape (snapshots + charts array). The schema covers the remaining parameter details, leaving nothing an agent needs missing.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all 13 parameters including the subtle periodKind/periodLength interaction and confidence modes. The description adds only the list/no-args mode and doesn't expand any parameter semantics beyond what the schema covers. Baseline 3 applies.

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 (Query) and resource (metric snapshots as a time series), and distinguishes itself from siblings like get_daily_metrics, get_weekly_trends and get_metrics_comparison by scoping to canonical snapshot data plus ready-to-render charts.

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 explicit trigger examples ('show me all CVR snapshots for UK over the last 6 months', 'how has ROAS evolved by month?') and an explicit default action ('DEFAULT TO RENDERING THE CHART'). It also states when to call with no args / list:true for the registry.

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

All Ask AI tools Inspect

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

Need Help?