.png)
.png)
2
Retailer Tools Reference
This article covers every tool available to Headset Retailer subscribers through the Headset MCP server. You don't call these tools yourself. You ask a question in plain English, and the AI picks the right tool (or chain of tools) to answer it. Knowing what's available helps you ask better questions and understand what's possible.
All tools are read-only. Nothing the AI does through this connector can modify your Headset data.
The tool set at a glance
| Tool | What it answers |
|---|---|
current_user_accounts |
"Which accounts do I have access to?" |
retailer_get_stores |
"Which of my stores are connected?" |
retailer_sales_totals |
"What did we sell?" (one grand-total answer) |
retailer_sales_by_dimension |
"Top X by Y" (ranked breakdowns) |
retailer_sales_trend |
"How is it changing over time?" |
retailer_get_inventory |
"What's on hand, and what's running low?" |
retailer_benchmarks |
"How do I stack up against my state?" |
search_dimension_values |
Resolves your wording to exact catalog values |
menu_brands * |
"Which brands dominate menus in my market?" |
menu_stores * |
"Who are my competitors, and who carries brand X?" |
* Requires the Competitive Intelligence add-on. See the callout at the bottom of this article.
Account and store tools
current_user_accounts
Returns the Headset accounts visible to your login. Mostly used behind the scenes when the AI needs to confirm what you have access to.
retailer_get_stores
Lists your POS-connected stores. The AI typically calls this first to scope other questions ("across all my stores" vs. "just the Bellevue location") and to figure out which state you operate in.
Try asking:
Which of my stores are connected to Headset?
Sales tools
The three sales tools share the same filters, so any question can be scoped by time window, store, state, city, brand, category, vendor, pack size, product, medical vs. recreational, customer gender, or customer age group.
Time windows use natural expressions: "last 30 days", "this month", "yesterday", "2026-06-01 to 2026-06-30". If you don't specify a window, the AI is querying all-time data, so it's worth being explicit.
Available measures: total revenue, gross sales, units, discounts, cost, profit, transaction count, average item price, gross margin %, and % of revenue with cost data. If you don't ask for specific measures, you get revenue and units.
retailer_sales_totals
One grand-total row, no breakdown. This is the fastest answer to "how much" questions.
Try asking:
What was our total revenue and profit last month?
How many units of Wyld did we sell in the last 90 days?
retailer_sales_by_dimension
Sales broken down by exactly one dimension, ranked by a measure. This is the workhorse for "top X by Y" questions.
Dimensions: store, state, city, category, brand, vendor, product, unit (pack size), medical vs. recreational, order source, employee (budtender), customer gender, customer age group.
The AI can combine a filter with a dimension for anchored questions: "best-selling gummies" becomes a product breakdown filtered to the Edibles category, and "flower sales by pack size" becomes a unit breakdown filtered to Flower.
Try asking:
What were our top 15 brands by revenue in the last 30 days?
Who was our best-performing budtender last week?
Break down last month's sales by customer age group.
retailer_sales_trend
Sales over time. Pick a grain (day, week, month, quarter, or year) and get one row per period, in order. Optionally cross the trend with one dimension (brand, category, store, unit, medical vs. recreational, or employee) to see how the mix shifts over time.
Try asking:
Show me weekly sales for the last 12 weeks.
How do Saturdays compare to the rest of the week?
Chart medical vs. recreational revenue by month for this year.
Inventory
retailer_get_inventory
Current on-hand inventory across your stores, in two modes:
- Per-product mode (the default): one row per SKU with on-hand units, price, days and weeks of supply, on-hand retail and cost value, and average daily sales velocity. Sorted by weeks of supply ascending by default, so reorder candidates surface first.
- Grouped mode: totals rolled up by category, brand, vendor, store, or unit (pack size), with measures like product count, stockout count, on-hand units and value, and trailing-28-day units and revenue.
Filters include store, category, brand, vendor, pack size, in-stock only, and min/max weeks of supply. That last one is how the AI finds low-supply items ("under 2 weeks of supply") or overstock ("more than 12 weeks").
One important boundary: this tool describes what's running low. It does not calculate suggested order quantities. For prescriptive reorder amounts, use the reorder report in Headset Retailer.
Try asking:
Which products have less than two weeks of supply left?
What's my total on-hand inventory value by category?
How many flower eighths do I have on hand for Raw Garden?
Benchmarks
retailer_benchmarks
Compares a store's monthly performance against other stores in the same state. For each metric (basket count, items per basket, average item price, discount rate, and revenue) you get your store's percentile rank from 0 to 100, the state cohort's 25th/50th/75th/95th percentile values, and month-over-month and year-over-year growth.
Benchmarking data is monthly and trails the current month, so questions are answered against the most recent fully-closed month.
Try asking:
How did my store rank in the state last month?
Is my discount rate high compared to other stores in Washington?
Which of my stores is underperforming its state cohort?
The lookup helper
search_dimension_values
Your catalog has exact names, and the way people talk doesn't always match them. This tool searches your own sales data for the canonical brand, category, vendor, product, and pack-size values, matched loosely ("pre roll" finds "Infused Pre-Roll", "3.5" resolves to "3.5 Gm").
The AI uses this automatically before filtering, so when you say "eighths" it filters on the exact unit value your data actually uses. Results are ranked by units sold, so the most relevant match comes first.
Try asking:
What categories do I sell? What does my data call pre-rolls?
Competitive Intelligence tools
Requires the Competitive Intelligence add-on. These two tools read crawled competitor e-commerce menu data rather than your own POS data. If the add-on isn't on your account, the AI will let you know what it unlocks; contact [email protected] to enable it.
menu_brands
Brands present on competitor e-commerce menus in one or more states, ranked by store count by default. Each brand includes per-state store count, SKU count, distribution %, and sales per store. Pair it with your own sales-by-brand breakdown for a brand gap analysis: which brands are winning menus in your market that you don't carry?
Try asking:
Which brands have the widest distribution on Washington menus?
Is Stiiizy carried in Colorado? How widely?
Which top-20 menu brands in my state am I not carrying?
menu_stores
Competitor dispensaries in a state (optionally narrowed by city), with menu size, brand count, and velocity signals. This also answers "who carries brand X near me": the AI looks the brand up with menu_brands first, then finds the stores carrying it.
Try asking:
Who are the biggest competitor menus in Seattle?
Which stores near me carry Jeeter?
Which dispensaries in Oregon have the fastest-moving menus?
How the tools chain together
The real power is in combinations. A question like "Are my best-selling brands losing ground in the broader market?" might chain retailer_get_stores (to find your state), retailer_sales_by_dimension (your top brands), and menu_brands (their market distribution), and give you one synthesized answer. You don't have to orchestrate any of that. Just ask the question you actually care about.
For ready-made prompts, see Example Prompts & Workflows. For data boundaries and tips on asking good questions, see Limitations, Tips & FAQ.
