Skip to main content
Once you connect an assistant, it gets these tools. You do not call them 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. None of them writes to your data, exports it, or reaches another organization’s.

​
The tools

Every connection lists the eight data tools above. A connection on SourceMedium’s earlier tool set lists two more, describe_table and describe_tables, which describe documented tables; on the current tool set search_data_catalog does that job and also reaches your own tables. The tools your assistant lists show which set its connection has. Newer connections also carry submit_feedback, which the assistant is asked to call once when it finishes, so you may see it run without having asked for it. 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 the tables, then run_bigquery_sql

Only when query_metrics refuses, or the question is not a catalog metric. The assistant describes up to four tables in one call (search_data_catalog with the table names, or describe_tables on the earlier tool set), then writes SQL using only the names it returned.
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: Looking for one of your own tables? Ask the assistant to find it by part of its name, such as “spend tracker”. search_data_catalog lists the matching live tables across every dataset it can query.

​
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 describing those tables and writing 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 the table descriptions. 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 your own agent.

Connect your own agent

Connection URL, sign-in, and step-by-step setup for each AI tool.

Agent connection troubleshooting

Error codes and what to do about each one.