> ## Documentation Index
> Fetch the complete documentation index at: https://syntalic.com/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`; [source and release history](https://github.com/Syntalic/mcp-server)) exposes **17 tools** by default: 6 free and 11 paid **measure tools**, one per [measure](https://syntalic.com/docs/reference/measures.md). Below is what each does and what to ask in natural language. Claude (or your MCP client) fills in the arguments; you don't have to think in parameters.

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.

> [!NOTE]
>
> Upgrading from 0.12 or earlier? The per-route tools (`best_price`, `price_positioning`, `ontology_resolve` and the rest) are now splits of the measure tools. To get them back as separate tools, set `SYNTALIC_TOOLS=routes`. See [Per-route tools](#per-route-tools).

## 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 food and beverages in Canada?"
> "Which categories are thin on Best Buy?"

### `browse_categories`

The product category tree with listing counts per node (one per store, variant and country). Pass a parent path to drill into a subtree.

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

### `list_retailers`

Retailers in the catalog with listing 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 listing counts. An optional query prefix-matches the name, so "sam" finds Samsung. To see the brands on a shelf, use `measure_assortment`.

> "Do you have Anker products?"
> "Which brands do you have that start with Sam?"

### `wallet_info`

Your wallet addresses, the balance on each chain, and funding instructions.

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

## Measure tools

Each tool accepts `subject` (an id from `measure_resolve`, or a name where supported) and `by` (the split; each tool has a default). Both are optional in the tool schema; the selected split determines which route-specific parameters are required. Do not send a subject and its equivalent route parameter together. Each split is answered by one API endpoint, named in the table, and **costs what that endpoint costs**: the MCP calls the endpoint itself, so a split on a \$0.01 endpoint is \$0.01 even when the measure's own HTTP path is \$0.02.

An unsupported split or incompatible subject is rejected before the request is sent. Resolve names to IDs when possible; ambiguous names can return multiple co-equal matches, so select the appropriate kind rather than assuming the first match is correct.

### `measure_offers`

**\$0.01.** Who sells one product, and at what price, now.

| `by` | Answers | Endpoint |
| - | - | - |
| `retailer` (default) | Offers ranked by price quality, current status, stock, freshness, then pack price | `best-price` |

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

### `measure_prices`

**\$0.01 to \$0.02.** The price level and spread of a shelf.

| `by` | Answers | Endpoint |
| - | - | - |
| `summary` (default) | Counts, median and range, promo rate and in-stock rate, top brands | `category-summary`, \$0.02 |
| `distribution` | Mean, spread and percentiles of current prices | `price-dispersion`, \$0.02 |
| `band` | The shelf's price tiers and its comparability window | `price-bands`, \$0.02 |
| `brand` | One brand's place on the shelf's price ladder | `price-positioning`, \$0.01 |
| `product` | Paginated product listings and prices for the shelf | `competitive-landscape`, \$0.01 |
| `retailer` | One retailer's price index against the shelf, day by day | `retailer-index`, \$0.02 |

> "Give me a pricing summary for cordless vacuums."
> "Where does Anker sit on the wireless charging price ladder?"
> "Is Costco cheaper than the grocery shelf on average?"

### `measure_trend`

**\$0.01 to \$0.02.** How prices moved, for a product, a shelf or a brand.

| `by` | Answers | Endpoint |
| - | - | - |
| `period` (default), for a product | One product's price series, with its low, high and direction | `price-history`, \$0.01 |
| `period` (default), for a brand | A brand's price, product count and promo count, day by day | `brand-tracker`, \$0.01 |
| `drop` | Whether one product's current price is below its recent average | `price-drop-alert`, \$0.01 |
| `product` | The products that rose and fell most, on a shelf or for a brand | `price-change-leaders`, \$0.02 |

`period` is about a product or a brand, never a shelf. For a shelf, ask for the biggest movers (`by: product`).

> "How has the Sony WH-1000XM5 changed in price over the last 90 days?"
> "Which electronics products moved the most in the last 30 days?"

### `measure_promotions`

**\$0.01.** Who discounts, how often and how deep.

| `by` | Answers | Endpoint |
| - | - | - |
| `brand` (default) | Promo frequency and depth per brand on a shelf | `promo-intelligence` |
| `retailer` | Promo frequency and depth per retailer on a shelf | `promo-intelligence` |
| `product` | The discounted products on a shelf or for a brand, best first | `deal-finder` |

> "Which retailers discount grocery most often?"
> "Show me the best deals on espresso machines this week."

### `measure_assortment`

**\$0.01 to \$0.02.** What is on the shelf, and who holds it.

| `by` | Answers | Endpoint |
| - | - | - |
| `brand` (default) | Each brand's share of the shelf, by product count | `share-of-shelf`, \$0.01 |
| `concentration` | How concentrated the shelf is: HHI, CR4, effective brands | `category-concentration`, \$0.02 |
| `category` | What a brand sells, counted per category | `brand-breakdown`, \$0.01 |
| `retailer` | Which chains carry a brand or a shelf, and how much of it | `retailer-assortment`, \$0.01 |
| `availability` | Out-of-stock rate per chain | `availability-index`, \$0.01 |

> "What's Apple's share of shelf in wireless earbuds?"
> "Which retailers carry Olipop?"

### `measure_attention`

**\$0.03.** Share of social conversation (TikTok and Instagram), and how it is moving.

| `by` | Answers | Endpoint |
| - | - | - |
| `brand` (default) | Each brand's share of mentions on a shelf | `brand-share` |
| `product` | The catalog products a shelf is talking about | `product-share` |
| `category` | Which subcategories own a shelf's conversation | `category-structure` |
| `creator` | The creators driving a shelf's conversation | `creator-index` |
| `product_type` | Attention per product type, and how the mix is shifting | `product-type-trends` |
| `topic` | The topics emerging and fading on a shelf | `topic-trends` |
| `momentum` | Brands ranked by movement: new, rising, falling | `brand-momentum` |
| `emerging` | Brands creators keep tagging that the catalog does not carry | `emerging-brands` |
| `week` | Weekly mentions and views for one brand or one shelf | `series` |

> "What's the share of conversation by brand in food-beverages-tobacco?"
> "Which brands are rising in health-beauty?"
> "Chart weekly mentions for Olipop."

### `measure_signals`

**\$0.03.** What posts say, as labels: launches, reviews, stance, names, practices.

| `by` | Answers | Endpoint |
| - | - | - |
| `brand` (default) | Launches, reviews, stance, retailers and prices posts attach to each brand | `brand-signals` |
| `product_name` | Product names read off posts that match no catalog product | `product-names` |
| `practice` | The marketing practices creators describe brands using | `tactics` |

With `by: practice`, the `channel` filter takes the nine channels `tactics` takes: email, retail, supply, brand\_launch, growth, social, site, branding and customer. Leave it out to see practices in every channel. Before MCP server 0.14.0 it took only `email`.

> "What are creators saying about new soda launches?"
> "Which marketing practices do creators say beauty brands use on email?"

### `measure_scout`

**\$0.05.** Social attention set against the shelf: the only tool that binds both.

| `by` | Answers | Endpoint |
| - | - | - |
| `gap` (default) | Brands ranked by share of conversation against share of shelf | `attention-vs-shelf` |
| `launch` | New arrivals on a shelf against the conversation around their brand | `launch-buzz` |

> "Which soda brands have more conversation than shelf share?"
> "Which new snack listings landed with social traction?"

### `measure_resolve`

**\$0.01.** A name, phrase or code to ids. Call it first when a question names a brand, shelf, product type or retailer, and scope the other tools with the ids it returns.

| `by` | Answers | Endpoint |
| - | - | - |
| `name` (default) | Every shelf, product type, brand and chain a term names, as ids | `ontology/resolve` |
| `browse_node` | Amazon browse node ids or phrases to GS1 GPC codes | `reference/classify` |
| `gpc_browse_nodes` | The browse nodes mapped onto a GPC code | `reference/reverse` |
| `gpc_attributes` | The attributes GS1 defines for a GPC brick, with their allowed values | `reference/brick-attributes` |

> "What does 'protein bars' map to in Syntalic?"
> "What attributes does GS1 define for coffee?"

### `measure_neighbors`

**\$0.01.** What sits next to an id: ancestors, children, product types, brands, and the chains that carry it (`by: relations`, the only split).

For a shelf (`spt:`) it also answers two social blocks:

* `facets`, in the defaults: the marketing practices creators describe brands using on the shelf, grouped by channel (email, retail, supply, brand launch, growth, social, site, branding and customer care), with the creators and posts behind each.
* `labels`, only when you ask for it by name (`relations: "labels"` (or `relations: ["labels"]` in per-route mode)): what the posts about the shelf are. Each post carries one to three **kinds** (advice, story, pitch, showcase, demo, news, insight, review), up to three **themes** (what it is about) and **facets** such as `for_operators`, `compares_brands` or `pre_launch`. Every item has `creators`, `posts`, `brands` and up to five `example_brands`, over the last 30 days. Read the counts as the tracked corpus (TikTok and Instagram), not as a share of the market. `status: unavailable` means the labels couldn't be read for this answer, either because they aren't published yet or because of a temporary problem. It doesn't mean there are none.

> "Which chains carry this brand, and which don't?"
>
> "What kinds of posts are about soda, and who are they aimed at?"

### `measure_coverage`

**\$0.01.** How much evidence stands behind an id: listings, freshness, channels, and the chains scanned (`by: evidence`, the only split). Use it before saying a brand is "not seen" at a retailer: with a brand id and a `retailer`, it says whether the brand was seen there, the retailer was checked and the brand not seen, or the retailer wasn't checked.

> "How much data do you have on Olipop, and which retailers did you check?"

## Per-route tools

Set `SYNTALIC_TOOLS=routes` to replace the 11 measure tools with per-route tools: **39 tools**, the same 6 free ones and 33 paid, one per endpoint except the five listed below. This is the 0.12 tool set without the inflation tool, which is currently unavailable. The playbook prompts still name these tools. In default mode, use the corresponding `measure_*` tool and split rather than a bare route or measure name.

| Group | Price | Tools |
| - | - | - |
| Ontology | \$0.01 | `ontology_resolve`, `ontology_neighbors`, `ontology_coverage` |
| Shopper | \$0.01 | `best_price`, `price_history`, `deal_finder`, `price_drop_alert` |
| Marketing | \$0.01 | `competitive_landscape`, `brand_tracker`, `promo_intelligence`, `share_of_shelf`, `price_positioning`, `brand_breakdown`, `retailer_assortment`, `availability_index` |
| Analyst | \$0.02 | `price_dispersion`, `retailer_index`, `price_bands`, `category_summary`, `category_concentration`, `price_change_leaders` |
| Taxonomy | \$0.01 | `classify_product_type`, `gpc_reverse_lookup`, `gpc_brick_attributes` |
| Social | \$0.03 | `creator_index`, `brand_share`, `category_structure`, `brand_momentum`, `topic_trends`, `product_type_trends`, `social_series` |
| Scout | \$0.05 | `attention_vs_shelf`, `launch_buzz` |

Five endpoints have measure splits but no standalone MCP tool (they are still callable over HTTP): `product-share`, `brand-signals`, `emerging-brands`, `product-names` and `tactics`. The inflation and similar-brands endpoints are currently unavailable, so the MCP doesn't offer them. Shelf movers are available via `measure_trend` with `by: product`; this is not an inflation statistic.

How to set the variable in your MCP config is on the [MCP server](https://syntalic.com/docs/integrate/mcp.md#choosing-the-tool-set) page.

## Filters

Besides `subject` and `by`, tools accept route-specific parameters. An MCP client can infer them from a prompt, or you can supply them explicitly. The selected split determines which are valid; check the tool schema and API Reference.

| Filter | Values |
| - | - |
| `country` | `us` or `ca` (defaults to `us`) |
| `retailer` | e.g. `amazon`, `walmart`, `costco` |
| `time_window` | `last_30_days`, `last_60_days`, `last_90_days`, `month_to_date`, and others, or explicit `from` / `to` dates (where applicable) |

Social and Scout splits accept the following where supported (not all splits accept every filter):

| Filter | Values |
| - | - |
| `category` | A Shopify taxonomy path: a root such as `food-beverages-tobacco` or `health-beauty`, or any node under it (`food-beverages-tobacco/beverages/soda`). An `spt:` id from `measure_resolve` works in its place. Retired browse roots such as `grocery-gourmet-food` are refused, free, with the root to use instead. |
| `window` | `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). The weekly series uses `weeks` instead. |
| `subject_kind`, `weeks` | For weekly series, select `brand` or `category` and the route-specific number of weeks, rather than `window` |

For `attention` by `emerging` and `signals` by `product_name`, use an `spt:` ID or the split's explicit filters, not a plain category name as `subject`.

A `404 NOT_PUBLISHED` on a social split means that view isn't published in the current data release, **not** that the shelf is quiet. Nothing is billed for it.

## Sample response

Illustrative, abridged `measure_offers` response (not a live quote):

```json theme={null}
{
  "query": "airpods pro",
  "country": "us",
  "currency": "USD",
  "retailers_compared": 4,
  "best_price": {
    "retailer": "amazon",
    "price": 189.0,
    "in_stock": true,
    "match_type": "entity",
    "last_read_at": "2026-11-15T11:14:22Z",
    "current": true,
    "fresh": true
  },
  "other_prices": [
    { "retailer": "walmart", "price": 199.0 }
  ]
}
```

Treat the figures above as examples only. Interpret a real response using its evidence and freshness fields; see [Coverage](https://syntalic.com/docs/reference/coverage.md). A single compared retailer is not a market-wide best price. Every field is described in the **API Reference** tab.

## Prompts and resources

The MCP also serves playbook prompts and resources (`syntalic://playbooks`, `syntalic://ontology/rules`, and `syntalic://ontology/metrics`). The playbook prompts and the rules and metrics resources name the per-route tools, such as `price_positioning` or `promo_intelligence`, and some mention the unavailable inflation tool. In the default tool set, use the matching measure tool and split instead (`price_positioning` is `measure_prices` by `brand`), and skip inflation steps. See the [MCP server repository](https://github.com/Syntalic/mcp-server).


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