Improvado AI Agent

Check the ClickHouse query complexity for an existing view or materialized view. Reads the object SQL from system.tables, then runs the complexity check. Use when reacting to "this view is too expensive" or before replacing a production object.

clickhouseObjectQueryComplexityTool

Check the ClickHouse query complexity for a recipe (notebook) before running or deploying it. Resolves the final recipe SQL from ai-assistant-backend, then runs the complexity check. Use before running or scheduling a recipe transformation.

clickhouseRecipeQueryComplexityTool

Check the ClickHouse query complexity for a dashboard widget before adding or updating it. Fetches the compiled SQL from ai-dashboards, then runs the complexity check. Use before addWidgetTool or updateWidgetTool for any queryable widget.

clickhouseWidgetQueryComplexityTool

Get a secure link to connect a data source to the current Improvado workspace. Omit the data source to browse available sources with search, categories, and label filters, or specify one to open its setup. The setup page shows existing connections; select a connection to view its accounts. Open the link in the customer's browser or provide it as a clickable link; the customer signs in and completes setup there. The private link works once and expires shortly. Do not open it in advance to test it; request a new link if needed.

connectDataSourceTool

Copy a dashboard into a new one. Widgets and layout are deep-copied, and every child page is cloned into its OWN new row — a copy never shares pages with the original, so editing one cannot change the other. Returns the new settingsId (and the cloned page ids).

copyDashboardTool

Count the rows of a workbook whose entity id is no longer in the workbook’s source, within the workbook’s stored filters and accounts. Source sync only adds and updates rows, so these stay in the grid and the compliance score until nc_remove_rows_absent_from_source removes them. Matched by id, so a renamed entity is not counted. IMPORTANT: for the end-to-end workflow, follow the `naming-convention` skill — read it locally if available, otherwise from the knowledge graph (under `knowledge-graph/general/skills/`, via listKnowledgeGraphFiles + retrieveFromKnowledgeGraph).

nc_count_rows_absent_from_source

Create a recurring heartbeat automation that runs an agent on a schedule. A recurring automation creates a new result chat on every run (an interval one reuses a single hidden chat) and persists memory/artifacts in the workspace Knowledge Graph path. Use scheduleType "interval" to keep checking on work you started until it finishes; its runs report back to this chat with reportToParentChatTool.

createAgentAutomationTool

Register a generated automation summary, plan, email report, or execution result after writing its markdown file to the workspace Knowledge Graph. Use kgPath relative to /mnt/kg/workspace, for example automations/<automationId>/outputs/<runId>.md.

createAgentAutomationOutputTool

Create a brand preset in the current workspace. Set isDefault to make it the brand new dashboards get — a scope has at most one default, so this takes it from whichever preset held it. Agency-wide presets are not created here: they are admin-managed.

createBrandPresetTool

Create a new agency-scoped custom role. Title must be non-empty and unique within the agency. `layers` keys must come from getRolePermissionsCatalogTool; each value must be a list of permission codes valid for that layer. The tool validates the payload against the catalog before submitting and returns a helpful error if any layer or permission is unknown. Docs: https://improvado.io/docs/manage-custom-roles

createCustomRoleTool

Create a NEW editable dashboard and return its settingsId. Pass `database` and `operations` (the patchDashboard vocabulary: addWidget / updateFilters / mergeConfig, applied in order to the fresh config) to create it WITH its widgets, filters and settings in ONE call — one validation, one save, one version, and nothing is created if an operation fails. That replaces the createDashboard + patchDashboard pair; add more later with addWidget / patchDashboard. Use this rather than copying when there is no existing dashboard worth starting from. ONE dashboard "with tabs / pages / sections as separate pages" is ONE createDashboard for the parent plus addPage per tab — never N createDashboard calls (that yields N unrelated dashboards in the menu), and never text-box separators in one flat grid when the user asked for tabs.

createDashboardTool

Create a new dashboard folder in the current workspace. Pass parentId to nest it inside another folder, or omit/null to create it at the top level. Use listDashboardFoldersTool first to resolve a parent folder name to its id.

createDashboardFolderTool

