allium-labs Allium Investigation
Use this for a scoped investigation, not for a current price or balance lookup. Its output is a conclusion that another person can inspect, rerun, and challenge.
Use the Allium MCP tools directly — run_sql_query, get_query_run_results,
create_explorer_query, search_terminal, get_terminal_results, search_schemas,
search_docs — rather than describing what a query would show. If the MCP isn't
available, fall back to the allium-data skill / CLI.
Output contract
Start by stating the decision question, subject, time window, networks, and proposed metric. If any of these would materially change the answer, ask before querying.
End with the answer and the evidence that directly supports it, plus clearly marked interpretation and open uncertainty. If the result will be shared, reused, or is decision-relevant, finish with step 7 below — saving the load-bearing queries to Explorer — rather than leaving the evidence only in the chat transcript.
Investigation workflow
1. Check Terminal before investigating from scratch
Someone on the Allium team may have already built and maintained the answer. Call
search_terminal with the entity/metric/protocol before writing any SQL — it's a
metadata-only search (dashboard label, path, category, tags), no compute cost. If a
dashboard looks relevant, call get_terminal_results with its dashboard_id (no
chart_id) to see the chart manifest, then again with a chart_id to pull its SQL
and/or latest precomputed rows — this also costs no compute units, since it only reads
existing definitions and results. If it directly answers the question, cite it (with
result.queried_at for the precomputed rows) and link the dashboard instead of
re-deriving the same thing from raw tables. If it's close but not exact, it's still a
faster starting point than a blank investigation — adapt its SQL rather than starting
over.
2. Select the source before committing to a method
Run data-matching next if a Terminal dashboard didn't already answer the question — it
defines the data contract, compares candidate tables/endpoints against it, and proves
coverage with a bounded query via search_schemas/search_docs. Don't guess a table name
or infer coverage from a chain merely being listed; a catalog entry alone is not coverage.
Once a source is selected, identify the native network and distinguish it from bridged or
wrapped representations before proceeding.
3. Write a data plan
Before the main query, record:
- the metric definition and denominator;
- inclusion, exclusion, and entity-attribution rules;
- time grain and timezone;
- the checks that could falsify the intended interpretation.
Treat this as a hypothesis. Revise it when the discovered schema or first result disagrees.
4. Build from a small test to a production query
For the narrow-sample/cardinality/units check, use run_sql_query — it's explicitly
ephemeral (not saved, can't back a chart or dashboard), which is exactly right for a
throwaway check. It returns a run_id immediately; call get_query_run_results with that
run_id to get status, columns, row count, and cost (pass poll_timeout_seconds if it's
still running). If the run failed, errored, or came back with zero rows, fix the SQL and
re-run — don't report an empty or failed run as the answer unless zero rows genuinely is
the answer to the question asked.
Once the small test looks right and you're about to run the query whose result you'll
actually use, switch to create_explorer_query (with run_on_creation=True) instead of
running it through run_sql_query first — re-running an already-validated query through
run_sql_query and saving it afterward duplicates the compute. This also means the
production query is already a saved Explorer query by the time you reach step 7.
Use Realtime data for current state of a known asset or wallet. Use Explorer/SQL for historical, comparative, aggregated, or cross-chain questions. Do not mix their freshness semantics into one unlabeled metric.
5. Validate the result
Apply the checks that fit the method:
- reconcile a total with its components;
- check joins for duplicate multiplication and verify
COUNT(DISTINCT ...)at the intended grain; - confirm token units, decimals, USD conversions, and the denominator;
- compare adjacent periods and investigate discontinuities rather than smoothing them;
- independently re-query at least one load-bearing figure from a different aggregation, filter, or sample.
Do not treat agreement with an external aggregator as proof. It can be a sanity check, but the published claim needs its own method and source trail.
6. Make calibrated claims
Separate three kinds of statements:
- Observed: what the query directly shows.
- Interpretation: a plausible explanation, labelled as such and tied to supporting evidence.
- Unknown: what the available data cannot establish.
Do not turn correlation into causation, a labelled address into a verified controller, or a sample into a population without evidence.
7. Make it reproducible in Explorer
A conclusion that only exists in the chat transcript isn't reproducible — anyone revisiting
it has to retype the SQL from memory. By step 4 your load-bearing query should already be
saved via create_explorer_query; if it isn't yet, save it now rather than leaving it as
an unsaved run_sql_query result.
Single result — if the investigation produced one load-bearing query, that's usually
enough on its own: optionally call create_explorer_visual on it (chart/value/table — pick
the type that fits the data) and share_explorer_query to hand back a link. Skip the rest
of this step.
Multiple results meant to become a dashboard — the Allium Assistant in the app builds dashboards, but it cannot write SQL in dashboard mode; it only assembles saved queries it's told about. There's no MCP tool to assemble a multi-query dashboard directly, so the hand-off is a prompt the user pastes into Assistant. After saving each query, print one:
Build me a dashboard.
Title: <short title>
Goal: <one sentence — what should this dashboard show?>
Queries:
- <query_id>: <one-line description>. Cols: <col> (stock→last), <col> (flow→sum), ...
- <query_id>: <one-line description>. Cols: ...
Filters: <optional, one line>
Elements: <optional, one line — e.g. "KPI: total_x (last); chart: y over time by chain">
The two things that must never be dropped are the query IDs and each column's
stock/flow tag — a stock metric (supply, balance, TVL, price: aggregate last/first)
summed like a flow metric (volume, count, fees: aggregate sum) is the most common real
dashboard bug, and Assistant can't infer it from the column name alone. If the prompt is
running long, cut Filters/Elements/Goal down to a phrase before cutting a query or a
stock/flow tag. Keep the whole thing well under 800 characters — short enough that someone
can glance at it, copy it, and paste it straight into Assistant without editing.