# Asking Questions and Checking Answers

Asking questions comes after authoring. Once your contract is authored, asking is the easy part: you ask in business language, and your agent, guided by the querying Skill, does the rest. This page explains what your agent does on your behalf, what in the contract makes it work smoothly, and what to tell your agent once so that afterwards you can just ask. If you do not have a contract yet, start with the contract-authoring guide.

## Your agent does the querying for you

Each question is turned into SQL in two steps. Your agent turns your natural language question into a structured request, using its own model and the authored contract, guided by the querying Skill. ADI (via the MCP Server) then compiles that request into SQL, and that step is fixed and deterministic: the same request against the same contract always produces the same SQL.

For example, a question such as "revenue by country in September" might become a request like this, naming the metric, the grouping and the time window:

```json
{
  "query_request_version": "1",
  "metrics": ["net_revenue"],
  "group_bys": ["orders.country"],
  "time_range": {"type": "absolute", "start": "2026-09-01", "end": "2026-09-30"}
}
```

The grouping field is `group_bys`. A request using `group_by` is refused as `request_malformed`, and the refusal names the right field.

The querying Skill guides your agent through the part that needs judgement:

- **It matches your words to the contract.** Your terms are looked up in the contract's vocabulary. If a term could mean more than one metric, your agent tells you which one it picked, and names the others, before it runs the query.
- **It handles refusals.** If a request is refused, your agent reads what the refusal allows, such as the metrics or groupings on offer, and either retries with a corrected request or asks you to choose.
- **It asks your agent to keep the write-up faithful to the contract.** The Skill tells your agent to report figures the contract keeps separate, such as revenue in two currencies, separately, and, when it ranks by a rate, to fetch the count behind each rate as well, where the contract declares one.
- **It runs the SQL, or hands it to you.** At this tier ADI generates and validates SQL but does not run it. Your agent runs it with a database client or warehouse connection that is already set up where it works, or gives it to you to run yourself. If your agent needs to install anything to run the SQL, the querying Skill (from plugin 1.2.0) has it ask you first, but it may not always follow that; to reduce the risk, follow the precautions in Step 6 of Getting Started and check what it runs.
- **It shows its working.** Every governed answer comes with provenance: the metric measured, the joins applied, the filters and time window you asked for, and the policies honoured, plus a plain-language summary. A metric's own built-in filters appear only in the SQL.

A lighter model such as Haiku can be used for querying, but its error rate may be higher, so check its answers further before you use them. Beyond the checks below, ask your agent to send the contract files exactly as saved, and to compare the `contract_hash` each response returns and stop if it changes (see the Features page). The briefing below matters more if you use one. The investment belongs in authoring, which is where the contract-authoring guide recommends your strongest available model.

## The contract is what makes this work smoothly

Much of what makes querying smooth is decided when the contract is authored. Four things are worth having in place:

- **Your team's own words in the vocabulary.** Include the terms and abbreviations people actually use for each metric, as well as its formal name, and decide deliberately what a bare word such as "count" or "revenue" should mean.
- **A month or quarter column for trends.** A structured request cannot bucket dates, so grouping by a date returns one row per day. If the contract declares a month or quarter column and allows it as a grouping, monthly figures come back governed for any type of metric. Without one, only sums and counts can be rolled up, and the rollup sits outside the contract.
- **A count behind each rate.** A ranking on a rate can be led by a group with only two records behind it. Declaring the count as a metric lets your agent show it next to each rate. Some rates cannot be declared as a single metric and have to be worked out from two, and those are where figures can vary between runs.
- **The groupings people ask for.** A metric can list the groupings it permits, so allow the breakdowns your team needs.

The contract-authoring guide covers the vocabulary, the groupings and rates that have to be worked out from two metrics. A month column or a count metric is something to ask your agent to add while authoring, through a view if the table has no such column.

**Querying also tells you how to improve the contract.** If an answer is not what you expected, the fix is often something to add to the contract, such as a missing term, grouping or column. Once it is there, it holds for every later question and for everyone working from that contract. Keep the questions you ask with the question list from Step 1 of the contract-authoring guide, and re-run that list whenever you amend the contract.

## Tell your agent once, then just ask

The querying Skill already covers most of what matters. A short briefing covers the rest, so that you do not have to repeat these points each time. Add it to the standing instructions your agent reads at the start of each session, such as its project instructions file (in Cowork, see Using ADI in Claude Cowork in Getting Started):

```
When answering data questions with ADI:
- Start each answer by saying whether it came from ADI, from a saved ADI query, or from somewhere else, and which metric was used and which filters I asked for.
- Show the components behind any total, and never combine figures the contract keeps separate.
- Do not put personal values, such as names or email addresses, into a request to ADI. Ask me how to phrase the question without them, for example by a category.
- For any report I say I will run again, save the SQL together with its provenance and a copy of the contract bundle it was generated from, and re-run it on my own warehouse from the saved copy. Regenerate it through ADI if the contract bundle has changed since then or the period it covers has moved on.
- For a large set of questions, work through them in small groups.
```

Three things stay with you:

- **A glance at the first line of each answer.** If it says the answer did not come from ADI, or the provenance is missing, do not use the figure until your agent has either run it through ADI or told you why it could not. Keep this check yourself, because an agent that has left the governed path is not the best judge of that.
- **Your own judgement before a figure goes into a decision.** The contract governs the SQL and not the sentence your agent writes about the result, so look at the components your agent shows you.
- **Not typing personal details into your questions.** The briefing asks your agent not to send them to ADI, but anything you type is already handled by the model your agent runs, under your model provider's terms.

## If something does not look right

The Troubleshooting guide covers the specific cases, including a refusal for a question the data should answer, an answer using a metric you did not mean, an answer with no provenance, and an empty result.

## Where to go next

- **The contract-authoring guide** covers preparing, authoring, testing and refining the contract, starting from your own glossary
- **Beta Notes and Known Issues** covers time grains, date ranges and the other current limitations
- **The Features page** documents the MCP tools, provenance and the full refusal set
- **The Troubleshooting guide** covers specific failures and what to do about each
- **Legal and Data Use** sets out what reaches ADI when you ask a question