OWOX Data Marts

Use when you need the columns a saved report's rows will carry, in the order they are projected — the names to put above the values the report delivers. Includes the columns a report synthesises (aggregated `revenue | SUM`, Unique Count, calculated fields), which appear in no data mart schema. Answers from the stored schema and the report config, so it reads no report data — the columns are as of the Data Mart's last schema actualization, so one added warehouse-side and not yet actualized is missing until a run or a data read picks it up. This tool reads stored metadata only: it does not query report rows or refresh SQL views in the warehouse.

get_report_output_schema

Get the current status of a report run, identified by report_id and run_id. The run_id may come from run_report or from add_report when initial_run.status is "queued". Report runs routinely take several minutes, so keep polling while should_poll is true and stop when should_poll is false; terminal statuses are "success", "failed", "cancelled", "interrupted", and "restricted". If you can wait between tool calls, poll about every 15 seconds; otherwise call again immediately. The message field tells you what to do next, including when to warn that a run is taking longer than usual and when to treat it as stuck and stop polling. stop_reason is set only when status is still "running" but should_poll is false, such as queued_too_long or running_too_long. queued_at is when the run was created; started_at is null until execution starts, including the brief worker-claimed state before the start time is recorded. raw_status exposes the backend status, and error is populated only for failed runs.

get_report_run_status

List data marts available to the current OWOX project member. Defaults to published data marts; use status=draft only to browse draft metadata, because other MCP data-mart tools accept published data marts only. Use only when the user explicitly asks to list or browse data marts; for a concrete analytical question use get_relevant_data_marts_by_prompt instead, and for open-ended orientation use summarize_data_catalog. Use get_project_context → list_contexts to discover business goals, then pass context_ids to restrict discovery to any selected context; omission preserves project-wide discovery within your existing access. Responses include all attached context IDs and names.

list_data_marts

List destinations in the active OWOX project to target when creating a report. Also the only way to learn the destination_id and connected Google account for a google_sheets destination just created via add_destination, since that call does not return an id synchronously — see its description. When matching that destination, never pick by createdAt/recency — someone else may create a destination at the same time, so the newest entry is not reliably the right one. Filter by connectedGoogleAccount matching who the user expected instead; if exactly one entry matches, use it, and if more than one still matches, ask the user which one they mean rather than guessing. Destinations created via add_destination start unshared: the creator can use them in their own reports right away, but other project members cannot until a human shares them (Configure destination → Sharing) — this tool does not report sharing status, so if the report is for someone other than the destination's creator, confirm with the user that it has been shared rather than assuming it.

list_destinations

List business contexts in the connected OWOX project, including IDs, names and complete descriptions (null when missing). Discovery flow: get_project_context → list_contexts → list_data_marts or get_relevant_data_marts_by_prompt with context_ids → get_data_mart_details_by_id. Read descriptions for business goals and Markdown links to specific Data Marts. Listing a context or following a reference never grants access to its resources; all Data Mart tools enforce existing access controls.

list_contexts

Lists every scheduled REPORT_RUN trigger (report run schedule) in the current OWOX project that the current MCP user can see, in a single response. Each item includes trigger_id — pass it to update_report_run_schedule to modify that specific schedule or delete_report_run_schedule to remove it — plus the report and data mart it belongs to. To add another schedule for a report, call create_report_run_schedule; creating never replaces existing schedules.

list_report_run_schedules

