Skip to main content
Glama

Nova Amazon MCP Server

query_sqp

Read-only

Amazon SEARCH QUERY PERFORMANCE (Brand Analytics), curated — what shoppers TYPE on Amazon, the whole market's funnel on each query, and your slice of it. ORGANIC demand: this is not ads, and not query_search_terms (that one is what people typed before clicking YOUR ad; this is every seller's behaviour on the query). Answers: which keywords grow or shrink my market, where I lose share, which high-volume queries I am absent from, whether competitors take my brand, do I convert better than the market, am I priced above it. Two vocabularies: market_* = all sellers on that query, your_* = this product. ⏱ FIXED CALENDAR PERIODS: grain is REQUIRED ('week' | 'month'); omit from/to and you get the LATEST COMPLETE period, which is what you almost always want. The response echoes the period actually served: period.from/to are period STARTS (the mart key — read alone they look like one day), and period.covers is the SAME period in calendar DAYS (an SQP week is SUNDAY→Saturday, not an ISO Monday week; a month 1st→last). Weekly runs ~10 days behind, monthly ~7 WEEKS behind, so when crossing with query_metrics / query_advertising / query_search_terms you MUST pass EXACTLY period.covers.from and period.covers.to as their from/to — never 'this month', never period.from/to, and never a weekly series from those tools (their weeks start on Monday and will not line up with SQP weeks). 🔒 HISTORY DEPTH: on a trial plan the response carries dataFloor, an ISO day — NOTHING before it was served, whatever the seller's real history holds, so absence below that day means 'withheld by the plan', never 'no demand'. The field is ABSENT when nothing was withheld. Say so instead of concluding a keyword is new or a market collapsed. 📊 COMPARISON IS A METRIC, not a mode: use search_volume_yoy_pct (month) or search_volume_wow_pct (week) — they are like-for-like, computed only over keywords present in BOTH periods; comparing period totals reads +34% where the truth is -3%. Read comparable_keywords / comparable_share to see how solid it is; the metric is null below the reliability floor. ⚠️ DO NOT SUM market_* VALUES ACROSS ROWS YOURSELF: a query's volume is repeated on every parent ASIN that ranks on it, so adding rows double counts (measured x2.4). The summary block is already de-duplicated — use it. ⚠️ FILTER queryTypes OR YOUR ANSWER IS NOISE: too_broad and long_tail are category demand and dominate any total, so 'my biggest gap' unfiltered returns head terms like 'makeup'. Use ['core','presence','suggested','competitor'] for actionable work, ['core'] for your tight market, ['own_brand'] for brand defence. 🔗 CROSSING WITH PPC: group by keyword and each row carries variants, the spellings that query merges — filter query_advertising/query_search_terms with ALL of them, because 35% of served queries have several spellings and they carry 60% of the volume, so matching one string silently misses real campaigns. The reverse works too: pass your PPC targets into keywords here and they resolve through the same clustering. Metric keys are their OWN universe — not list_metrics keys, not ads keys. 💱 CURRENCY: monetary values are ALWAYS served in the organization's primary currency — the secondary currencies are not supported on this route; currency in the response is the code and currencyNotice, when present, MUST be relayed to the user.

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": {
      "metrics": "<metrics>",
      "grain": "<grain>"
    },
    "name": "query_sqp"
  }
}

Input Schema

