Bridge Tools Reference

This article covers every tool available to Headset Bridge subscribers through the Headset MCP server. Bridge gives brands and distributors sell-through visibility into the retailer stores that share data with them, and the MCP server puts that visibility one question away: "How did our brand sell across our connected stores last month?" is now a single prompt.

All tools are read-only. Nothing the AI does through this connector can modify your Headset data or your connections.

The one concept to understand: connections

A Bridge account has no stores of its own. Everything you can query flows through your connections: the retailer stores that have agreed to share data with you. Only Active connections have queryable sales and inventory data; pending invites don't count until the retailer accepts.

That's why most conversations start (visibly or behind the scenes) with the AI listing your connections, and why store-scoped questions are always scoped to connected stores.

The tool set at a glance

Tool	What it answers
bridge_find_connections	"Which stores am I connected to?"
bridge_sales_totals	"What sold across my connections?" (one grand total)
bridge_sales_by_dimension	"Top X by Y across my connections"
bridge_sales_trend	"How is sell-through changing over time?"
bridge_get_inventory	"What do my connected stores have on hand?"
bridge_search_dimension_values	Resolves your wording to exact catalog values

---

Connections

bridge_find_connections

Lists your account's connections to retailer stores. Each connection includes the store/account name, its status, and the retailer store ID that every other bridge tool uses for store-level scoping.

By default it returns Active connections (the ones with queryable data). You can also ask about Pending invites to see who hasn't accepted yet. Accounts with hundreds of connections are paged automatically; the AI keeps fetching pages until it has seen them all.

Try asking:

Which stores am I connected to?

Do I have any pending connection invites?

Am I connected to Lux Pot Shop?

---

Sales tools

The three sales tools share the same filters: time window, specific stores (by connection), state, city, brand, category, vendor, pack size, product, medical vs. recreational, customer gender, and customer age group.

Time windows use natural expressions: "last 30 days", "this month", "2026-06-01 to 2026-06-30". If you don't specify one, you're querying all-time data, so be explicit.

Available measures: total revenue, gross sales, units, discounts, cost, profit, transaction count, store count, average item price, gross margin %, and % of revenue with cost data. The default is revenue and units. The store_count measure is Bridge-specific and answers "how many of my connected stores sold this?"

bridge_sales_totals

One grand-total row across your connected stores, no breakdown. Fastest answer to "how much" questions.

Try asking:

What was our total sell-through revenue last month across all connections?

How many units of our Sour Gummies sold in Washington stores in the last 60 days?

bridge_sales_by_dimension

Sales broken down by exactly one dimension, ranked by a measure.

Dimensions: store, state, city, category, brand, vendor, product, unit (pack size), medical vs. recreational, order source, customer gender, customer age group.

Note that unlike the retailer tool set, Bridge has no employee dimension (budtender-level data belongs to the retailer).

Try asking:

Which of my connected stores sold the most of our brand last month?

What are our top 10 SKUs by units across all connections?

Break our sales down by customer age group.

bridge_sales_trend

Sell-through over time. Pick a grain (day, week, month, quarter, or year), optionally crossed with one dimension (brand, category, store, unit, or medical vs. recreational).

Try asking:

Show weekly sell-through of our brand for the last 12 weeks.

Is our velocity growing month over month in each connected store?

Med vs. rec split by month for this year.

---

Inventory

bridge_get_inventory

Current on-hand inventory across your connected retailer stores. Two modes:

• Per-product mode (the default): one row per SKU per store, with on-hand units, price, days and weeks of supply, on-hand value, and average daily velocity. Sorted by weeks of supply ascending by default, so at-risk items surface first.
• Grouped mode: totals rolled up by category, brand, vendor, store, or pack size. Grouped measures include product count, stockout count, on-hand units and value, trailing-28-day units and revenue, and (except when grouping by store) the number of connected stores carrying each row.

This is the tool for spotting stores about to run out of your product. Ask about items under a supply threshold, filtered to your brand, and you have a call list for your sales reps.

The boundary to know: it describes what's running low, but it does not calculate suggested reorder quantities.

Try asking:

Which connected stores have less than two weeks of supply of our flower?

How many of my connected stores are currently stocked out of our top SKU?

Total on-hand units of our brand by store.

---

The lookup helper

bridge_search_dimension_values

Retailer catalogs name things differently than you do. This tool searches your connected-store 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 it automatically before filtering, so your questions land on the exact values the data uses. Results are ranked by units sold.

Try asking:

What do my connected stores' menus call our products?

---

How the tools chain together

A question like "Which connected stores are selling through our new gummies fastest, and which are about to stock out?" chains bridge_find_connections, bridge_search_dimension_values (to pin down the product), bridge_sales_trend (velocity by store), and bridge_get_inventory (weeks of supply). You just ask the question; the AI handles the plumbing.

For ready-made prompts, see Example Prompts & Workflows. For data boundaries and tips, see Limitations, Tips & FAQ.