> ## Documentation Index
> Fetch the complete documentation index at: https://crushrewards.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Tools

> What you can ask Syntalic through Claude Code, Cursor, or any MCP client.

The MCP server (`@syntalic/mcp-server` **0.11.0**) exposes **37 tools**: 31 paid and 6 free. Below is what each does and what to ask in natural language — Claude (or your MCP client) handles parameter parsing, you don't have to think in arguments.

Start with the free **Discovery** tools. They cost nothing and tell you whether a paid query will land on good data before you spend on it.

## Discovery

**Free** — no payment required.

### `catalog_overview`

The shape of the catalog: unique products, listings, brands, categories, retailers, price observations, and when it was last updated.

> "What's in the Syntalic catalog?"
> "How many products and retailers do you actually cover?"

### `coverage_map`

Where the catalog is deep vs. thin, as priced product counts and a quality status per retailer × country × category. The one to check before spending.

> "Do you have good coverage of grocery in Canada?"
> "Which categories are thin on Best Buy?"

### `browse_categories`

The product category tree with per-node product counts. Pass a parent path to drill into a subtree.

> "What categories do you cover?"
> "Show me what's under Home & Kitchen."

### `list_retailers`

Retailers in the catalog with product counts, countries covered, and freshness.

> "Which retailers do you cover in Canada?"
> "How fresh is your Costco data?"

### `list_brands`

Brands in the catalog with product counts. An optional query prefix-matches the name, so "sam" finds Samsung.

> "Do you have Anker products?"
> "List the vacuum brands you track."

## Shopper

Per-query price: **\$0.01**

### `best_price`

Find the cheapest current price for a product across covered retailers.

> "What's the cheapest place to buy AirPods Pro right now?"
> "Find me the best price for a Dyson V15 in Canada."

### `price_history`

Show price trends over time for a specific product.

> "How has the Sony WH-1000XM5 changed in price over the last 90 days?"
> "Has the Dyson V15 ever been cheaper than \$549?"

### `deal_finder`

List products currently below their typical price in a category.

> "Show me the best deals on espresso machines this week."
> "What's on sale in cordless vacuums under \$400?"

### `price_drop_alert`

Surface products whose prices dropped recently.

> "Which TVs have dropped in price in the last 7 days?"
> "Any recent price drops on Bose headphones?"

## Marketing

Per-query price: **\$0.01**

### `competitive_landscape`

Per-retailer pricing snapshot for a category or competitor set.

> "How do AirPods Pro prices compare across Amazon, Walmart, and Best Buy?"
> "Show me the competitive landscape for robot vacuums under \$500."

### `brand_tracker`

All products from a brand with current price + availability.

> "Track all Bose headphone listings in the US."
> "What KitchenAid stand mixers are currently in stock and what do they cost?"

### `promo_intelligence`

Promotional activity by retailer or brand — who's running deals, how deep, how often.

> "What promotions has Walmart been running on KitchenAid this quarter?"
> "How aggressive are Amazon's promos on Apple accessories vs. Best Buy's?"

### `share_of_shelf`

Percentage of category listings that each brand occupies — a digital-shelf-share signal.

> "What's Apple's share of shelf in wireless earbuds?"
> "Which brand dominates listings in the cordless drill category?"

### `price_positioning`

Premium / mid / value positioning by brand within a category.

> "Where does Anker sit in wireless charging — premium or value?"
> "Show me the price positioning of all major brands in robot vacuums."

### `brand_breakdown`

A brand's assortment broken down by category — what it actually sells, not what it is known for.

> "What categories does Olipop actually sell into?"
> "Break down Lululemon's assortment by category."

### `retailer_assortment`

Which retail chains carry a brand or a category. You must pass at least one of brand or category.

> "Which retailers carry Olipop?"
> "Who stocks cordless vacuums in the US?"

### `availability_index`

Out-of-stock rates by retailer or by category root. You must pass at least one of category or brand.

> "Which retailers are most often out of stock on KitchenAid?"
> "Compare out-of-stock rates across grocery-gourmet-food."

## Analyst

Per-query price: **\$0.02**

### `inflation_tracker`

Period-over-period price change for a category.

> "What's the inflation rate for grocery essentials in the US over the last 6 months?"
> "How much have TV prices changed year-over-year?"

### `price_dispersion`

Spread of prices for a single product across retailers.

