What the MCP tools do

The seven tools a connected AI assistant can call, what each one is for, and the order that produces correct answers.

Once you connect an assistant, it gets seven tools. You do not call these yourself. The assistant picks them, and their descriptions tell it how. This page is here so you can tell whether it picked well, and so you can steer it when it did not.

All seven are read-only. There is no tool that writes, exports, or reaches another organization’s data.

The seven tools

Tool	What it does
get_data_context	Reports your organization, the BigQuery project and datasets the assistant may query, your connected Shopify stores and Meta ad accounts, and the server limits. Takes no arguments.
search_data_catalog	Searches tables, columns, and SourceMedium metric definitions using your own words. Called with no query, it lists every documented table and metric.
describe_table	Returns one table’s columns with type, null rate, distinct count, and observed min/max, plus the SourceMedium metrics computed from that table.
query_metrics	Compiles a named SourceMedium metric into SQL and runs it. Applies the canonical definition and SourceMedium’s own filters.
run_bigquery_sql	Runs one read-only SELECT against your warehouse. For custom or cross-table analysis.
shopify_admin_graphql	Runs one read-only GraphQL query against a connected Shopify store. Needs Shopify enabled for your organization.
meta_ads_query	Reads live data for a connected Meta ad account. Needs Meta enabled for your organization.

The order that gets correct answers

The assistant should look names up before it writes anything:

1. get_data_context

   First call in a session, and again before touching a source it has not used. Cheap, and it prevents guessing.

2. search_data_catalog

   Finds the real column and metric names for what you asked about.

3. query_metrics, when a named metric matches

   This compiles SourceMedium’s own definition. Numbers match your dashboards.

4. describe_table, then run_bigquery_sql

   Only when query_metrics refuses, or the question is not a catalog metric.

Ask for query_metrics by name when the number matters. A hand-written revenue, AOV, or ROAS query will not match what you see in SourceMedium, and nothing in the answer will tell you it is wrong. query_metrics applies the canonical formula and SourceMedium’s validity filters, such as is_order_sm_valid.

The mistake to watch for

The single most common failure is an assistant inventing a column name. Order revenue is order_net_revenue on obt_orders. It is not total_price, and dim_orders has no revenue column at all.

If an answer looks off, ask the assistant which table and column it used. If it names something you do not recognize, tell it to call search_data_catalog and try again.

Why a table can be documented but not queryable

search_data_catalog reports gaps in two directions, and they mean different things:

Direction	What you see	What it means
Documented, but not in your warehouse	queryable: false on the table, and the name listed under coverage.not_queryable	The table has SourceMedium documentation but is not delivered to your project. Usually a Foundation plan table that is Pro only. The assistant must not write SQL against it.
In your warehouse, but not documented	The name listed under coverage.uncatalogued	The table is live in your project but has no SourceMedium definition. You can query it, but there is no canonical metric for it.

When query_metrics refuses

It compiles one table per call, and it fails closed rather than guessing. It refuses cross-table metrics, unparseable formulas, and filters it cannot resolve.

Cross-table ratios are the common case. Blended ROAS and MER divide order revenue by ad spend, which live on different tables, so the assistant falls back to describe_table and run_bigquery_sql. That is expected. See ROAS for the two definitions and which one you want.

When it falls back, the calculation string the catalog shows is documentation, not runnable SQL. A correct fallback follows the metric’s structured dependencies and uses only real columns from describe_table. If your assistant pastes the calculation string into a query, stop it.

Paging through Shopify and Meta

Both provider tools cap a page at 100 records, and paging is not automatic. The response carries a cursor, and the assistant has to pass it back on a follow-up call. If you asked for “all campaigns” and got exactly 100, ask it to keep paging.

Query limits for the warehouse tools are on Connect an AI assistant.

Related

Connect an AI assistant

Connection URL, sign-in, and what the assistant can reach.

Assistant troubleshooting

Error codes and what to do about each one.