Improvado AI Agent

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

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>). 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 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. Returns the connection_id on success.

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. Data governance rules built on the workbook are not deleted — check nc_list_workbook_sets first and remove them separately, or they keep running against a table that no longer exists. 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. 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

Call the Improvado Discovery API for a given data source and connector to fetch live data from a platform such as Facebook, Google Ads, TikTok or LinkedIn. The request shape is published in Improvado's guides rather than derived from the platform's public docs. The full protocol ships as a skill in the knowledge graph: getKnowledgeGraphFile({ scope: "general", path: "skills/discovery-api/SKILL.md" }) returns it whole. The points below are the minimum contract when that file has not been read. - Coverage is listed in the catalog: getKnowledgeGraphFile({ scope: "general", path: "skills/discovery-api/guides/catalog.json" }). It names every published source with its aliases, which is how a platform named in plain words resolves to a slug, and how a docs slug maps to the `dataSource` name (docs `google_ads` is Discovery `google_ads_ql`). A source absent from the catalog is not covered. - retrieveFromKnowledgeGraph({ query: "<data source> <endpoint or task>" }) returns routing context (index.md, endpoints.md). That output is budgeted and truncates, so it locates the contract rather than stating it. getKnowledgeGraphFile on endpoints/<group>/<op>.md returns the file whole and carries the exact endpoint, absolute-URL shape, required params, mandatory headers, pagination and version; listKnowledgeGraphFiles resolves the path. For a source the catalog does not list, the official changelog via WebSearch or WebFetch is the fallback. - `request.url` takes an absolute URL with a scheme, shaped like https://graph.facebook.com/v<VERSION>/act_<id>/insights, with the version resolved from the guide. A relative path such as /me/adaccounts or /act_<id>/campaigns returns 400 "discovery URL ... is not allowed". - Versions come from the guide's technical.md or endpoints files, or from the official changelog for an uncovered source. A version taken from a prior example does not carry over between calls. - `connectorId` comes from discoveryListConnectorsTool and is the user's choice. - Endpoints that need an account take the account id from discoveryListAccountsTool. - Async endpoints return a report, query or job id with a status instead of rows: DV360 Bid Manager, Bing reporting, Amazon reports, CM360, The Trade Desk. Submit, hand the user the ids, then space the status checks out — 30 s, 60 s, 120 s, then 300 s, one check per turn without a shell — and fetch the finished file with discoveryFileDownloadTool, passing the header X-LES-Skip-Proxy-Auth: 1 for pre-signed result URLs. Resubmitting because polling is slow starts a second job. The skill's 'Async requests' section is the full protocol.

discoveryRequestTool

Download a file from a data source API via secret proxy and save it to storage. Unlike discoveryRequestTool which loads the full response content into the conversation context, this tool uploads the response to storage and returns a signed URL so you can download the file directly to disk using curl. Use this for binary data (Excel, PDF, ZIP, images), large CSV exports, or any response you want saved as a file without consuming context window. Async report jobs end here: fetch the finished report file with this tool, not discoveryRequestTool. For a PRE-SIGNED result URL (GCS googleCloudStoragePath, S3 ReportDownloadUrl, gzip links) pass the header X-LES-Skip-Proxy-Auth: 1 so no vendor Authorization header is injected — the URL is the credential. Returns a signed download URL valid for 12 hours.

discoveryFileDownloadTool

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

Display a grid of available data sources that users can connect to Improvado. Shows data sources with logos, categories, and connect buttons. Use this when user wants to see or connect data sources. Optionally filter by category.

discoveryListDataSourcesTool

Copy an existing page into a new tab on the same dashboard: same widgets and layout, its own row. The copy is deep — editing one page never changes the other. Use listPages to find the source pageSettingsId.

duplicatePageTool

Overwrite an EXISTING file in the knowledge graph with new content. Fails if the file does not exist (use createKnowledgeGraphFile for new files). Writable scopes are "workspace" and "agency". Pass the `etag` from getKnowledgeGraphFile for a safe conditional write; omit it to fetch-and-overwrite the current version.

editKnowledgeGraphFile

Apply a batch of cell edits and/or a column reorder to an existing workbook. This is synchronous and writes directly to ClickHouse. For find/replace at scale, use nc_find_replace instead. Only pass columnOrder when reordering. 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_edit_workbook