Create a new editable dashboard from a PUBLISHED template (template_<id>) or the system_budget_pacing_live template. Budget Pacing requires verified workspace data before creation. The copy is independent — editing it never changes the template — and it stays linked, so the user can later pull template updates with 'Sync with template'. For a blank dashboard use createDashboard; to duplicate an existing dashboard use copyDashboard.

createDashboardFromTemplateTool

Create a new data extract from a data source

createExtractTool

Create a custom extraction template based on a parent global template. Works for both entity and wide report templates. For wide templates (parent has allow_to_select_dimensions=True), connection_id is REQUIRED; for entity report templates, connection_id is NOT needed. TIP: When creating extracts for "wide" data sources, the standard createExtractTool may lack field validation. Instead, first create a custom template with this tool (which validates fields, dimensions, and additional_params), then create an extract based on the resulting custom template ID.

createExtractTemplateTool

Create a NEW flat data extract from an uploaded file. This is the final step in the NEW file import flow - it creates a persistent extract configuration that stores the data. To upload a file to an EXISTING extract, use uploadNewFileToExtractTool instead.

createFlatDataExtractTool

Create a NEW file in the knowledge graph. Fails if a file already exists at the path (use editKnowledgeGraphFile to change an existing one). Writable scopes are "workspace" and "agency"; "general" is read-only. Path must end with a supported extension (.md, .txt, .json, .yaml, .yml, .csv, .html); .md files require a YAML frontmatter block.

createKnowledgeGraphFile

Create a new data load to a destination

createLoadTool

Create a new data governance rule folder in the current workspace. Pass parentId to nest it inside another folder, or omit/null for the top level. Use listMdgRuleFoldersTool first to resolve a parent folder name to its id.

createMdgRuleFolderTool

Create one or more naming convention workbooks for the chosen dimensions of a source table. table_name is required (datasource-only creation is not supported here — provide the source ClickHouse table name). This is a synchronous, potentially long-running call (analyzes the source table, builds allowed_values + campaign tables in ClickHouse). Returns the new workbook set id and the dimensions that were processed. IMPORTANT: for the end-to-end workflow, follow the `naming-convention` skill — read it locally if available, otherwise from the knowledge graph (under `knowledge-graph/general/skills/`, via listKnowledgeGraphFiles + retrieveFromKnowledgeGraph).

nc_create_workbook

Create an Improvado platform connection for a data source. auth_id and params must match one of the data source's declared authentication methods; params carries non-secret settings such as connection_name. Parameters holding a password, API key, token or secret are rejected on this server: sources that need credentials are connected in the Improvado interface. Use connectDataSourceTool to get an authorized link to that interface. New connections are visible to the whole workspace unless visibility is 'private'; reconnecting an existing connection keeps its privacy. Returns connection_id, action ('created' / 'reconnected') and is_private.

createConnectionTool

Create a recipe from a template

createRecipeTool

Create a new recipe step (cell). Currently supports only SQL steps.

createRecipeStepTool

Create a SQL extract from a connection + table (or custom query). This is the final step — it persists the extract config and schedules recurring pulls. Run field discovery and sample first so the user confirms the schema.

createSqlExtractTool

Create a one-time link that signs the user's browser in to Improvado and opens the given page. Improvado pages such as dashboards open a sign-in page in a browser without an Improvado session; open this link there instead. The link works once and expires within minutes: open it right away, and do not open it in advance to test it. Once it is opened the browser stays signed in and other Improvado pages open directly, so request a new link only when a sign-in page appears again.

createSignInLinkTool

Create a Google Sheets extract using the flat data API

createSpreadsheetExtractTool

Create or replace data governance view in agency schema. Use CREATE OR REPLACE to update existing rules.

createMdgViewTool

Decline a flat data file that is waiting for approval (status awaiting_approval): the file is not processed, nothing is loaded from it, and the extract's config is left exactly as it is. Use it when the file itself is the problem — the wrong report, an unreadable export — not when the user only rejects a proposed config change. For that, replay the extract's held files with skip_config_gate=true, which processes them by the config as it stands. Declining is final for that file, and a corrected file can then be uploaded under the same name.

