Altertable

Executes exactly one insight and returns its query results as structured data for further reasoning. Use this to read an insight's numbers, series, or rows. Pass `insight` for a saved insight or `definition` for a non-persisted insight, never both. A definition does not create or update a saved insight. Definitions dispatch on the `kind` field and expect the matching fields: `funnel` + `funnel_definition`, `journeys` + `journeys_definition`, `segmentation` + `segmentation_definition`, `retention` + `retention_definition`, `semantic` + `semantic_definition`, or `sql` + `sql_definition` + `sql_parameters` (x_axis_columns / y_axis_columns from SQL aliases). Definition-based funnel, journeys, segmentation, and retention kinds also require `from`, `to`, and `interval` inside `definition`. Preferred flow for new SQL results: validate the statement with `query_lakehouse`, then pass `sql_definition` and `sql_parameters` inside `definition` (visualization_options alone is not enough).

execute_insight

Executes a SQL statement against the lakehouse using the DuckDB dialect, including writes (INSERT/UPDATE/DELETE/DDL). Result output is bounded at 50000 tokens. If `truncation` is set, re-issue the same statement with `offset: <next_offset>` to fetch the next page. Add a deterministic `ORDER BY` to any query that may be paginated; without it, continuation can duplicate or skip rows (especially for GROUP BY or joins). For read-only queries, prefer the `query_lakehouse` tool instead. Before writing your first statement, load the `query-altertable` skill by reading `altertable://skills/query-altertable` with `read_resource`, unless it is already loaded.

execute_lakehouse

Check the DuckDB execution plan and estimated cost for one or more SQL statements before running them, to catch expensive queries early. Before writing your first statement, load the `query-altertable` skill by reading `altertable://skills/query-altertable` with `read_resource`, unless it is already loaded.

explain_sql

Writes the Python dlt pipeline that loads an external source into a lakehouse schema, and proves it runs in a sandbox before returning it. Call this when the user wants to ingest a source Altertable does not already hold. Returns a validated script plus the names of the source credentials it reads, or the reason no correct pipeline could be written. Pass `last_run_error` to repair a pipeline whose task run failed. This spawns a sandbox and takes several minutes, so tell the user it is running and how long it takes before calling it, and call it once the target and the source are settled, not to explore options.

generate_dlt_pipeline

Returns structured data for one or more lakehouse catalogs (altertable databases or external connections). Normally omit `level`: narrow with `schemas` and `tables`, and the tool automatically returns detailed schema for a small selection or a compact table overview for a large one. Use `level: overview` only when you explicitly want names and descriptions without columns; `columns` and `full` are explicit schema-depth overrides. After choosing a table, use profile_columns to inspect observed nulls, cardinality, uniqueness, ranges, and common values. Each table includes explicit semantic endorsement (draft, verified, excluded) labels. Tables whose semantic endorsement is `excluded` are omitted from the output. A column reported with `contains_pii` holds personally identifiable data: prefer aggregates over it and do not echo its values back to the user unless they ask for them. Typical flow: call with the default to discover tables. If more than one table could represent the requested concept, first inventory the schema without `tables` at `level: overview`; then pass `tables: [...]` for the specific tables you intend to query. When a table reports `estimated_row_count`, treat it as an approximate row count: on large tables keep query_lakehouse gentle with aggregates, selective filters, and LIMIT instead of scanning or returning every row.

get_catalog

Returns one finding by slug. Accepts a finding slug (DSC-*) or the slug of its inbox notification (NTF-*). Returns the finding body, review status, related task and context slugs, and comments.

get_finding

Walk one hop over stored entity_edges (structural associations and similar_to). Given an indexed entity slug, returns the entities directly connected to it in either direction as compact refs, plus the source identity. Find slugs via `search_entities`; read full content via `altertable://ontology/entities/{slug}`.

get_neighbors

REQUIRED FIRST STEP: CALL THIS BEFORE ANY OTHER TOOL. Returns information about the current organization, environment, and knowledge-entry context the agent must use to decide what to do and how to behave. Skipping this risks acting on the wrong scope or missing mandatory specific guidance.

initialize

