Available Tools

Delegates a question or instruction to the Altertable Agent. 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 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 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 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. 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 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 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 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.

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). By default (level: auto) it renders full detail (columns, semantic dimensions, measures and relations) for small catalogs and a compact overview (schemas, table names, descriptions and semantic endorsement, without columns) for large ones, deciding by size. Force a depth with level: overview, level: columns, or level: full. Narrow the output with schemas and/or tables to fetch only the parts you need (recommended for wide catalogs). Use level: profile with tables: to additionally sample columns and report null percentage, cardinality, min/max, and top values. Prefer columns: when you only need specific columns. Profiles use a bounded reservoir sample. Each table includes explicit semantic endorsement (draft, verified, excluded) labels. Tables whose semantic endorsement is excluded are omitted from the output. Typical flow: call with the default to discover tables, then pass tables: [...] (optionally level: profile) for the specific tables you intend to query.

Walk the entity ontology one hop. 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}.

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, engine, and description when one is set. 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, ask tasks, anomaly detection, forecasts, etc.). Supports optional filters by full-text query, task kind (same names as create_task type), target slug, and labels.

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

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

Renders a non-persisted insight from an insight definition. Executes the definition and returns the data results plus visualization metadata needed for MCP clients to display the insight inline. Does not create or update a saved 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. Use this when the user asks to show, visualize, chart, inspect, or render an insight without saving it. 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.

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; 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, ranked primarily by relevance to the query, with importance as a bounded boost. 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.

Use this to see how a referenced 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.

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 an existing insight. Provide the insight slug plus any fields to change. Definition fields (funnel_definition, segmentation_definition, etc.) apply to the current or updated kind. Returns the insight ID, slug, and URL.

Update an organization-wide knowledge entry. 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. 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. 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 any fields to change: instructions, CRON schedule, target slugs, active state, or title. Omit a field to leave it unchanged.

Validates whether a SQL statement is valid DuckDB dialect

Retrieves a dashboard by its slug. Returns title, description, labels, 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.

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.