declineFlatDataFileTool

Delete a heartbeat automation and stop future scheduled runs.

deleteAgentAutomationTool

Delete an agency-scoped custom role. Users currently assigned to it are atomically reassigned to the system **Viewer** role; the response includes `reassigned_users_count`. System roles cannot be deleted. **Before calling this tool, you should normally call listRoleUsersTool (or check `user_count` from listWorkspaceRolesTool) and, if any users will be affected, confirm with the user that they accept the fallback to Viewer.** Set `confirm_user_reassignment: true` to acknowledge that user reassignment is expected. Docs: https://improvado.io/docs/manage-custom-roles

deleteCustomRoleTool

Delete a data load

deleteLoadTool

Permanently delete a naming convention workbook tab: its ClickHouse table, allowed-values glossary, overrides and view are dropped, every stored version is removed, and scheduled source syncs are cancelled. It refuses if the table is not where the workbook says it lives, so a failed call deletes nothing. Associated data governance rules are deleted first; this requires governance edit permission in addition to naming convention delete. If a rule cannot be removed, the workbook is kept and the response includes its rule name and link. This cannot be undone and there is no export step; nc_export returns the rows beforehand. Fixing a delimiter or a column instead of dropping the tab is nc_change_delimiter or nc_manage_columns. IMPORTANT: for the end-to-end workflow, follow the `naming-convention` skill — read it locally if available, otherwise from the knowledge graph (under `knowledge-graph/general/skills/`, via listKnowledgeGraphFiles + retrieveFromKnowledgeGraph).

nc_delete_workbook

Delete a workbook set: every workbook in it, their campaign tables, their glossaries, their views, their recorded manual corrections and their sync schedules. Nothing here can be restored — a stored version carries no row data, so the tables cannot be rebuilt from one; only a fresh nc_create_workbook from the source can. Associated governance rules are deleted first and require governance edit permission. A blocked rule keeps its tab and the set in place. Get explicit confirmation from the user, and pass the set's exact name as confirmName. To repair a set rather than discard it, reorder its columns or rebuild its data instead. IMPORTANT: for the end-to-end workflow, follow the `naming-convention` skill — read it locally if available, otherwise from the knowledge graph (under `knowledge-graph/general/skills/`, via listKnowledgeGraphFiles + retrieveFromKnowledgeGraph).

nc_delete_workbook_set

List the props a widget TYPE accepts, straight from the dashboard schemas — call it before building a widget you have not built recently, instead of guessing field names. Omit `type` to see the available types. This reads the live schema, so it cannot go stale the way a remembered field list does.

describeWidgetTool

Remove a child page from the parent's tab strip. The page's own dashboard row is left intact and becomes a standalone dashboard in the list, not deleted, so this is reversible by re-adding the reference. Remaining pages are re-ordered so no gap is left.

detachPageTool

Check whether a workbook's part columns still agree on which token of the source name each one takes. Compares the stored column_order against the splitByChar indices baked into the campaign view, and reports any part column the campaign table is missing. A disagreement means the workbook is parsing names against a different taxonomy than the one that produced its values. Physical column order is reported for information only — ClickHouse fixes it at creation, so it never tracks the taxonomy. IMPORTANT: for the end-to-end workflow, follow the `naming-convention` skill — read it locally if available, otherwise from the knowledge graph (under `knowledge-graph/general/skills/`, via listKnowledgeGraphFiles + retrieveFromKnowledgeGraph).

nc_diagnose_token_order

Discover field definitions (column names, types) from an uploaded flat data file. Uses the Improvado field discovery API to analyze the file and return inferred field schemas.

discoverFileFieldsTool

Discover field definitions (column names, suggested and possible types, dimension/metric) from a SQL table or custom query. Call this after the user picks a table from listSqlReportTypesTool.

discoverSqlFieldsTool

List all accounts with optional filtering and pagination. Supports filtering by connection ID, active status, search terms, and ordering.

discoveryListAccountsTool

List all connectors for a given datasource

discoveryListConnectorsTool