Semantic Rails

Capabilities

Semantic Rails MCP question-answering entrypoint. For answering governed-data questions, use: discover, plan, validate, compile, execute. Use catalog for orientation. Return the package's supported and unsupported capability surface — rolling windows, prior-period offsets, metric predicates, scoped aggregates, conversion metrics, etc. Recommended loop position: 0 (cold-start orientation). Costs ~10KB; tells you which IR expression kinds the runtime can compile and execute for this package. Gotch

Catalog

List every governed semantic object in the active package — measures, metrics, dimensions, segments, entities. Recommended loop position: 1 (after capabilities, before discover). Prefer 'discover' for term-targeted lookups. Gotcha: default verbosity is 'summary' — flat ID lists (~22KB), right for orientation. Bump to 'compact' for row metadata (capped 200/kind) or 'full' for uncapped + alias_index (large).

Discover

Rank semantic objects against business terms (e.g. 'revenue', 'aov by store'). Returns measures, metrics, dimensions, and entities scored with 'match_reasons'. Recommended loop position: 1 (after the user's question). Pick best id, then 'inspect'. Verbosity: 'minimal' trims each row to {id,kind,score,default_temporal_role,available,match_reasons} (cheap orientation); 'compact' (default) ships full cards. Gotcha: nonsense or out-of-scope terms return an 'out_of_scope' or 'low_relevance' block wit

Inspect

Return the stable object card for one id — label, description, search terms, related dimensions, valid temporal roles, policy/validity windows. Recommended loop position: 2 (after 'discover', before composing Query IR). Gotcha: 'object_id' must be a full id like 'measure.jaffle.revenue_usd', not a label — use 'discover' first if you only have a phrase.

Build Options

Return ranked next choices for a guided query builder — given partial Query IR, what dimension/filter/time-range to add next. Recommended loop position: 2.5 (between 'inspect' and 'plan' when composing step-by-step instead of from a single intent). Gotcha: pass the partial 'query' you've assembled — empty input returns initial-stage options.

Valid Values

Return governed valid values for one dimension — from its declared value_domain by default, or via a constrained warehouse probe when 'allow_live_query: true'. Recommended loop position: 3 (composing a 'where' filter on a categorical dimension). Gotcha: 'dimension_id' must be a full id like 'dimension.jaffle.store_name'. Set allow_live_query: true only when no declared domain exists — it costs a warehouse round-trip.

Plan

Single public intent-planning surface: natural-language intent → one best Query IR plus optional alternatives. Use detail='query' for the tight QA loop before execute(row_format='columns'). Returns 'status' ('ok' | 'low_confidence' | 'unrealizable' | 'out_of_scope') and 'best.query_ir'. 'status=ok' has already paid validation cost, so agents may proceed to 'compile' or 'execute' with 'best.query_ir'. Use detail='full' for alternatives/blocked drafts, or detail='debug' for compose_hints. Gotcha:

Validate

Check Query IR before compiling — returns errors, warnings, and repair hints. Loop position: 5 (before 'compile' or 'execute'). Gotcha: 'query' must be a JSON object, not a stringified blob; wrap as {query: {...}}. Defaults to verbosity='minimal' — pass verbosity=compact|full for normalized query/policy effects/plans. IR: select[]={expression,as}, group_by[]=[<dim>,...] (bare ids), where[]={field,op,value}, order_by[]={field,direction}. select.expression: {aggregation, measure} | {metric} | {kin

Compile

Compile validated Query IR into rendered SQL — no warehouse execution. Loop position: 6 (after 'validate', before 'execute'). Gotcha: do not call before validate — compile raises on errors; validate returns structured repair hints. Defaults to verbosity='minimal' (keeps rendered_sql) — pass verbosity=compact|full for sql_plan/explain/logical plans. IR shape: see the 'validate' tool or 'build-options'.

Execute

Execute Query IR against the warehouse and return rows (compiles + runs in one call). Loop position: 7 (final — only after validate + compile succeed). Gotcha: only tool that costs warehouse credits + round-trip latency; side-effecting. Use 'compile' for SQL only. Defaults to verbosity='minimal' (rows + row_count) — pass verbosity=compact|full for SQL/plans/explain. Use row_format='columns' for compact answers. IR shape: see the 'validate' tool or 'build-options'.

Segment Validate

Validate a package-authored segment and the Query IR derived from it. Recommended loop position: 5 (segment workflow analogue of 'validate' for ad-hoc IR). Gotcha: 'segment_id' must be a full id like 'segment.jaffle.high_value_customers' — list known segments via 'catalog' if you only have a label.

Segment Explain

Explain the derived query for a package-authored segment — filters, joins, and time bounds it compiles to. Recommended loop position: 6 (after 'segment-validate', before previewing rows). Gotcha: governed segments only — for ad-hoc cohorts, compose Query IR with a 'where' clause and call 'compile' to read the explain payload on its response.

Segment Preview

Preview members of a package-authored segment — sample rows plus total member count. Hits the warehouse. Recommended loop position: 7 (segment analogue of 'execute' — final step). Gotcha: only segment tool that costs warehouse credits. Run segment-validate + segment-explain first; preview is for showing rows to the user.