Available Tools

Delegates a question or instruction to the Altertable data agent (Ask AI). The agent explores the data in the current environment, answers analytical questions, and can draft or create insights, discoveries, and tasks. It runs to completion and returns the final answer (no streaming). Pass chat_id to continue a previous conversation; omit it to start a new one (the resulting chat_id is returned so you can continue the conversation later).

Creates a new discovery to log a finding. A notification record is always created. Set notify to false to skip fanning out notifications through enabled delivery channels — notifications are sent by default.

Creates a new funnel insight. Returns the insight ID and slug.

Create an organization-wide knowledge entry, loaded into every agent's session context. 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 organization-wide 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 insights, learnings, and procedures discovered during data analysis. Use episodic for analysis sessions/findings, semantic for data facts/patterns, procedural for query techniques/workflows. Higher importance decays slower.

Creates a new retention insight. Returns the insight ID and slug.

Creates a new segmentation insight. Returns the insight ID and slug.

Creates a new semantic model-based insight. Returns the insight ID and slug.

Creates a new SQL-based insight. Returns the insight ID and slug.

Create a recurring task with a CRON schedule; can also schedule anomaly detection or forecast runs on an insight or dashboard target.

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 an insight (chart) the user is iterating on. Call this whenever you have a complete definition. The UI displays it as a draft for the user to review and refine. Use this during draft iteration; the create_*_insight tools persist a finished insight and are not used while iterating.

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

Returns a markdown description of one or more lakehouse catalogs (altertable databases or external connections): physical schemas, tables, columns and semantic dimensions, semantic measures, and relations. Each table includes explicit semantic endorsement (draft, verified, excluded) labels.Tables whose semantic endorsement is excluded are omitted from the output.

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 catalog_name (use with get_catalog), name, and engine. For full schema, tables, and columns, call get_catalog with that catalog_name.

Retrieves events along with statistics for a given time period. Returns aggregated event data including event names, counts, and metadata. Supports optional query filtering to search specific events.

Lists all insights (charts) in the organization. Insights are saved queries that can be SQL, semantic, segmentation, or funnel type. Supports optional query filtering to search by title or description. Returns insight metadata including slug, title, description, chart kind, and creation/update timestamps.

Lists recurring tasks in the environment (schedules, monitors, anomaly detection, forecasts, etc.). Supports optional filters by full-text query, task kind (same names as create_task type), target slug, and tags.

Retrieves user traits (attributes) data. Returns user attribute data that can be used for segmentation, personalization, and analysis. User traits include properties like email, name, subscription tier, and custom attributes.

Performance-optimizes a DuckDB SQL statement using EXPLAIN analysis and sample query execution. Preserves the exact output column shape (names and types). Returns the original statement unchanged when already optimal or when optimization would alter column shape or semantics.

Previews the results of an insight without creating a permanent insight. Dispatches on the kind field and expects the matching definition: funnel + funnel_definition, segmentation + segmentation_definition, retention + retention_definition, semantic + semantic_definition, or sql + sql_statement. Funnel, segmentation and retention kinds also require from, to, and interval. Useful for testing configurations before committing to creation. Preferred flow for SQL results: validate the statement with query_lakehouse, then call this tool to render the result as a chart in MCP clients that support MCP Apps.

Executes one or more SQL queries against the lakehouse using the DuckDB dialect. Results come back in the same order as the input, with rows and column metadata. Each statement output is bounded at 50000 tokens. If a result has truncation set, re-issue that statement with offset: <result.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). Displayed as an MCP App in clients that support them.

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, in-response relevance scores, and matched_branches indicating which retrieval branches (lexical, semantic) fired per hit. Use node_types to scope by entity type; read the resource at altertable://ontology for valid types. After finding a slug, read the resource at altertable://ontology/entities/{slug} for full entity content.

Search for memories with relevance-based ranking (considers recency, access patterns, and importance). Supports both semantic (vector) and keyword search. Note: Each search increments access_count on returned memories. Tip: Use this tool proactively at the start of a workflow to auto-recall relevant context.

Takes a screenshot of a dashboard or insight via its shared link. Returns an inline image for visual verification. Auto-creates a short-lived share token if none exists.

Maintain a live, ordered plan of what you are doing so the user can follow along. Call this as soon as a request needs more than one action to lay out the steps, then call it again after each step to advance its state (pending, then inprogress, then done) and keep the plan current. The UI renders these steps for the user, so do not narrate them in prose. Reference the entity a step concerns by its entity_slug.

Validates whether a SQL statement is valid DuckDB dialect

Retrieves a dashboard by its slug. Returns title, description, tags, and ordered widgets (chart/text/section with grid positions). Includes a flat list of referenced insight slugs. Does NOT execute queries — use view_insight for that.

Executes an insight query and returns results. Works with SQL, semantic, segmentation, and funnel insights. For large results, summarize key findings rather than echoing raw data.

Fetch the 50 most popular pages in the current environment for a time period.

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.