Skip to content
DocumentationReference
Reference
MCP tools

MCP tools

Use this reference to look up tool inputs and outputs. For connection, OAuth authorization, environment selection, and access scopes, see MCP setup.

This page lists public tools and their minimum scopes. Discovery in your client also depends on permissions, enabled features, and connected integrations. Behavior hints describe tool properties; the granted scope and resource permissions determine access.

ask

Asks the Altertable Agent an analytical question about the data in the current environment and returns its answer or a question for the user (no streaming). Never answer that question yourself: ask the user, with your own question tool if you have one, then continue with chat_id and their answer as the prompt. Use it for multi-step analysis the user wants the agent to handle end to end. The agent is read-only: it explores catalogs, runs read-only queries, and reads existing insights, dashboards, documentation, and public GitHub repositories, but never creates, updates, or deletes them or any data.

Minimum scope

ask_question

Ask one question when the user must decide and the request or context does not settle it. Offer exactly three distinct options, recommended first. The user replies in their next message with an option or their own answer.

Minimum scope

comment_finding

Add a comment to a finding discussion thread.

Minimum scope

create_dashboard

Creates a new dashboard. Expects a title plus optional description, widgets, variables, and labels. Widgets can reference saved insights by slug, embed inline insight definitions, show text, or group charts in sections. Returns the dashboard ID, slug, and URL.

Minimum scope

create_data_app

Creates a data app from a single index.tsx file. Only React, @altertable/data-app, and @altertable/data-app-react imports are allowed. The file is bundled before save, and declares the SQL queries the app runs by ID. The source defines its title and description. Returns the slug and URL.

Minimum scope

create_insight

Creates a new insight. Dispatches on the kind field and expects the matching definition: funnel + funnel_definition, journeys + journeys_definition, segmentation + segmentation_definition, retention + retention_definition, semantic + semantic_definition, or sql + sql_definition + sql_parameters. Returns the insight ID and slug.

Minimum scope

create_knowledge

Create an environment knowledge entry, loaded into this environment's agent session context along with organization knowledge. Only call this tool when the human explicitly asks to save a 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. Before creating the entry, ensure the human's intent to save it as environment knowledge is explicit; if the intended scope, title, or content is unclear, ask for clarification. Never paraphrase, summarize, synthesize, infer, translate, reformat, or generate either field yourself.

Minimum scope

create_memory

Store a high-signal fact, decision, finding, or reusable technique worth recalling in a later session, either because the user asked you to remember it or because it will save work next time. Skip routine or low-value details. Set source_slug (and entities) so search_memory can retrieve it.

Minimum scope

create_sandbox

Creates one short-lived workspace sandbox and returns its id and expiry. Pass repository slugs to clone repositories already connected to this workspace into /workspace/<slug>, or omit them for an empty sandbox. The workspace CLI in the sandbox is already signed in for this environment. An analyst session is read-only. The sandbox expires on its own and does not save its changes back to the organization.

Minimum scope

create_task

Creates one task in this workspace when the user asks to save it. An ask task runs its instructions on the given targets and starts active. A dlt_run task records where a pipeline will load and is saved paused, so this call does not run it. Provide a cron schedule, event triggers, or both. Never send secret values. Returns the task slug and URL.

Minimum scope

delete_data_app

Deletes a data app by slug.

Minimum scope

document_semantic_model

Sets the natural-language description on the persisted semantic model for a table. Pass catalog from list_catalogs (same value as its catalog_name); schema and table match the lakehouse identifiers.

Minimum scope

document_semantic_model_dimension

Sets the natural-language description on one dimension of a persisted semantic model. projection is the dimension name: alias (as) if set, otherwise the column name (same as listed under Columns/dimensions in get_catalog output).

Minimum scope

execute_insight

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).

Minimum scope

execute_lakehouse

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.

Minimum scope

explain_sql

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.

Minimum scope

generate_dlt_pipeline

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.

Minimum scope

get_catalog

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.

Minimum scope

get_finding

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.

Minimum scope

get_neighbors

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}.

Minimum scope

initialize

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.

Minimum scope

list_catalogs

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.

Minimum scope

list_dashboards

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.

Minimum scope

list_events

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.

Minimum scope

list_insights

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.

Minimum scope

list_repositories

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

Minimum scope

list_semantic_metrics

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.

Minimum scope

list_tasks

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.

Minimum scope

list_user_traits

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.

Minimum scope

profile_columns

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.

Minimum scope

query_lakehouse

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.

Minimum scope

read_resource

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.

Minimum scope

render_data_app

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.

Minimum scope

render_insight

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).

Minimum scope

report_finding

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

Minimum scope

run_sandbox_command

Runs one command inside an existing workspace sandbox and returns stdout, stderr, and the exit code. The command can modify that sandbox. It does not run on the host.

Minimum scope

search_docs

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

Minimum scope

search_entities

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.

Minimum scope

search_memory

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.

Minimum scope

take_screenshot

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.

Minimum scope

terminate_sandbox

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

Minimum scope

update_dashboard

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.

Minimum scope

update_data_app

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.

Minimum scope

update_insight

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.

Minimum scope

update_knowledge

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.

Minimum scope

update_task

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.

Minimum scope

validate_data_app

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.

Minimum scope

validate_sql

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.

Minimum scope

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.

Minimum scope