> "How much price variance is there for the iPhone 16 Pro across US retailers?"
> "Which products in the laptop category have the widest price spread?"

### `retailer_index`

Average pricing posture of a retailer relative to a category baseline.

> "Is Costco actually cheaper than Walmart on average for grocery items?"
> "Where does Target sit on the price index for home goods?"

### `price_bands`

Price architecture of one category shelf: the window that counts as "similarly priced" there, plus entry-through-luxury tiers. Scoped by a browse-node path, not a category term.

> "What are the price bands under electronics/headphones?"
> "Does \$199 compete on the electronics/headphones shelf, or is it a different tier?"

### `category_summary`

Statistical pricing summary for a category — distribution, median, range.

> "Give me a pricing summary for cordless vacuums under \$500."
> "What's the price distribution for noise-cancelling headphones?"

### `category_concentration`

How concentrated a category is: a few brands owning the shelf vs. genuinely fragmented.

> "Is the cordless vacuum category concentrated or fragmented?"
> "How much of grocery-gourmet-food shelf share sits with the top brands?"

### `price_change_leaders`

Biggest price movers in a category or for a brand over a 7, 30, or 90 day window. You must pass at least one of category or brand.

> "Which grocery-gourmet-food products moved the most in the last 30 days?"
> "Show the biggest 90-day price movers for Bose."

## Taxonomy

Per-query price: **\$0.01**

