Skip to main content
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

​
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:

​
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.

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.