# MCP tools When an AI agent connects to Altertable via MCP, it gains access to the following tools. This list is generated from the MCP server definition and stays in sync automatically. | Tool | Description | | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ask` | 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. | | `ask_secret` | 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. | | `call_mcp_tool` | 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. | | `comment_finding` | Add a comment to a finding discussion thread. | | `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. | | `create_data_app` | 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. | | `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. | | `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. | | `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. | | `create_sandbox` | Create a short-lived shell sandbox for investigation (inspect files, run commands, etc). Optionally clones repositories into /workspace/\ 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_task` | 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. | | `delete_data_app` | Deletes a data app by slug. | | `describe_tool` | 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. | | `display_slack_data_table` | 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. | | `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. | | `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). | | `draft_dashboard` | 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_insight` | 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_query` | 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_segment` | 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_task` | 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. | | `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). | | `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: ` 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. | | `explain_sql` | Check the DuckDB execution plan and estimated cost for one or more SQL statements before running them, to catch expensive queries early. | | `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. | | `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. | | `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. | | `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}`. | | `github_read` | 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`. | | `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. | | `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. | | `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. | | `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. | | `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. | | `list_mcp_tools` | 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. | | `list_repositories` | Lists Git repositories connected to the organization. Use the returned slugs with `create_sandbox` to clone specific repositories into a sandbox. | | `list_semantic_metrics` | Lists the semantic metrics of this environment with their label, layer, description, table, and source. | | `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. | | `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. | | `optimize_sql` | 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. | | `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. | | `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: ` 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. | | `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`. | | `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. | | `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). | | `report_finding` | Reports a finding worth human attention from the current investigation. Persists the finding and notifies users through enabled delivery channels. | | `run_sandbox_command` | Run a shell command in a sandbox created by `create_sandbox` and return stdout/stderr. | | `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. | | `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. | | `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. | | `start_subagent` | 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. | | `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. | | `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. | | `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. | | `update_data_app` | 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. | | `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. | | `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. | | `update_plan` | 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_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. | | `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. | | `validate_sql` | Validates whether a SQL statement is valid DuckDB dialect | | `web_search` | 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. |