These resolve product *identity* against [GS1 GPC](https://www.gs1.org/standards/gpc), the global standard for what a product **is**, independently of how any one retailer files it. Use them when you need a stable category key across retailers rather than a browse path.

All three are built to make misses visible: an unresolved input comes back explicitly unresolved rather than quietly guessing at a neighbouring category.

### `classify_product_type`

Resolve a product type or phrase to its GS1 GPC brick, with the brick's class, family, and segment.

> "What's the GPC brick for olive oil?"
> "Classify 'cordless drill' and 'air fryer' into GPC."

### `gpc_reverse_lookup`

The crosswalk in reverse: given GPC codes, return the retailer browse nodes mapped to them. Returns a total count alongside the list, so truncation is detectable rather than silent.

> "Which browse nodes map to GPC brick 10000045?"
> "Show me every category that maps to the olive oil brick."

### `gpc_brick_attributes`

The GS1 attribute schema for one or more bricks — the attribute names and permitted values GS1 defines for that category.

> "What attributes does GS1 define for coffee?"
> "What values are allowed for the 'Packaging Type' attribute on protein bars?"

## Social

Per-query price: **\$0.03**

TikTok and Instagram only — this is not a pan-social listening product. Every Social tool is scoped to **one browse category root**. There is no wildcard: these answers are ranked comparisons, and a cross-category ranking would be meaningless.

<Warning>
  `category` is a browse **category root** such as `grocery-gourmet-food` or `beauty-personal-care`. There is **no** `subcategory` tool argument, and `social_series` only accepts `subject_kind` of `brand` or `category`. Aisle slugs like `beverages` are not a social subcategory — they are not a filter you can pass to narrow a department.
</Warning>

A `404 NOT_PUBLISHED` means we do not publish that rollup yet, **not** that the category is quiet. Nothing is billed for it.

`organic_only` is a live filter (default `false`). Set it when you want to exclude posts marked as ads. Each slice is its own denominator, so shares within an organic-only result sum to 100 of the organic slice, not to the organic share of the whole.

### `creator_index`

Creators ranked by mention volume in a category — who is actually talking about the shelf, not who has the biggest following.

> "Who is driving grocery-gourmet-food conversation on TikTok?"
> "Rank Instagram creators in beauty-personal-care, organic posts only."

### `brand_share`

Share of social **attention** by brand within a category — not share of shelf or of sales. `rank` is emitted only on unfiltered requests; a brand-filtered page is one row and carries no ordinal.

> "What's the share of conversation by brand in grocery-gourmet-food?"
> "How much of grocery-gourmet-food mention volume is Olipop?"

### `category_structure`

Which subcategories own a category's conversation. Use it before brand-level questions, to see where the attention sits.

<Note>
  This **rollup is not published yet** and currently returns `404 NOT_PUBLISHED` for every category. That is a gap in what we publish, not a finding, and nothing is billed. The tool describes a rollup of subcategory *ownership* inside a category root — it is not a `subcategory` query filter.
</Note>

> "Which subcategories own grocery-gourmet-food conversation?"

### `brand_momentum`

Brands rising, falling, or newly appearing in a category. `status: new` is emerging-brand detection.

> "Which brands are rising in beauty-personal-care?"
> "Show new brands appearing in grocery-gourmet-food this window."

### `topic_trends`

Emerging conversation topics in a category.

<Note>
  This rollup is **not published yet** (`404 NOT_PUBLISHED` for every category). Nothing is billed. Do not report that as "no topics."
</Note>

> "What topics are emerging in grocery-gourmet-food?"

### `product_type_trends`

Attention by product type within a category, rather than by brand.

<Note>
  This rollup is **not published yet** (`404 NOT_PUBLISHED` for every category). Nothing is billed.
</Note>

> "Which product types own beauty-personal-care conversation?"

### `social_series`

Weekly mentions and views time series for one subject: a **brand** or a **category**. Use it to chart a trend rather than rank a moment. `subject` is required unless `subject_kind` is `category`.

> "Chart weekly mentions for Olipop in grocery-gourmet-food."
> "Give me the category-level weekly series for beauty-personal-care."

`subject_kind=subcategory` is not accepted.

## Scout

Per-query price: **\$0.05**

The only tools that bind **both** corpora — social conversation and the retail shelf — to one category axis and one brand key. Same category grain as Social: browse `category_root`, no `subcategory` argument. `organic_only` is available here too.

### `attention_vs_shelf`

Brands ranked by the gap between share-of-conversation and share-of-shelf. Attention without distribution is a stocking opportunity; the reverse is shelf that is not earning its space.

> "Which grocery-gourmet-food brands have more conversation than shelf share?"
> "Where is beauty-personal-care over-indexed on shelf vs. social?"

### `launch_buzz`

New shelf arrivals set against the conversation around their brand — launches that landed vs. launches that shipped in silence.

> "Which new grocery-gourmet-food listings landed with social traction?"
> "Show silent launches in beauty-personal-care this window."

## Utility

**Free** — no payment required.

### `wallet_info`

Show the MCP's wallet addresses, balance per chain, and funding instructions.

> "What's my Syntalic wallet balance and where do I send USDC?"

## Filters

The Shopper, Marketing, and Analyst tools accept these optional filters. You don't pass them directly — the MCP infers them from your prompt ("in Canada", "on Amazon", "last 30 days"):

| Filter | Values |
| - | - |
| `country` | `us` or `ca` (defaults to `us`) |
| `retailer` | e.g. `amazon`, `walmart`, `costco` |
| `days` | integer lookback window (where applicable) |

Social and Scout tools take a different set. The MCP infers these from prompts too ("organic only", "TikTok", "last 7 days", "grocery-gourmet-food"):

| Filter | Values |
| - | - |
| `category` | **Required.** Browse category root, e.g. `grocery-gourmet-food`, `beauty-personal-care`. Not an aisle slug. No `subcategory` argument. |
| `window` | `7d`, `30d`, or `90d` (defaults to `30d`) |
| `platform` | `all`, `tiktok`, or `instagram` (defaults to `all`) |
| `organic_only` | `true` to exclude posts marked as ads (defaults to `false`) |
| `limit` | 1–100 (defaults to 25) |
| `country` | `us` or `ca` on Scout tools (defaults to `us`) |
| `subject_kind` | `brand` or `category` on `social_series` only. Not `subcategory`. |

The Taxonomy tools take GPC codes or product phrases instead, and the Discovery tools take their own filters — `coverage_map`, for example, narrows by country, platform, category, or quality status.

## Sample response

A `best_price` call for "wireless earbuds" returns something like:

```json theme={null}
{
  "query": "wireless earbuds",
  "country": "US",
  "best": {
    "retailer": "amazon",
    "price": 89.99,
    "currency": "USD",
    "title": "Apple AirPods (3rd Generation)",
    "url": "https://amazon.com/...",
    "in_stock": true,
    "scraped_at": "2026-04-28T11:14:22Z"
  },
  "alternatives": [
    { "retailer": "walmart", "price": 99.00, "..." },
    { "retailer": "target", "price": 99.99, "..." }
  ]
}
```

The MCP returns these payloads to Claude, which summarizes them in natural language — you'd see something like *"The cheapest wireless earbuds right now are AirPods 3rd Gen on Amazon at \$89.99, with Walmart \$9 higher and Target close behind."*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.