Query an OWOX data mart and return its data rows in a compact, header-once table, plus server-side totals computed over all matching rows (ignoring the row limit). Each call costs credits, records a run, and may replace an OWOX-managed technical view when the Data Mart has a SQL definition. Call get_data_mart_details_by_id first to get the data mart's exact field names and joinable/blended fields, then copy field names verbatim into fields — unless you already have that schema in context. Field names must be exact; never guess or invent them. When building the query: - Request only the fields relevant to the user's question — never request all fields. - Use limit to control how many rows come back (1–1000, default 20). There is no offset/pagination: the tool returns a bounded subset. - aggregations: SUM, COUNT, COUNT_DISTINCT, AVG, MIN, MAX, and percentiles P25/P50/P75/P95 — which of them a given field allows depends on the field's type and the data mart's per-field settings (see the matrix below). Group-by is implied by the non-aggregated fields you select. - Prefer a metric the data mart already defines: when get_data_mart_details_by_id shows a field whose "calculated" level is "metric", that field IS the quantity, computed at the grain your query asks for — list it in "fields" and read the value. Do not rebuild it by aggregating its inputs and dividing them yourself; on such a field an empty allowedAggregations means "already computed", never "unusable". - For “how many” questions, use COUNT or COUNT_DISTINCT (when the business meaning is unique entities) instead of returning raw rows and counting them yourself. Keep only dimensions the user asked to break the count by. - date_buckets: bucket a date/timestamp field by DAY/WEEK/MONTH/QUARTER/YEAR (e.g. "revenue by month"). Only date-category fields can be bucketed; time_zone applies only to types with a time-of-day component (TIMESTAMP/DATETIME — not pure DATE), and never to a Calculated Field, whose bucket must be requested without one. Which operators and aggregations fit which field type (using each field's "type" from get_data_mart_details_by_id): - number (INTEGER, FLOAT, NUMERIC, …): operators eq, neq, in, not_in, gt, gte, lt, lte, between, is_blank, is_not_blank; aggregations SUM, AVG, MIN, MAX by default; P25, P50, P75, P95 only where enabled on the field - string (STRING, VARCHAR, TEXT, …): operators eq, neq, contains, not_contains, starts_with, ends_with, in, not_in, is_blank, is_not_blank; aggregations COUNT, COUNT_DISTINCT by default; MIN, MAX only where enabled on the field - date (DATE, DATETIME, TIMESTAMP, …): operators eq, neq, in, not_in, gt, gte, lt, lte, between, is_blank, is_not_blank, before, after, in_last_n_days, in_next_n_days, this_week, last_week, this_month, this_quarter, last_quarter, this_year; aggregations MIN, MAX by default; COUNT, COUNT_DISTINCT only where enabled on the field - time (TIME): operators eq, neq, in, not_in, gt, gte, lt, lte, between, is_blank, is_not_blank, before, after; aggregations MIN, MAX by default; COUNT, COUNT_DISTINCT only where enabled on the field - boolean (BOOLEAN): operators eq, neq, is_blank, is_not_blank (eq/neq take a boolean true or false, not a string); aggregations COUNT, COUNT_DISTINCT - other (JSON, STRUCT, GEOGRAPHY, …): operators is_blank, is_not_blank; aggregations COUNT - Arrays are column-only: when a field's mode is REPEATED or its type or sliceType is ARRAY (including parameterized ARRAY types), it may appear in fields, but never in filters, slices, sort, aggregations, or date_buckets. This overrides all category rules above, including COUNT, ANY_VALUE and blank checks. A data mart can narrow a field's aggregations further ("only where enabled on the field") — get_data_mart_details_by_id returns each field's effective allowedAggregations; trust that over this table. Note COUNT/COUNT_DISTINCT are NOT available on number fields — to count rows per group, apply COUNT to a non-number field you already select that is always filled (an id field works well; COUNT skips NULLs, so a nullable field undercounts). To count UNIQUE records of a JOINED data mart (e.g. "how many distinct orders per customer"), do not aggregate its id column — instead select that source's own Unique Count field like any other field; get_data_mart_details_by_id (with_joined_fields) lists it among that source's joined fields whenever one is available. Copy its "name" (e.g. "orders__unique_count"), never its human-readable "displayName". It can be selected in "fields" and ordered by in "sort" (using that same exact name), but it cannot be used in filters, slices, aggregations, or date_buckets. - sort: order the result rows by { field, direction } with direction "asc" or "desc"; rules apply in order (the first is the primary key). Each sorted field must also be listed in fields. - fields must list every column the query uses, INCLUDING any field named in aggregations, date_buckets, or sort — a field you aggregate, bucket, or sort but omit from fields is rejected. Example — "revenue by month": fields ["ts", "revenue"], aggregations [{field: "revenue", function: "SUM"}], date_buckets [{field: "ts", unit: "MONTH"}]. (Filters are the exception: a filter may reference a field that is not in fields.) Choosing between slices and filters (both are row-level predicates applied to raw values BEFORE any aggregation, so neither can threshold a total you asked for via "aggregations" — the one exception is a Calculated Field whose level is "metric", whose formula is already aggregated and whose filter therefore compares the aggregated value): - slices (pre-join): narrow a JOINED data mart before it is blended in — criteria on a joined data mart's own fields only. Slices do NOT apply to the main data mart. More efficient — they reduce the joined volume before the join. A slice runs on the field's ORIGINAL value, so when get_data_mart_details lists a "sliceType" for the field, use operators valid for that pre-join type (not the field's blended-result "type"). - filters (post-join): row-level criteria on the blended result — use for anything on the MAIN data mart's fields or on a joined field. A filter on a field you also aggregate restricts which raw rows feed the aggregate (e.g. filter revenue > 0 → SUM over positive rows), NOT the group total. - Rule: pre-narrowing a joined data mart's rows → slices; any other raw-row criterion → filters. - Filtering by a total you asked for via "aggregations" (e.g. "groups whose SUM(revenue) > 100") is NOT supported — return all groups with their totals and let the caller compare. If the data mart already defines that quantity as a Calculated Field with level "metric", filter on THAT field instead and the threshold is applied to the aggregated value; list it in "fields" when you do. - Example — "orders in the last 3 months" where orders is a joined data mart: the date range narrows the joined orders before the join → slices. Using the results: - Use metrics and totals from the response directly — never recompute a value already present (totals are computed server-side over all matching rows, so they stay correct even when rows are truncated). - The totals block is separate from the rows. - Totals keys are technical output column names. Match a totals key to column_metadata[].name, not to a business-friendly columns label. - data_last_updated answers "how current is what I am looking at?". Read it carefully before repeating it: - data_last_updated_at is when the SOURCE TABLES last changed in the data warehouse. It is NOT a statement about which time period the data covers: a table rewritten today may have only backfilled figures for 2021. Say "the source tables were last updated on X", never "the data is fresh as of X". - null means unknown, not old and not fresh. Say the warehouse does not report it, and do not infer staleness from it. - coverage "partial" means some sources could not be read, so the real time can only be MORE recent than the one reported — present it as "at least as recent as X" and mention that the picture is incomplete. "unavailable" means nothing could be determined. - Mention it unprompted when the user's question depends on recency (today's numbers, "latest", trends up to now) or when they are about to act on the result. - Present every timestamp from this block (including per-table sources) in a business-friendly form — e.g. "August 4, 2026 at 09:46 UTC" — converted to the user's time zone when the conversation establishes one, otherwise in UTC with the zone named. Never show a raw ISO-8601 value like 2026-08-04T09:46:33Z. If truncated is true, not all matching rows were returned: narrow the query (fewer fields, tighter slices/filters) or raise limit (up to 1000). Always use the source metadata in the response: name the Data Mart the answer came from, distinguish numbers calculated by OWOX from arithmetic you perform yourself, and clearly warn the user when rows were truncated.

query_data_mart

Start an existing report by report_id and deliver fresh data to its push destination. Use this for a later rerun or when add_report returned initial_run.status="failed_to_queue". Do not call it when add_report already returned a queued run_id. Returns immediately with report_id and run_id; it does not wait for final status. Poll get_report_run_status with those ids until should_poll is false, waiting up to 15 seconds between checks when possible. Each call starts a new billed Report Run; concurrent runs are rejected as "Report is already running or pending".

run_report

Returns a high-level summary input for the current OWOX project published Data Mart catalog so the LLM can orient the user. Use when the user asks open-ended questions like "what data is available here?", "what can I analyze?", or "where should I start?". The tool returns counts and top published Data Marts ranked by configured relationship connectivity, with shortened descriptions and basic usage metadata. It does not query actual data rows, compute data freshness, or generate a natural-language summary.

summarize_data_catalog

Update an existing report: rename it, replace which data mart fields it exports, replace its output controls — filters/slices, aggregations, date_buckets, sort, limit — using the same vocabulary as query_data_mart ([] removes a control, null removes the limit), and/or — for reports with an email, slack, teams, or google_chat destination — change the message subject or body. Use it whenever the user asks to change a report that already exists — including one you created earlier in this conversation ("add a filter", "sort by revenue", "rename it") — instead of creating another report with add_report. Provide at least one change; anything not provided stays unchanged. Returns the report as it is after the update, and by default re-runs a Google Sheets report when the export changed (run.status="queued" — poll get_report_run_status), so the sheet shows the new definition; email, Slack, Teams, and Google Chat reports are re-sent only with run_immediately=true.

update_report

Updates one existing report run schedule identified by trigger_id (get it from list_report_run_schedules). This changes cron_expression, and optionally time_zone and is_active; it does not change the report target and does not create another schedule. Changing or disabling a schedule can skip report deliveries, and missed runs are not replayed when the schedule is restored. To add another schedule for the same report, call create_report_run_schedule instead. time_zone must be a valid IANA timezone (e.g. "Europe/Kyiv"); if omitted, the schedule keeps its current timezone. If is_active is omitted, the schedule keeps its current active state.

update_report_run_schedule