> For the complete documentation index, see [llms.txt](https://help.smartico.ai/welcome/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-golden-queries.md).

# MCP - Golden queries

Golden queries are fixed data questions that Smartico wrote and tested: who entered a campaign, who received, opened or clicked a message, which bonuses were issued, how a tournament stands. You give a few values (a period, a campaign), and the query returns the rows. You do not write SQL, and the numbers follow the same definitions in every run.

Use a golden query first when one fits your question. Write your own SQL only when none does: see [MCP - For data analysis](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-for-data-analysis.md).

## Why use them

* **Tested definitions.** "Delivered", "converted" or "redeemed" mean the same thing in every run and for every team.
* **No SQL needed.** The assistant passes the values; the server holds the query.
* **Wider access.** An access profile can run golden queries without being allowed to write its own SQL. **MCP Editor** can run them.

## Who can run them

| Access profile      | Find and run golden queries | See the SQL of a golden query |
| ------------------- | :-------------------------: | :---------------------------: |
| **MCP Full access** |              ✓              |               ✓               |
| **MCP Editor**      |              ✓              |               —               |
| **MCP Analyst**     |              ✓              |               ✓               |
| **MCP Viewer**      |              —              |               —               |
| **MCP No Access**   |              —              |               —               |

In a custom profile, the **Golden queries** group allows `find_golden_queries` and `run_golden_query`. `get_golden_query_sql` comes with `exec_sql` (the **Data warehouse** group). See [MCP - Access Profiles](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-access-profiles.md).

## How to find and run them

There are three tools:

| Tool                   | What it does                                                                                                                                                                                                                                 |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `find_golden_queries`  | Searches the golden queries by a few English `keywords`, or lists all of them without keywords. Returns a card for each one: its key, what it answers, and its inputs with examples. Never the SQL. Read-only.                               |
| `run_golden_query`     | Runs one golden query by its `key` with your values in `params`. Returns the columns and the rows as CSV, the row count and the tokens used. Takes `dry_run`, `max_rows` (up to 1,000, default 100), `force` and `as_file`, like `exec_sql`. |
| `get_golden_query_sql` | Returns the SQL of a golden query, with your values in, as a start for your own query with `exec_sql`. Runs nothing.                                                                                                                         |

In a chat, you do not need to name the tools. Ask your question; the assistant looks for a golden query first. For example:

* *"Which golden queries do you have for campaigns?"*
* *"Show the results of campaign 'Weekend reload' for last week: entries, conversions and the control group."*
* *"Why did emails fail yesterday? Use a golden query."*

As a plain JSON-RPC call (see [MCP - Connect Claude, ChatGPT, Cursor and other MCP Clients](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-connect-claude-chatgpt-cursor-and-other-mcp-clients)), call `run_golden_query` with the `key` of the query and its inputs in `params`, named as on the card that `find_golden_queries` returns. To see the expected token cost before a run, add `dry_run: true`: it checks the values and runs nothing. The dry run is optional.

## Cost

A golden query reads the label's data warehouse, like `exec_sql`. A run uses the label's monthly AI token allowance, by the amount of data it reads. A run with `dry_run: true` shows the expected tokens and uses none. `find_golden_queries` and `get_golden_query_sql` use no tokens. Some golden queries, such as the live tournament leaderboard, read the current state from the back office instead of the data warehouse. They read only your label's rows, and their cost depends on how much they read and how long they run.

## The current golden queries

The list grows. To see the current list on your label, ask the assistant *"List the golden queries"* (it calls `find_golden_queries` without keywords). Dates are whole days in UTC, written YYYY-MM-DD; both the first and the last day are included. Ids are lists: you can give one or several.

| Key                        | What it answers                                                                                                                                                                                                                                                                           | Inputs                                                                                                      |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `campaigns-overview`       | Every campaign that players entered in a period, the busiest first: entries, players, conversions of the target and control groups, conversion rates, attributed deposit value. Start here to find the campaigns to look at.                                                              | First and last day; optional number of campaigns (default 50)                                               |
| `campaign-results`         | Results of given campaigns: entries, players, target and control group entries and conversions, both conversion rates (compare them for the uplift), attributed deposit value. One row per campaign.                                                                                      | Campaign ids, first and last day                                                                            |
| `campaign-players`         | The players who entered given campaigns: when they entered, whether they were in the control group, when they converted or stopped, whether they are still in the campaign, the attributed deposit value. One row per entry.                                                              | Campaign ids, first and last day; optional: only the entries that converted, only the entries still running |
| `campaign-step-counts`     | How many players reached each step of given campaigns, as the numbers on the journey in the back office: one row per step, with players, times reached and control-group players. Shows where players drop out.                                                                           | Campaign ids, first and last day                                                                            |
| `campaign-message-stats`   | The messages of given campaigns, or of every campaign, by campaign, channel and template: sent, delivered, shown (opened), clicked, failed, opted out, delivery and click rates.                                                                                                          | First and last day; optional campaign ids, channel, template and brand                                      |
| `campaign-message-players` | Each message per player: channel, template, gateway, time, and whether it was sent, delivered, shown, clicked or failed (with the reason). For given campaigns, for every campaign, or as one player's message history.                                                                   | First and last day; optional campaign ids, outcome, player, channel, template and brand                     |
| `messages-daily`           | Messages per day by channel, gateway (the email or SMS provider) and brand: sent, delivered, shown (opened), clicked, failed, opted out, delivery and click rates.                                                                                                                        | First and last day; optional time zone, campaign ids, channel, template and brand                           |
| `message-failures`         | Why messages failed: failed messages and players by channel, template and fail reason, with one example of the provider's text.                                                                                                                                                           | First and last day                                                                                          |
| `bonuses-summary`          | Bonuses by template and by what issued them (campaign, automation rule, gamification, store, tournament, mini-game, manual): bonuses, players, how many are redeemed, waiting, failed or expired, the cost value set on the template and the redeemed amount. Optionally one row per day. | First and last day; optional template ids, campaign ids, brand, per day and time zone                       |
| `bonuses-list`             | Every bonus in a period, one row per bonus: player, template, what issued it, its latest status, the bonus amount, the first and last time, the cost value, and the error of a failed bonus.                                                                                              | First and last day; optional status, template ids, campaign ids, player and what issued it                  |
| `mission-completions`      | Missions and badges: players who opted in, completions, players who completed, prizes claimed. One row per mission.                                                                                                                                                                       | First and last day                                                                                          |
| `minigame-results`         | Mini-game plays by game and prize: plays, players, points paid to play, prize amount, prizes claimed.                                                                                                                                                                                     | First and last day                                                                                          |
| `store-purchases`          | Store purchases by item: purchases, players, points spent, the first and last purchase.                                                                                                                                                                                                   | First and last day                                                                                          |
| `store-purchases-list`     | Every store purchase, one row per purchase: when, the player, the brand, the item and the points paid.                                                                                                                                                                                    | First and last day; optional item ids, player and item type                                                 |
| `tournament-leaderboard`   | The live standing of a tournament, as the back office shows it: each player's score, rank, final place and registration status. The latest started run by default.                                                                                                                        | Tournament ids; optional runs and number of places (default 100)                                            |

## Frequently asked questions

**Can I change a golden query?** Not the golden query itself. With `exec_sql` in your profile, ask for its SQL (`get_golden_query_sql`), change it, and run your version with `exec_sql`.

**A golden query returned more rows than I see.** A run returns up to 1,000 rows (100 by default). When a data warehouse golden query is cut, the answer says how many rows the whole result has. Narrow the period, or ask for a summary query instead of a list. If you need every row and your client runs code, run it with `as_file: true` to get the whole result as a file, up to 500,000 rows. This works for golden queries that read the data warehouse, not for the live tournament leaderboard. See [Large Results as a File](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-for-data-analysis#large-results-as-a-file).

**Can a golden query read another label's data?** No. It reads only the data of the label the call runs on.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-golden-queries.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