Lists all data catalogs in the current environment: external connections (Postgres, Snowflake, etc.) and Altertable databases. Each entry includes slug (use in task target_slugs), catalog_name (use with get_catalog), name, engine, read_only, and description when one is set. For full schema, tables, and columns, call get_catalog with that catalog_name.

list_catalogs

Lists all dashboards in the organization. Dashboards are collections of insights presented together. Supports optional query filtering to search by title or description. Returns dashboard metadata including slug, title, description, and creation/update timestamps.

list_dashboards

Lists the Product Analytics event names tracked in the current environment, each with the names of the properties recorded on it. Use it to discover which events and properties exist before querying or charting them. Filter by a substring of the event name, or by when an event was last seen. Returns names only, never event counts or property values.

list_events

Lists all insights (charts) in the organization. Insights are saved queries of these kinds: funnel, journeys, segmentation, logssegmentation, semantic, sql, retention. Supports optional query filtering to search by title or description. Returns insight metadata including slug, title, description, chart kind, and creation/update timestamps.

list_insights

Lists Git repositories connected to the organization. Use the returned slugs with `create_sandbox` to clone specific repositories into a sandbox.

list_repositories

Lists the semantic metrics of this environment and, when one can be queried, a runnable query for it. Prefer these metrics over computing a business metric yourself, and run the query with query_lakehouse. Use a metric's expression only to explain it or tell metrics apart, e.g. a built-in filter. To combine, break down or filter, add metrics, DIMENSIONS or WHERE inside SEMANTIC_VIEW(...) using the dimension members listed on that metric, or other columns of the metric alias or of the aliases in those members, e.g. DIMENSIONS date_trunc('month', <member>) AS month.

list_semantic_metrics

Lists recurring tasks in the environment (schedules, ask tasks, dlt pipelines, etc.). Supports optional filters by full-text query, task kind (same names as create_task `type`), target slug, and labels.

list_tasks

Lists the names of user traits recorded by Product Analytics in the current environment. Use it to discover which trait names exist before filtering or segmenting by them. Returns trait names only, never trait values.

list_user_traits

Performance-optimizes one DuckDB query class per call and benchmarks the rewrite before returning it. Three target modes: pass `statement` to optimize a read-only SELECT directly; pass `query_fingerprint` to optimize that recurring query class from the workload digest; pass neither to optimize the single slowest candidate in the digest. The rewrite preserves the exact output column shape and is verified against the live data. Returns the proven-faster rewrite with its benchmark, or a data layout recommendation when no rewrite can help. Resolving a target from the digest requires the analytics digest catalog to be attached.

optimize_sql

Profiles selected columns from one lakehouse table using one bounded, cached sample query. Use this after get_catalog and before SQL when the answer depends on repeated versus unique values, null or blank handling, entity versus event grain, ordering stored values, or interpreting an ambiguous measure. Returns counts, cardinality, sample-scoped uniqueness, ranges, and common values. Observed nulls and blanks are evidence about representation; do not exclude nulls or blanks unless the request or documented semantics require it. Always pass only the load-bearing columns; at most 25 columns can be profiled per call.

profile_columns

Executes a read-only SQL query against the lakehouse using the DuckDB dialect. Result output is bounded at 50000 tokens. If `truncation` is set, re-issue the same statement with `offset: <next_offset>` to fetch the next page. Add a deterministic `ORDER BY` to any query that may be paginated; without it, continuation can duplicate or skip rows (especially for GROUP BY or joins). To write data, use the `execute_lakehouse` tool instead. Before writing your first statement, load the `query-altertable` skill by reading `altertable://skills/query-altertable` with `read_resource`, unless it is already loaded.

query_lakehouse

Reads an `altertable://` resource and returns its contents. `altertable://skills/{name}` returns a skill playbook and an `additional_files` manifest; `altertable://skills/{name}/{directory}/{filename}` returns a linked skill file (e.g. `altertable://skills/analyze-product-behavior/references/match-recognize.md`). `altertable://ontology/entities/{slug}` returns an entity in full; `altertable://ontology/entities/{slug}/neighbors` lists what it connects to; `altertable://ontology` describes the entity types. Use a URI already in context; otherwise find slugs with `search_entities`.

read_resource

Renders one saved data app in the inline Data App Viewer. Use this when the user asks to open, show, or interact with a data app.

render_data_app

