> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sourcemedium.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/docs/ai-analyst/connect-from-chatgpt-claude), 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:
First call in a session, and again before touching a source it has not used. Cheap, and it prevents guessing.
Finds the real column and metric names for what you asked about.
This compiles SourceMedium's own definition. Numbers match your dashboards.
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](/docs/data-activation/managed-data-warehouse/overview) 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](/docs/help-center/common-analyses/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](/docs/ai-analyst/connect-from-chatgpt-claude#limits).
## Related
Connection URL, sign-in, and what the assistant can reach.
Error codes and what to do about each one.