NameRequiredDescriptionDefault
qNoFree-text search over the query wording.
toNoWindow on period STARTS: every complete week/month whose start date is <= to is served (a week starting on `to` is fully included). Omit BOTH from/to to get the latest complete period.
fromNoWindow on period STARTS: every complete week/month whose start date is >= from is served. Omit BOTH from/to to get the latest complete period.
skusNoSKUs — resolved up to their families.
tagsNo"Your Filters" tag IDS from list_tags — a tag NAME is rejected.
grainYesREQUIRED. 'month' for year-over-year, month-over-month and trend work; 'week' for anything recent (10-day lag vs ~7 weeks).
limitNoRows per call of an entity grouping, 1 to 1000 (default 50). groupBy 'period' is never cut: the series comes whole, in date order.
reasonNoOne sentence, ALWAYS IN ENGLISH (regardless of the conversation language), on WHY you are making this call — the user question or your analytical goal. Recorded so the seller can see how their data is used.
sortByNoSQP metric key to rank rows by (e.g. "search_volume"). Refused with groupBy 'period': the series comes in date order.
groupByNo'keyword' is the main drill-down (and the only grain that returns `variants`); 'parentAsin', 'queryType', 'marketplace', or 'period' for a time series — one row per published week/month of the requested grain, keyed {type:'period', granularity, from, to} (from/to are the SQP period bounds, NOT your from/to). Omit for one total row.
metricsYesSQP metric keys (search_volume, your_impression_share, market_purchases, search_volume_yoy_pct, …) — NOT product or ads keys. Like-for-like variances carry their horizon in the name: _yoy_ and _mom_ at grain month, _wow_ at grain week.
accountsNoRestrict to a subset of your own seller account IDs (from list_accounts). Omit to include all your accounts. A brand/account name is accepted and resolved to its id when it matches one of your accounts unambiguously; a label that carries the id ("Brand (A1B2C3D4E5F6G)") resolves to that id.
keywordsNoExact customer queries — matched through the clustering, so any spelling of the query works (pass your PPC targets here directly).
sortOrderNodesc (default) = biggest first.
childAsinsNoChild ASINs — resolved UP to their families (a child has no market of its own).
queryTypesNoHow the query relates to the product. READ THE TOOL DESCRIPTION: leaving this open returns category head terms. The cockpit's SQP columns use ['core','presence','suggested','ads_only','low_ctr'] — pass exactly that to match what the seller sees in Nova.
parentAsinsNoFamily keys — the grain SQP is reported at.
marketplacesNoMarketplace IDs.
metricFiltersNoServer-side thresholds (ANDed) — e.g. your_impression_share < 5 AND search_volume > 1000 for the gaps that matter. Needs an entity grouping.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the read-only, non-destructive annotations, it discloses Sunday-to-Saturday weeks, publication lag, plan-based history withholding through dataFloor, comparison reliability floors, duplicated row values and de-duplicated summaries, spelling clustering, and fixed-currency behavior. These details materially affect invocation, cross-tool joins, and interpretation, and none conflicts with the annotations.

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

Conciseness2/5

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

The purpose is front-loaded and emoji labels provide some sectioning, but the result is an exceptionally long, dense single paragraph with pervasive capitalization. It repeats schema-covered defaults and requirements and uses extended statistics and repeated warnings where shorter wording and real section breaks would be much easier to scan.

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 19-parameter analytics tool without an output schema, it covers source scope, period selection and response-period fields, lag, withheld history, comparisons, aggregation, filtering, PPC joins, and currency. Together with the fully described schema, it provides unusually complete guidance for both correct invocation and correct interpretation.

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

Parameters5/5

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

Although schema description coverage is 100%, the description adds substantial operational meaning for metrics, grain, dates, queryTypes, and keywords. Examples include the market_* versus your_* vocabulary, exactly which period.covers dates to pass to siblings, recommended queryTypes combinations by analytical goal, and the need to use every variant when matching PPC data.

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?

It identifies the curated Amazon Search Query Performance/Brand Analytics resource, explains its organic query, market-funnel, and product-share scope, and lists concrete questions it answers. It explicitly distinguishes the tool from advertising data and query_search_terms, making selection among siblings straightforward.

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?

It gives explicit usage contexts and decision rules: omit dates for the latest complete period, choose comparison metrics by grain, use particular queryTypes sets for actionable analysis or brand defence, and use the summary rather than summing rows. It also supplies precise when-not and cross-tool guidance for query_metrics, query_advertising, and query_search_terms.

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.