Renders exactly one insight in the inline Insight Viewer so the user can see the chart. Returns query results plus the visualization metadata the client needs to display the insight. Use this when the user asks to show, visualize, chart, inspect, or render a saved or non-persisted insight. Pass `insight` for a saved insight or `definition` for a non-persisted insight, never both. A definition does not create or update a saved insight. Definitions dispatch on the `kind` field and expect the matching fields: `funnel` + `funnel_definition`, `journeys` + `journeys_definition`, `segmentation` + `segmentation_definition`, `retention` + `retention_definition`, `semantic` + `semantic_definition`, or `sql` + `sql_definition` + `sql_parameters` (x_axis_columns / y_axis_columns from SQL aliases). Definition-based funnel, journeys, segmentation, and retention kinds also require `from`, `to`, and `interval` inside `definition`. Preferred flow for new SQL results: validate the statement with `query_lakehouse`, then pass `sql_definition` and `sql_parameters` inside `definition` (visualization_options alone is not enough).

render_insight

Reports a finding worth human attention from the current investigation. Persists the finding and notifies users through enabled delivery channels.

report_finding

Search the Altertable platform documentation for information about features, insight types, usage and best practices. Returns relevant documentation snippets with titles, content, and URLs.

search_docs

Hybrid lexical and semantic search across indexed Altertable entities. Returns matching entity slugs, titles, content snippets, an `rrf_score` for in-response ordering, a `semantic_similarity` (absolute relevance, present when the semantic branch matched), and `matched_branches` indicating which retrieval branches (lexical, semantic) fired per hit. Use `node_types` to scope by entity type; its schema lists every searchable type, and any other value is rejected. Read `altertable://ontology` for how types relate. Read a hit's `resource_uri` for its full content. Call `get_neighbors` to inspect directly related entities.

search_entities

Search for memories, ranked by reciprocal rank fusion (RRF), with importance as a bounded boost. Supports both semantic (vector) and keyword search. Note: Returned memories count as accessed, at most once per day. Tip: Use this tool proactively at the start of a workflow to auto-recall relevant context.

search_memory

Use this to see how a supported entity renders, given its slug. It captures the shared view of the entity as an inline image. Auto-creates a short-lived share token if none exists.

take_screenshot

Terminate a sandbox created by `create_sandbox`. Safe to call more than once; a missing or already-expired sandbox is not an error.

terminate_sandbox

Updates an existing dashboard. Provide the dashboard slug plus any fields to change: title, description, widgets, variables, or labels. Widget and variable lists replace the current values when provided. Returns the dashboard ID, slug, and URL.

update_dashboard

Replaces the source of a data app. The new source is bundled before save and may only import React, `@altertable/data-app`, and `@altertable/data-app-react`. It replaces the title, description and queries with those it declares. Returns the slug and URL.

update_data_app

Updates an existing insight. Provide the insight slug plus any fields to change. Definition fields (`funnel_definition`, `segmentation_definition`, `sql_definition`, etc.) and matching `*_parameters` apply to the current or updated `kind`. Returns the insight ID, slug, and URL.

update_insight

Update a knowledge entry in the current environment. Only call this tool when the human explicitly asks to change a saved knowledge entry. The title and content must be either text the human provided directly, or text fetched verbatim from a source the human explicitly pointed at. Never paraphrase, summarize, synthesize, infer, translate, reformat, or generate either field yourself.

update_knowledge

Update a recurring task. Provide the task slug plus the fields to change: instructions, CRON schedule, event triggers, active state, title, target slugs, or the `script` and `timeout_seconds` of a `dlt_run` task. A task can carry a schedule and events at the same time; omitted fields are left unchanged. For a `dlt_run` task, catalog, schema and targets are fixed at creation; its script, timeout and the common task fields stay updateable.

update_task

Compiles and type-checks index.tsx and checks the queries it declares without saving. Valid when `errors` is empty, type errors included; `warnings` never fail validation.

validate_data_app

Validates whether a SQL statement is valid DuckDB dialect. Before writing your first statement, load the `query-altertable` skill by reading `altertable://skills/query-altertable` with `read_resource`, unless it is already loaded.

validate_sql

Performs a web search and returns ranked results (title, URL, snippet, and age when known). Prefer other tools: use this only when you need to search for external/public information on the web.

web_search