dataspring-cli 0.3.0__py3-none-any.whl

cli/_skills/dataspring-consume/SKILL.md

@@ -0,0 +1,712 @@
+---
+name: dataspring-consume
+description: How to query DataSpring correctly to answer analytical questions. Use when the user is asking analytical/business questions, when an agent is connected to a DataSpring MCP server, when running `dataspring query ...` from the terminal, or when scripting against DataSpring's REST API. Covers the three surfaces (MCP, CLI, REST) — same principles, different invocations.
+---
+
+# Querying DataSpring to answer analytical questions
+
+You are querying DataSpring. Three surfaces are available — pick the
+one the caller is using:
+
+- **MCP** — agent connected to a DataSpring MCP server (Claude
+  Desktop, Claude Code via stdio, etc.). Tool calls.
+- **CLI** — `dataspring` from the terminal. Shell commands.
+- **REST** — direct HTTP. Scripts, integrations.
+
+The principles below are surface-agnostic, drawn from real production
+traces — departing from them produces misleading numbers.
+
+## Surface cheatsheet
+
+| Operation | MCP tool | CLI | REST |
+|---|---|---|---|
+| List metrics | `list_metrics()` | `dataspring metrics list` | `GET /api/semantic-layer/metrics` |
+| List dimensions | `list_dimensions()` | `dataspring dimensions list` | `GET /api/semantic-layer/dimensions` |
+| Explain one metric | `explain_metric(metric_name)` | `dataspring metrics show <name>` | `GET /api/semantic-layer/metrics/<name>` |
+| Query | `query_metrics(metrics, dimensions?, grain?, start_date?, end_date?, where?, ...)` | `dataspring query -m <name> [-d ...] [-g month] ...` | `POST /api/dispatch/query_metrics` with the same fields |
+| Explain what was computed | `explain_query(metrics, ...)` (same fields as `query_metrics`) | (no CLI command yet) | `POST /api/dispatch/explain_query` |
+| What DataSpring learned / undo | `learned_edit list` / `undo` | `dataspring learned list` | `GET /api/learned` |
+| Verified queries | `verified_query_edit list` / `record` | (no CLI command yet) | (no dedicated route) |
+| Read business_context | `dataspring://context` resource | `dataspring business-context get` | `GET /api/context` |
+| Check business_context size | `business_context_edit show_size` | `dataspring business-context size` | (no dedicated route — use `GET /api/context` and measure) |
+| Org's published skill | (this skill, served via SKILL.md) | `dataspring skill instructions consume` | `GET /api/v1/skill/consume/instructions` |
+
+No catalog is pre-loaded. You are handed NO catalog up front — the catalog
+index (`list_metrics` / `dataspring metrics list` / `GET
+/api/semantic-layer/metrics`) is the only place it exists, so start there
+every time (see §2). Pass the user's question verbatim where the surface
+accepts one — it is what lets the index flag an `ambiguous` set of
+candidates (§2.1) instead of leaving you to guess between them.
+
+All three surfaces hit the same backend, semantic layer, and authorisation
+rules — same `business_context` and `description` bytes everywhere.
+
+## Getting the CLI and this skill
+
+One line installs the CLI (it installs `uv` first if the machine has none),
+then log in and install the skills the server serves, so the text an agent
+reads is the one this deployment was built with:
+
+```bash
+curl -fsSL https://dataspring.app/install.sh | sh    # Windows: irm https://dataspring.app/install.ps1 | iex
+dataspring login
+dataspring skills install --all                      # into ~/.claude/skills/<name>/, stamped
+```
+
+Run `dataspring skills install` again after `dataspring upgrade` (the CLI
+upgrades itself in place; `dataspring --version` says when the server has
+operations this CLI does not know). `dataspring skills diff` shows what
+drifted between the installed copy and the served one; `--offline` on any
+`skills` command uses the copy bundled in the CLI instead of the server.
+
+## 1. Knowledge layers — consult before querying
+
+Before answering any analytical question, gather context from these
+sources, in order:
+
+| Layer | Source | What it gives you |
+|---|---|---|
+| 1. Org orientation | `business_context` (§13) | What the org sells, what's synced (and what isn't), cross-cutting derivation rules |
+| 2. Semantic layer catalog | `list_metrics()` / `dataspring metrics list` / `GET /api/semantic-layer/metrics`, and the dimensions equivalents | An index of every metric and dimension in the org — names, grain, one-line summaries, most-used first |
+| 3. Metric/dimension detail | `explain_metric(name)` / `dataspring metrics show <name>` / `GET /api/semantic-layer/metrics/<name>` | Unit, source rollup, standing filter rules, caveats (§3–§6) |
+| 4. Runtime state | the query response itself | Whether the assumption actually holds — `NO_DATA`, an error `code`, a row count of zero |
+
+Gather each layer ONCE. If you already have a layer, move to the next one; re-reading something
+you have been given is the most common way to burn a turn without
+improving the answer. And this ladder is for ANALYTICAL questions: a
+greeting or a one-word reply needs none of it.
+
+Each layer is cheaper to check than the next is to discover the hard way:
+`business_context` says what's plausible, the catalog says what's
+queryable, and only the query result can contradict the first three. Don't
+skip straight to a query on a hunch — "obvious" metric names and assumed
+data coverage are wrong often enough to matter.
+
+## 2. The discovery pattern
+
+**No catalog is pre-loaded.** Whatever surface you are on, you have
+not been given the org's metrics — not in your system prompt, not in
+this skill, not in an attachment. The catalog exists only behind the
+tools below, and it is only ever as current as the call you make.
+Answering from a metric name you inferred, remembered, or assumed
+because it is the obvious English word is the failure this section
+exists to prevent.
+
+For any analytical question, in this order:
+
+1. **List the catalog INDEX** — `list_metrics()` plus `list_dimensions()` on MCP; `dataspring metrics
+   list` on the CLI. You get names, type, grain and a one-line summary
+   per entry, ranked with the org's most-used entries first. It is an
+   index: enough to decide what is relevant, deliberately not enough to
+   answer with. Pass the user's question verbatim where the surface accepts one (§2.1), and
+   narrow a large index with the `query` substring parameter rather than
+   paging through it.
+2. **Explain what you picked** — `explain_metric` /
+   `explain_metric(names=[...])`, for every entity the question
+   touches, in ONE call. This is where the authoritative description
+   lives: unit, source rollup, standing filter rules, caveats (§3). Read
+   it before you query; do not paraphrase from the name or the summary.
+3. **Query** — only now, with the names and grains you just confirmed.
+
+Don't skip step 1: "obvious" metrics like `total_revenue` differ across
+orgs in unit, source, and standing filter rules, and a name matching the
+question's English words is exactly the case where skipping feels safest
+and is not.
+
+Once you've read an entity's index row and description this conversation,
+they stay in context — a follow-up or drilldown on the SAME entity goes
+straight to the query. Re-list when the user pivots to a new subject.
+
+**A `caveat` on an index row is not optional to skip.** The row
+carries the metric's own KNOWN ISSUE / CAVEAT sentence (for example
+`caveat: "KNOWN ISSUE: only surveyed tickets are counted"`). When a
+row carries a `caveat`, step 1 alone is not enough — you MUST
+call `explain_metric` (`explain_metric`) for that entity before
+answering, and your answer must surface the caveat alongside the
+number. A one-line summary is where a caveat goes silently missing
+(§3).
+
+This skill deliberately names no metrics of its own. Any metric or
+dimension list in front of you comes from your org's semantic
+layer, never from this document — a catalog written into a skill
+drifts from the manifest the moment someone edits a dbt model.
+
+## 2.1 Disambiguate instead of guessing
+
+When two or more metrics plausibly answer the question, **ask — do not
+pick**. Picking one and reporting its number is the most expensive
+mistake available to you: the answer looks finished, so nobody checks it.
+
+Calibrate on a real case: one org's revenue metrics exist as explicit
+`*_ex_vat` / `*_inc_vat` pairs because the two readings differ by 25% and an
+agent that silently chose was wrong a quarter of the time.
+
+**What counts as ambiguous.** Several metrics match what the question
+named, and nothing in the question separates them. A period, a filter or a
+breakdown does NOT separate them ("churn last month" is exactly as
+ambiguous as "churn" — a window narrows the query, never the metric).
+Endorsement does not either — a metric on ten dashboards is the org's
+*default*, not an answer to "which reading did you mean"; lead your
+question with it, still ask. What DOES separate them is a term the user
+supplied that fits one and not the others ("churn *rate*", "*total*
+revenue"), or a description that answers the question the others cannot —
+one clear winner: use it, and say which you used.
+
+**Check before you query, not after.** A bare family term with no
+qualifier of its own — treat it as ambiguous until the catalog says
+otherwise; the ambiguity is only visible once you can see the whole family
+side by side.
+
+`list_metrics` runs this check for you when you pass the user's
+question verbatim. When it cannot separate the candidates it returns an
+`ambiguous` block naming them: stop and ask — **do not query any of them**
+without a reason you could state out loud. The check is a floor, not a
+verdict either way: no flag is not a clearance when you can see two
+readings it did not catch (ask anyway); a flag is not always the last
+word if the user's own wording already picks one out (use that one and
+say so).
+
+**Querying every candidate is not disambiguation.** Running all eight
+members of a family and reporting the set answers a question the user
+did not ask, costs eight queries, and leaves them to pick the number
+themselves — which was your job to ask about.
+
+**How to ask.** One short question that (1) names at least two candidates
+by their exact catalog identifiers — "Net or gross?" without names leaves
+the user guessing which metrics you mean — and (2) says what distinguishes
+them (unit, source, population, period, standing filter; the index
+summaries are usually enough, `explain_metric`/`explain_metric` if
+you need more). Then stop and wait — do not query, and do not answer
+"either way, here is one of them". Example, using the VAT pair above:
+
+> "`total_event_revenue_ex_vat` or `total_event_revenue_inc_vat`? The
+> first is net; the second includes 25% VAT."
+
+A list of every candidate is not a question; two or three, named, with the
+difference stated, is — and the names must come from the catalog you just
+read, never from this document.
+
+This is a different move from declaring a gap (§8): a gap means the
+semantic layer *cannot* answer, ambiguity means it can answer in several
+ways and only the user knows which.
+
+## 3. Read the description fields
+
+The `description` on each metric and dimension is **authoritative** — the
+source of truth for unit, computation, source rollup, filter rules, and
+caveats. Read it; do not paraphrase or infer the unit from the name.
+
+What it tells you:
+
+- **Unit** — DKK, count, %, hours. State it back explicitly in the answer.
+- **Source rollup** — which systems contribute; say so if the user asks
+  about one system and the metric rolls up several.
+- **Caveats** — temporal discontinuities, methodology changes, bug-fix
+  dates (see §6). A catalog row carrying a `caveat` sentence (§2) signals
+  this — quote it, don't answer from the index row alone.
+- **Standing filter rules** — "for B2B, pair with…". Apply unless the
+  user explicitly overrides.
+- **Derived-field pointers** — "use `event_segment`, not raw
+  `event_type`" (see §5).
+
+Byte-identical across MCP, CLI, and REST — authored once in dbt YAML,
+served everywhere.
+
+## 4. Apply standing filter rules from descriptions
+
+If a metric's description says "pair with `status='paid'` to exclude
+voided invoices", include that filter unless the user explicitly asks for
+the unfiltered view — the author wrote it because querying without it is a
+known footgun. **MCP** passes it through `query_metrics(filter=...)` where
+supported (else mention it in the answer); **CLI** (`dataspring query` has no
+ad-hoc filters yet) and **REST** (POST body) mention or include it the same
+way. Don't argue or substitute your own interpretation — the description is
+closer to the warehouse than you are.
+
+## 4.1 Echo the defaults that were applied for you
+
+The user's saved preferences are applied to the query before it runs — a
+standing filter, a default segment, a metric substitution. The response
+reports them as `applied_defaults`, each with an `echo_text` phrase
+(MCP: in the `query_metrics` response dict; CLI: printed with the
+result; REST: in the `POST /query` body). Say every one in the answer, beside the
+number it changed:
+
+> Reseller revenue: $94k (excluding direct billings — your default)
+
+A defaulted number is not the unqualified number, and the reader cannot
+see the query. An explicit request in this turn wins over a standing
+default and nothing is reported for it — say that too ("including direct
+billings this time, overriding your standing filter"). Omitting the echo
+is how a filtered figure gets quoted in a board deck as the total.
+
+## 5. Prefer derived dimensions when descriptions point that way
+
+Descriptions often steer you to a derived dimension over a raw one
+(`customer_segment` over `customer.tier`, `event_segment` over
+`event_type`) — the derived version layers business logic the raw field
+usually lacks or mismodels. Use the qualified name verbatim from the
+dimensions catalog (e.g. `pos_order_line__venue_name`, not `venue_name`) —
+the prefix names the owning semantic model.
+
+## 6. Honor temporal discontinuities
+
+When a description warns "pre-X date is unreliable" or "ETL bug fixed Y
+date", segment your query and tell the user about the discontinuity.
+Example: "pre-2024-04-01 numbers exclude refunds; ETL bug fixed
+2024-04-15" plus a year-over-year ask across that boundary means running
+two queries (before/after) and calling out the methodology change rather
+than silently quoting one misleading trend. Same rule regardless of
+surface — same warehouse, same boundaries.
+
+## 7. Insights, not just data
+
+Don't just return raw query results. Interpret what the number
+means in the org's business context.
+
+| Bad | Good |
+|-----|------|
+| "Revenue: 2.1M DKK" | "Revenue hit 2.1M DKK in January, up 12% YoY. Lunch drove most of the growth while events dipped seasonally." |
+| "NPS: 48" | "NPS at 48 (strong). Food scores highest (4.2/5) while atmosphere lags (3.8/5). Summer months consistently outperform winter." |
+
+Always contextualize with all THREE of these. They are DIFFERENT
+things, and a good answer that does two of them is still missing one:
+
+1. **Comparison** — the figure next to another figure: YoY, MoM, vs a
+   trailing average, vs another period or segment. A direction word
+   alone ("up", "strong") is not one; there must be something it is up
+   against.
+2. **Relative size** — the figure sized against a WHOLE: a share or
+   percent of a total, a rate, a per-unit figure, or a breakdown of the
+   parts. Note what this is NOT: "up 4.4% month over month" is a
+   comparison, not a relative size. A percentage CHANGE measures the
+   same number against its own past; sizing measures it against
+   something else — a total, a denominator, its own components.
+3. **Business implication** — a driver, a risk, a data-quality caveat
+   that blocks a decision, or a next step. Restating the trend in words
+   ("growth moderated") is NOT an implication; it has to say what the
+   number means for the reader.
+
+**A question whose literal answer is one number is exactly the case
+this rule is for, not an exception to it.** Shipping "Total revenue
+last month was 3,525,734.18" is literally correct and still a failure:
+you already have the query, one more window is one more call, and a
+breakdown you already fetched costs nothing but arithmetic.
+
+**But context is built from the metric you were asked about, not from
+extra ones.** Widen the WINDOW of the metric the question names, or
+break it down by a dimension it already has — do not go and fetch
+neighbouring metrics to manufacture a story. Asked for one metric,
+answer with THAT metric over two periods; do not also pull the two
+related ones because they would make the paragraph richer. That reads as
+not knowing which metric the question was about, it is the single
+commonest way to turn a 3-call turn into a 6-call one, and the extra
+metrics are exactly the near-misses you are supposed to avoid.
+
+And when the figure is already in the conversation, the context is
+too: answer from it. Do not spend a call re-reading your own previous
+query to remember what you asked.
+
+## 8. Declare the gap when the semantic layer can't answer
+
+If a question requires a metric, dimension, or join that doesn't exist in
+the catalog, say so explicitly before doing anything else — don't run a
+query against the closest-named metric and report a misleading number,
+and don't improvise a raw-SQL query around the gap: query generation stops
+at the semantic layer and never falls back to hand-written SQL.
+
+State the gap in this form, verbatim:
+
+```
+SEMANTIC LAYER GAP: [reason]
+Falling back because: [specific missing metric/dimension/join]
+```
+
+Then offer the checklist:
+
+```
+Would you like me to add this to the semantic layer? I can propose:
+- [ ] New metric: `metric_name`
+- [ ] New dimension: `dimension_name`
+- [ ] New semantic model for `entity_name`
+```
+
+That checklist is for a gap you cannot compute around. When you CAN compute
+it — every ingredient is in the catalog — the branch below replaces the
+checklist: an admin is owed the definition itself, not a checkbox asking
+whether to write one.
+
+Valid reasons: the metric doesn't exist, a required dimension isn't
+exposed, the question needs a join across entities no semantic model
+connects, or it's ad-hoc exploration ahead of defining a metric.
+
+Say it exactly this way rather than paraphrasing — the fixed shape is
+what makes it easy to scan in a long conversation.
+
+**When the ingredients exist and only the metric is missing.**
+Sometimes every input is in the catalog and only the combination is
+absent — revenue per ticket, where both `total_revenue` and
+`tickets_created` exist and no ratio metric does. Being able to
+compute it does not make it defined. Declare it anyway, in this
+order:
+
+1. **Declare** — the verbatim block above, naming the missing metric.
+2. **Compute** — deliver the number as a labelled ephemeral
+   computation from rows you fetched (§8.1): say which metrics it was
+   computed from — **every** one of them, by name, not just the one the
+   unit happens to mention — and that it is not a defined metric. A rate
+   phrased as "34.4 per 1,000 usage events" names the denominator and
+   leaves the numerator unattributed: the reader cannot tell which metric
+   it was.
+3. **Offer the durable path** for this user's role — an admin gets a
+   concrete definition, reached by asking `metric_edit` for a `preview`
+   and quoting back the `dbt_yaml` it returns; a member or viewer gets a quick metric via
+   `quick_metric_edit`. For an admin this happens in the SAME turn and
+   without asking: a preview writes nothing, so it needs no permission, and
+   only `create` does. Offering to propose a definition is not proposing
+   one — the YAML has to be in the answer.
+
+Steps 1 and 2 are identical for every role. Only step 3 forks, and the
+fork has to be visible in the answer:
+
+| Role | Bad | Good |
+|---|---|---|
+| admin / owner | Opens "## Revenue per Support Ticket", shows a ratio table, offers to save it as a quick metric — or to propose a definition without showing one. No declaration, no YAML; the org still has no metric afterwards. | Opens with the verbatim gap block; gives the ratio computed from `total_revenue` and `tickets_created`, labelled ephemeral; then quotes the dbt YAML the delegated preview returned, in full, and asks whether to create it. |
+| member / viewer | The same ratio table, presented as a finished figure the org agreed on. | The same gap block and the same labelled ratio; then "I can save this as a personal quick metric — `qm:revenue_per_ticket` — queryable from now on." Nothing org-scoped is offered or attempted. |
+
+An admin answered the member's way is the exact failure this fork exists
+to end: the arithmetic is right and the semantic layer is unchanged.
+
+Do not silently divide two numbers in prose. An unlabelled quotient
+reads as a figure the org has agreed on, and it is not one — that
+substitution, not the arithmetic, is what this branch exists to end.
+
+## 8.1 Compute, persist, or declare
+
+A question that needs arithmetic over fetched rows — a growth rate, a
+ratio, a share, two queries blended into one number — is answered by
+fetching every ingredient with a metric query and computing from those rows
+yourself (or in your host's own code tool, if it has one). DataSpring does
+not run code for you.
+
+### Two rules worth knowing before your first query
+
+**Categorical dimension values are stored LOWER-CASED.** Write
+`= 'enterprise'`, not `= 'Enterprise'`. A wrong-cased literal matches
+nothing and returns zero rows with no error — you will get a `hint` naming
+the real values, but that costs a round trip you did not need to spend.
+When you are unsure of a value, the hint on an empty result is
+authoritative: use it rather than guessing again.
+
+**`order_by` takes `-field` for descending, not `field desc`.** Both are
+accepted now (the SQL suffix is translated for you), but write
+`-total_revenue` — and leave `order_by` out entirely on a single-row
+aggregate, where there is nothing to sort.
+
+Which rung a number belongs on:
+
+| The number is... | Path |
+|---|---|
+| One-off arithmetic over rows you fetched | compute it yourself: one metric query per ingredient (`query_metrics` / `dataspring query` / `POST /query`), then the arithmetic, then the attributed answer |
+| A derived number THIS user will want repeatedly | `quick_metric_edit` — persisted, and queried afterwards with the `qm:` prefix |
+| A durable metric the whole org should share | the admin path — `metric_edit` preview, then the `dbt_yaml` it returns |
+
+Three rules hold on every rung:
+
+- **A computed number is ephemeral and is never a defined metric.** It
+  is a number computed for this one answer; nothing was added to the
+  semantic layer, and nobody else can query it.
+- **Fetch every ingredient.** Run a metric query for each one; never reuse
+  a figure from prose, a dashboard title or an earlier turn as a literal —
+  a hardcoded input can't be reproduced from what was actually queried.
+- **Attribute every computed number in the answer, however it was computed.**
+  Name the metrics it came from — `total_revenue`, `tickets_created`, not a
+  prose label a table happened to use for them ("Total Sales", "New
+  Tickets") — and say what it is not — "computed from `total_revenue` and
+  `tickets_created`; not a defined metric".
+- **Raw SQL never, on any path.** Rows come from a metric query. There is
+  no second way.
+
+When the query response carries `applied_defaults` (or `notes`, or `hint`),
+carry it into the answer beside the number (§4.1): a defaulted figure quoted
+as the unqualified one is the mistake this section exists to prevent.
+
+## 9. When to update the semantic layer
+
+Declaring a gap (§8) doesn't by itself mean the semantic layer
+needs a change. After the gap is declared, judge whether the
+question represents a reusable business need:
+
+| Situation | Action |
+|-----------|--------|
+| One-off exploration | No update needed |
+| Recurring metric need | Create a metric |
+| Missing dimension | Add it to the relevant semantic model |
+| New entity relationship | Consider a new semantic model |
+
+Separate from *where a fact belongs once captured*: one metric/dimension/
+entity fact goes in that object's `description` in the dbt YAML;
+a cross-cutting organisation fact goes in `business_context`. This table
+answers *whether it's worth capturing*; that rule answers *which document*.
+
+Propose the change via `metric_edit` / `semantic_model_edit` (MCP), `dataspring metrics create` /
+`dataspring models create` (CLI), or the equivalent admin REST routes —
+admin/owner only. Show it first (§8): a `preview` compiles the definition
+and writes nothing, so it needs no consent. What needs the user's yes is
+`create`; never make that change unilaterally.
+
+*How* to make that proposal — surface ownership, the member alternative,
+when it needs a dbt YAML snippet instead of a write, and undo — is the
+`dataspring-correct` skill (`GET /api/v1/skill/correct/instructions`); this
+section only decides whether the change is worth making.
+
+## 10. Refuse hopeless queries honestly
+
+If a question requires data the catalog doesn't expose, or the
+`business_context` warns the relevant system isn't synced, say so.
+Don't run a query against the closest-named metric and report a
+misleading number.
+
+Examples of honest refusals:
+
+- "I can't answer how many emails went out — `business_context`
+  notes the org doesn't sync staff mailboxes."
+- "I can't answer attribution by paid-search keyword — there's no
+  metric or dimension in the catalog that captures search keyword."
+
+## 11. Tool / response error recovery
+
+Errors come back with a `code` and a `suggestion` (canonical name; older
+paths still expose `hint` as an alias). Follow the suggestion.
+
+Codes you'll see:
+
+- `METRIC_NOT_FOUND` / `QUICK_METRIC_NOT_FOUND` — suggestion lists
+  available names. Don't retry with the same name; pick from the
+  suggestion or ask the user.
+- `NO_DATA` — exists, but the date range / filter combination returned
+  nothing. Tell the user; don't fabricate a zero.
+- `NO_BASE_METRICS` — quick metric expression has no dependencies to
+  resolve. Almost always a config bug; surface it.
+- `EXCEEDS_INSTRUCTIONS_CAP` — `business_context_edit` write over the
+  2000-byte UTF-8 cap. The error includes `current_bytes`/`cap_bytes`;
+  trim the content, don't loop.
+
+A qualified-dimension complaint (e.g. `venue_name` rejected, expecting
+`pos_order_line__venue_name`) — retry with the qualified name once, don't
+loop on the same error.
+
+**Recovery is YOUR business, never the reader's.** Once you have recovered,
+answer as if the failed attempt never happened. The reader asked a
+question about their business; they did not ask what your tool calls did.
+Never open an answer with, or otherwise mention:
+
+- "The validation error was caused by an invalid request payload…"
+- "The query is now valid."
+- "I retried with valid structured arguments."
+- "No additional write was needed — it already contains…"
+
+Each of those is a real answer this agent has shipped, and each one
+replaced the sentence the reader actually needed. If you could not
+recover, say what you could not find out and what you would need — that
+is about THEM. If you did recover, just answer.
+
+Surface shape: **MCP** returns `{error, code, suggestion}` in the tool
+response (`hint` mirrors `suggestion` for back-compat); **CLI** prints
+"✗ Error: …" with a hint line, exit code 1; **REST** is HTTP 4xx/5xx with
+`{"detail": {"message", "code", "suggestion", ...}}`.
+
+## 12. Multi-turn / multi-call efficiency
+
+After the catalog is loaded once:
+
+- Drilldowns ("show me the same broken down by region") go
+  straight to the query call. No re-discovery needed.
+- Comparison questions ("how does this compare to last year?")
+  are a second query call with adjusted dates.
+- Refinements ("can you exclude internal accounts?") add a
+  filter; respect any standing rules from the metric description
+  on top of the user's ad-hoc filter.
+
+**If the figure is already in this conversation, answer from it.** A
+follow-up like "which of those days was weakest?" is arithmetic over rows
+you already fetched and printed — re-running the same query to re-read
+your own table costs a round trip and risks answering from a different
+result than the one the user is looking at. Query again only when the
+question needs data you have not got: a new metric, a new window, a new
+breakdown.
+
+The catalog is only stale if the user pivots to a brand-new
+analytical area; in that case, re-list.
+
+## 13. The org's `business_context` document
+
+Cross-cutting org orientation lives in `business_context` — what
+the org sells, what's synced, what's NOT synced, cross-cutting
+derivation rules. Hard cap: 2000 UTF-8 bytes.
+
+How it reaches you:
+
+- **CLI**: `dataspring business-context get` prints it.
+  `dataspring business-context size` shows the byte budget.
+- **REST**: `GET /api/context` returns `{"content": "..."}`.
+
+Treat `business_context` as part of the same authoritative layer
+as metric descriptions. Same provenance (dbt repo via the
+manifest workflow), same trust level.
+
+That's the working agreement. Same principles, three surfaces —
+do this and the answers will be right.
+
+## 14. Parameter reference
+
+<!-- dispatch-params: query_metrics explain_query run_sql update_context quick_metric_edit learned_edit verified_query_edit business_context_edit -->
+_Generated from the dispatch registry (`GET /api/dispatch`); do not edit by hand. Field descriptions are the models' own, verbatim on every surface._
+
+#### `query_metrics`
+
+MCP tool `query_metrics`; `POST /api/dispatch/query_metrics`. Fetch metric data from the warehouse.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `metrics` | list of string | yes | List of metric names to query (e.g., ['total_revenue', 'order_count']) |
+| `dimensions` | list of string | no | Dimensions to group by. Use qualified names from dataspring://dimensions (e.g., ['customer__segment', 'order__region']) |
+| `grain` | string | no | Time granularity: 'day', 'week', 'month', 'quarter', or 'year' |
+| `start_date` | string | no | Start date in YYYY-MM-DD format |
+| `end_date` | string | no | End date in YYYY-MM-DD format |
+| `limit` | integer | no | Maximum number of rows to return |
+| `order_by` | string | no | Column to sort by, append ' desc' for descending (e.g., 'total_revenue desc') |
+| `where` | list of string | no | Row filters in MetricFlow's constraint syntax, one string each, e.g. "{{ Dimension('customer__segment') }} NOT IN ('Direct')". Use qualified names from dataspring://dimensions - an unresolvable name comes back as an error whose suggestion names the qualified form. `where` decides WHICH ROWS the numbers cover; `dimensions` breaks the numbers OUT by a column; send both for a breakdown of a filtered slice. A `where` on a dimension also overrides the user's standing filter on that same dimension for this call. |
+| `warehouse` | string | no | Which of the org's warehouses to run against - an id from dataspring://warehouses ('managed', 'external', ...). Omit for the active one. During a migration ask both and compare. |
+| `suggest_visualization` | boolean | no, default `False` | Also return a suggested visualization type for the result. |
+| `format` | one of `json`, `csv` | no, default `json` | 'json' (default) answers rows in `data`; 'csv' answers the same result as one CSV document in `content` (header row first) for a file or a spreadsheet, with `columns` and `row_count` alongside. |
+
+#### `explain_query`
+
+MCP tool `explain_query`; `POST /api/dispatch/explain_query`. Show what a query computes without running it: the resolved metrics and dimensions, the effective time window, the filters (including any standing preference folded in) and the compiled SQL. Use it when the user asks what you actually computed, disputes a number, or before proposing a correction. ``warehouse`` picks one of the org's warehouses; omit it for the active one.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `metrics` | list of string | yes | List of metric names to query (e.g., ['total_revenue', 'order_count']) |
+| `dimensions` | list of string | no | Dimensions to group by. Use qualified names from dataspring://dimensions (e.g., ['customer__segment', 'order__region']) |
+| `grain` | string | no | Time granularity: 'day', 'week', 'month', 'quarter', or 'year' |
+| `start_date` | string | no | Start date in YYYY-MM-DD format |
+| `end_date` | string | no | End date in YYYY-MM-DD format |
+| `limit` | integer | no | Maximum number of rows to return |
+| `order_by` | string | no | Column to sort by, append ' desc' for descending (e.g., 'total_revenue desc') |
+| `where` | list of string | no | Row filters in MetricFlow's constraint syntax, one string each, e.g. "{{ Dimension('customer__segment') }} NOT IN ('Direct')". Use qualified names from dataspring://dimensions - an unresolvable name comes back as an error whose suggestion names the qualified form. `where` decides WHICH ROWS the numbers cover; `dimensions` breaks the numbers OUT by a column; send both for a breakdown of a filtered slice. A `where` on a dimension also overrides the user's standing filter on that same dimension for this call. |
+| `warehouse` | string | no | Which of the org's warehouses to run against - an id from dataspring://warehouses ('managed', 'external', ...). Omit for the active one. During a migration ask both and compare. |
+
+#### `run_sql`
+
+MCP tool `run_sql`; `POST /api/dispatch/run_sql`. Run ONE read-only SQL statement against the org's warehouse and get the rows back, ungoverned.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `sql` | string | yes | One SQL statement (BigQuery Standard SQL on a managed warehouse). Name tables as <org>_marts.<table>, <org>_core.<table> or <org>_staging.<table>; the identity it runs as can read those and nothing else, so a write or a reach outside them is refused by the warehouse. |
+| `warehouse` | string | no | One of the org's warehouses (see dataspring://warehouses); omit for the active one. |
+| `max_rows` | integer | no, default `1000` | Rows to return at most (default 1000, cap 10000). Aggregate in SQL rather than paging. |
+| `format` | one of `json`, `csv`, `markdown` | no, default `json` | 'json' answers rows in `data`; 'csv' or 'markdown' answer one document in `content`. |
+| `dry_run` | boolean | no, default `False` | Only estimate the bytes the statement would process (and check it parses); run nothing. |
+
+#### `update_context`
+
+MCP tool `update_context`; `POST /api/dispatch/update_context`. Update user preferences (merge, not replace).
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `updates` | object | yes | Fields to update; only these change. Presentation: default_currency, default_grain, decimal_places, preferred_chart_type. Lists and maps REPLACE what is stored: favorite_metrics, standing_filters ([{dimension, operator: in\|not_in\|eq\|neq, values}]), metric_substitutions ({asked: preferred}), default_segment ({dimension, value} or null). |
+
+#### `quick_metric_edit`
+
+MCP tool `quick_metric_edit`; `POST /api/dispatch/quick_metric_edit`. Edit user-defined quick metrics (arithmetic expressions over existing metrics). The body is `{"action": {"action": "<verb>", ...}}`, one verb per table below.
+
+**`create`** — 
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `name` | string | yes | Metric name (e.g., "revenue_per_order") |
+| `expression` | string | yes | Arithmetic expression over existing metrics (e.g., "total_revenue / order_count") |
+| `description` | string | no |  |
+
+**`update`** — 
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `metric_id` | string | yes |  |
+| `name` | string | no |  |
+| `expression` | string | no |  |
+| `description` | string | no |  |
+
+**`delete`** — 
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `metric_id` | string | yes |  |
+
+#### `learned_edit`
+
+MCP tool `learned_edit`; `POST /api/dispatch/learned_edit`. Browse and undo the learned trail — what DataSpring learned for this org. The body is `{"action": {"action": "<verb>", ...}}`, one verb per table below.
+
+**`list`** — List what DataSpring learned for this org (plus your personal entries).
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `limit` | integer | no, default `20` |  |
+| `include_reverted` | boolean | no, default `False` |  |
+
+**`undo`** — Revert one learning (or, with no id, your most recent reversible one).
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `learning_id` | string | no | Learning to revert; omit for your most recent reversible entry |
+
+#### `verified_query_edit`
+
+MCP tool `verified_query_edit`; `POST /api/dispatch/verified_query_edit`. Curate verified queries — confirmed (question, query) pairs. The body is `{"action": {"action": "<verb>", ...}}`, one verb per table below.
+
+**`list`** — The org's verified queries plus your own personal ones.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `limit` | integer | no, default `20` |  |
+
+**`record`** — Record one confirmed (question, query) pair.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `question` | string | yes | The user's question, verbatim |
+| `params` | object | yes | The query that answers it, in the query_metrics wire shape: metrics, dimensions, grain, start_date, end_date, where, order_by, limit |
+| `note` | string | no | One line on WHY this is the right query for that question |
+| `scope` | one of `org`, `user` | no, default `user` | 'user' (the default) records it in this user's personal set; 'org' curates it for everyone and requires admin/owner |
+
+**`delete`** — Remove one verified query by id.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `id` | string | yes |  |
+
+#### `business_context_edit`
+
+MCP tool `business_context_edit`; `POST /api/dispatch/business_context_edit`. Edit the org's cross-cutting business_context document. The body is `{"action": {"action": "<verb>", ...}}`, one verb per table below.
+
+**`get`** — Read the current org business_context document.
+
+No parameters.
+
+**`show_size`** — Report current size and remaining room within the 2000-byte UTF-8 cap.
+
+No parameters.
+
+**`set`** — Replace the org's business_context with ``content`` (admin/owner).
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `content` | string | yes | Full document content to save |
+
+**`append`** — Append ``content`` to the existing business_context (admin/owner).
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `content` | string | yes | Text to append to the current document |
+<!-- /dispatch-params -->