MCP tools

Asks the Altertable Agent an analytical question about the data in the current environment and returns its final answer when done (no streaming). 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.

Asks the user to fill in a secret that is needed but not yet held. A secret belongs to the one task that reads it, never to the environment at large, so name the task as well as every secret it needs. Give each a compact field hint: what to paste, where to find it, and only essential access context. Altertable renders one password field per name and stores the value directly, so no secret passes through this conversation. Pass names and descriptions only, and never ask the user to paste a secret into the chat. This tool cannot read a secret back: use it to set or rotate one, not to check one.

Calls a tool on an organization-connected MCP server. Use list_mcp_tools first to discover tool names and argument schemas. In read-only and analyst sessions, only remote tools annotated read-only can be called.

Add a comment to a finding discussion thread.

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.

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

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.

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.

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.

Create a short-lived shell sandbox for investigation (inspect files, run commands, etc). Optionally clones repositories into /workspace/<slug> when slugs are provided (use list_repositories to discover them). The altertable CLI is preconfigured with lakehouse and management API credentials. Pass the returned sandbox_id to run_sandbox_command; call terminate_sandbox when finished. In an analyst session the sandbox is read-only but still available for investigation; it is ephemeral and does not persist changes to the organization.

Create a recurring task with a CRON schedule and/or event triggers: an ask run on zero or more entity targets, or a dlt_run pipeline that loads a source into a lakehouse schema. A task can carry a schedule and events at the same time. This is the only tool that persists a task. A dlt_run task is saved paused.

Deletes a data app by slug.

Returns the argument schema for a tool attached to this session whose schema was withheld. Call this before the first use of a tool that tells you to, then pass those arguments.

Runs a read-only SQL query against the lakehouse using the DuckDB dialect and posts its result as a table in the Slack thread. The column names become the header row. The result must fit Slack's table limits: at most 200 rows, 20 columns and 20000 characters, so aggregate or add a LIMIT first. Returns whether the table was posted, not its rows.

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.

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

Draft or update a dashboard the user is iterating on. Call this whenever you have a complete dashboard definition. The UI displays it as a draft for the user to review and refine.

Draft or update an insight (chart) the user is iterating on. Call this whenever you have a complete insight definition. The UI displays it as a draft for the user to review and refine.

Draft or update the SQL query the user is iterating on in the SQL editor. Call this whenever you have a complete DuckDB statement. The UI displays it as a draft for the user to review and run. The statement is validated and explained, so the response tells you whether it binds and how much data it scans before the user runs it.

Draft or update a segment the user is iterating on. Call this whenever you have a complete segment definition. The UI displays it as a draft for the user to review and refine.

Draft or update a scheduled task the user is iterating on. Call this with a complete definition. The UI displays it as a draft for the user to review and explicitly approve before creation.

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

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.

Check the DuckDB execution plan and estimated cost for one or more SQL statements before running them, to catch expensive queries early.

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.

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.

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.

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

Reads files or lists directories in one GitHub repository without cloning it. Works for any public repository. Private reads require access to a linked repository in this environment, or permission to manage the organization GitHub integration. Pass several entries in reads to fetch them in one call; results come back in the same order, and a failure is reported on that entry. Start with command read-dir (omit path for the repository root) to see names, paths, and types, then read-file to read files. For large files, pass start_line and end_line; when truncated is true, continue from end_line + 1.

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.

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.

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.

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.

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.

Lists tools exposed by organization-connected MCP servers, including argument schemas. Pass mcp_server_slug to inspect one server, or omit it to list every connected server. Use call_mcp_tool to invoke a listed tool. In read-only and analyst sessions, only remote tools annotated read-only are listed.

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

Lists the semantic metrics of this environment with their label, layer, description, table, and source.

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.

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.

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.

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.

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.

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.

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.

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

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

Run a shell command in a sandbox created by create_sandbox and return stdout/stderr.

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

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

Delegates a self-contained prompt to a read-only subagent. The subagent cannot see this conversation, catalogs, ontology, environment context, or your SQL/product-analytics playbook. Put in prompt only what this task needs (relevant catalogs or tables, entity slugs, metric definitions, time range, desired output shape, and any procedure it should follow) and omit the rest. Choose difficulty as easy, medium, or hard. The call blocks until the subagent finishes and returns its answer. You may call this several times in parallel for independent investigations.

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.

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

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.

Updates a data app. Provide the slug plus any fields to change. New source is bundled before save and may only import React and @altertable/data-app. Returns the slug and URL.

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

Maintain a live, ordered plan of what you are doing so the user can follow along. Use update_plan when a request needs more than one distinct action; do not use it for a trivial, single-action request. Once a plan exists, keep exactly one step inprogress until all steps are done. Before calling a tool for a later step, call update_plan in the same turn to mark the previous step done and the new step inprogress. Do not postpone step transitions until the end or mark several completed steps done only in the final update. The UI renders these steps for the user, so do not narrate them in prose. Phrase each step label as an ongoing action (e.g. "Querying orders", "Building chart") and keep it to 3 words or fewer. Reference the entity a step concerns by its entity_slug. You can issue this call in the same turn as the other tools you are using, and you do not need to wait for or read its result, since it only updates the display.

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.

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.

Validates whether a SQL statement is valid DuckDB dialect

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.