Skip to main content
Once you connect an assistant, it gets ten 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 ten are read-only. There is no tool that writes, exports, or reaches another organization’s data.

​
The tools

Every organization sees all ten tools listed. A Shopify or Meta tool called without a connected store or ad account answers SOURCE_UNAVAILABLE instead of data. Connecting the source in your workspace is what makes it answer.

​
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 and is the most reliable way to align with your dashboards.
4

describe_table or describe_tables, then run_bigquery_sql

Only when query_metrics refuses, or the question is not a catalog metric. Use describe_table for one table and describe_tables once for two to four tables.
Ask for query_metrics by name when the number matters. A hand-written revenue, AOV, or ROAS query can diverge from SourceMedium when it uses different fields, filters, dates, or scope, and the answer may not identify the difference. query_metrics applies the canonical formula and SourceMedium’s validity filters, such as is_order_sm_valid.
Two tools sit outside that query path and are worth asking for directly:
  • “Are my connections working?” routes to get_account_health. It reports each connection’s status, how fresh its data is, and who the fix belongs to: you, your provider, or SourceMedium.
  • “What does this metric mean?” routes to search_docs. It reads the same documentation you are reading now, so the assistant can explain SourceMedium concepts instead of guessing.

​
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, unparsable 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_tables 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 or describe_tables. 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 step-by-step setup for each AI tool.

AI assistant troubleshooting

Error codes and what to do about each one.