Analyze the downstream impact of changing a node or a specific column.

Args: workspaceID: Workspace to query nodeID: Node to analyze impact for columnID: (optional) Specific column — if omitted, analyzes impact of the entire node

Returns: Impacted node count, impacted column count, nodes grouped by depth level, and the critical path (longest dependency chain from source to leaf). Without columnID: shows all downstream nodes and all columns across them that depend on any column of this node. With columnID: shows only nodes/columns that specifically depend on that column.

Requires a lineage cache — will fetch all workspace nodes with detail=true on first call.

Analyze workspace node patterns to detect package adoption, pipeline layers, data modeling methodology, and generate recommendations.

This performs a whole-workspace scan (summary-level, all nodes) and returns a compact profile. Use it for profiling/overview tasks, NOT for finding a specific node — for that use search_workspace_content or get_workspace_node. If you want a reusable local snapshot of full node bodies, use cache_workspace_nodes (an explicit full pull).

Args:

• workspaceID (string, required): The workspace ID to analyze

Returns: Workspace profile with package adoption, pipeline layers, naming conventions, and recommendations.

Write a FROM/JOIN/ON clause to a workspace node's sourceMapping.join.joinCondition by analyzing predecessor columns and generating the join automatically.

Use this for multi-predecessor nodes where you need to combine data via JOIN. The tool inspects predecessor columns, finds common column names for ON conditions, and writes the full joinCondition to the node.

Args:

• workspaceID (string, required): The workspace ID

• nodeID (string, required): The node ID of the multi-predecessor node

• joinType (enum, optional): 'INNER JOIN' | 'LEFT JOIN' | 'RIGHT JOIN' | 'FULL OUTER JOIN'. Defaults to INNER JOIN

• whereClause (string, optional): WHERE filter to append after the JOIN (without the WHERE keyword)

• qualifyClause (string, optional): QUALIFY clause to append (without the QUALIFY keyword)

• joinColumnOverrides (array, optional): Explicit column mappings when column names differ across predecessors. Each entry: { leftPredecessor, rightPredecessor, leftColumn, rightColumn }

Returns: { nodeID, joinCondition, warning?, validation? }

Round-trip a user's edits on a rendered DDL/DML SQL document back to the cloud workspace node it came from. Parses the SQL's column list, diffs it against the node's current metadata.columns[], and updates the node via set_workspace_node (unless dryRun: true). Both DDL and DML inputs feed the same node metadata — a DDL edit and a DML edit on the same node update the same metadata.columns[].

Column-level diff (structural changes — joins, CTEs, WHERE/GROUP BY, custom expressions on the join itself — are NOT reverse-engineered; those live in the node YAML):

• Removed columns (in YAML, missing in SQL) → dropped

• Type changes (matching name, different dataType) → updated in place; existing sources / columnReferences / lineage metadata is preserved

• Renamed columns (DML only — same transform, new AS alias) → renamed in place, lineage preserved (column id stays stable so downstream refs keep working). Detection requires unambiguous transform pairing; ambiguous cases fall back to drop+add.

• Expression-changed columns (DML only — same name, edited transform) → sources[].transform is updated and source-mapping inference is re-run to refresh columnReferences if the new transform references different upstream columns.

• New columns → for DML inputs, source-mapping inference resolves the column's transform against upstream predecessors (alias-prefix match, all-pred name fallback, multi-source COALESCE/GREATEST). For DDL inputs, new columns are added with empty columnReferences[] (DDL doesn't carry transforms); fill them in via the cloud UI.

Block-level diff (DML only — single-sourceMapping nodes):

• WHERE / ON-condition edits → written to sourceMapping[0].join.joinCondition with table refs rewritten to {{ ref('LOC', 'NAME') }} form.

• Adding or removing a predecessor source via SQL is REJECTED — add/remove the predecessor in the cloud UI first, then re-render.

Tail-clause diff (DML only):

• GROUP BY presence toggle → flips config.groupByAll. Coalesce derives the actual GROUP BY column list from non-aggregate columns at render time.

• ORDER BY adds / changes / removes → config.orderby flag and config.orderbycolumn.items[] array of {sortColName, sortOrder}.

• LIMIT adds / changes / removes → appended to / stripped from the trailing position of sourceMapping[0].join.joinCondition. Coalesce has no native limit config field for typical SQL nodes; the apply path warns when groupByAll/orderby is set (the auto-rendered tail clauses would land AFTER LIMIT, producing invalid SQL).

INSERT header diff (DML only — INSERT-shaped inputs):

• Target identifier change (INSERT INTO "DB"."LOC"."NAME") → updates the cloud node's top-level database / locationName / name fields. Renames/relocates the node; downstream references are unaffected (they use the node id, not the name).

• INSERT column list out-of-sync with the SELECT projection → REJECTED. Coalesce auto-generates the INSERT list from metadata.columns[]; edit the SELECT (using AS aliases) to add/rename/reorder columns.

Args:

• workspaceID (string, required)

• nodeID (string, required)

• sql (string, required): Either a CREATE [OR REPLACE] TABLE statement (DDL, from coa_dry_run_create) OR a SELECT/INSERT statement (DML, from coa_dry_run_run). The shape is auto-detected.

• dryRun (boolean, optional): If true, return the diff without writing.

Returns: { applied, dryRun, inputKind, diff: { unchanged, typeChanged, renamed, expressionChanged, removed, added }, joinDiff: { kind: 'identical' | 'whereOrJoinEdit' | 'newSource' | 'removedSource' | 'unsupported', ... }, tailDiff: { groupBy: { kind: 'identical' | 'added' | 'removed', ... }, orderBy: { kind: 'identical' | 'added' | 'changed' | 'removed', ... } }, limitDiff: { kind: 'identical' | 'added' | 'changed' | 'removed' | 'unsupported', ... }, insertHeaderDiff: { kind: 'identical' | 'targetChanged' | 'columnListMismatch' | 'notApplicable', ... }, body?, warnings?, error? }

Scan all nodes and columns in a workspace and report documentation coverage statistics.

Args: workspaceID: Workspace to audit

Returns: Total and documented counts for nodes and columns, percentage coverage, and lists of undocumented nodes and columns (column list capped at 200). A node is 'documented' if it has a non-empty description. A column is 'documented' if its metadata.columns[] entry has a non-empty description field.

Requires a lineage cache — will fetch all workspace nodes with detail=true on first call (may take a moment for large workspaces). Subsequent calls use the cached graph (default TTL: 30 min).

Build a Coalesce pipeline from a natural language description. Describe what you want in plain English and this tool resolves workspace nodes, selects node types, and creates the pipeline nodes.

Examples:

• "combine customers and orders by customer_id, aggregate total revenue by region"

• "stage the raw payments table"

• "join products with inventory on product_id"

The tool parses the intent, fuzzy-matches entity names to existing workspace nodes, and selects appropriate node types. When confirmed, it creates the pipeline nodes directly. Alternatively, set dryRun=true to get the plan without creating nodes, then pass it to create_pipeline_from_plan.

If entity names cannot be resolved or the intent is ambiguous, the tool returns clarification questions instead of a plan.

Fetch and cache all environment nodes to disk for efficient repeated access.

Args:

• environmentID (string, required): The environment ID

• detail (boolean, optional): Fetch expanded node details. Defaults to true

• pageSize (number, optional): API page size for collection. Defaults to 250, max 500

• orderBy (string, optional): Sort field for paginated collection. Defaults to id

• orderByDirection ('asc'|'desc', optional): Sort direction

Returns: Cache metadata with resourceUri (coalesce://cache/...) for accessing the cached data via MCP resource read.

Fetch and cache all organization users to disk for efficient repeated access.

Args:

• pageSize (number, optional): API page size for collection. Defaults to 250, max 500

• orderBy (string, optional): Sort field for paginated collection. Defaults to id

• orderByDirection ('asc'|'desc', optional): Sort direction

Returns: Cache metadata with resourceUri (coalesce://cache/...) for accessing the cached data via MCP resource read.

Fetch and cache runs to disk with optional filters for efficient repeated access.

Args:

• runType (enum, optional): Filter by 'deploy' or 'refresh'

• runStatus (enum, optional): Filter by 'completed' | 'failed' | 'canceled' | 'running' | 'waitingToRun'

• environmentID (string, optional): Filter by environment ID

• detail (boolean, optional): Fetch expanded run details. Defaults to false

• pageSize (number, optional): API page size for collection. Defaults to 250, max 500

• orderBy (string, optional): Sort field for paginated collection. Defaults to id

• orderByDirection ('asc'|'desc', optional): Sort direction

Returns: Cache metadata with resourceUri (coalesce://cache/...) for accessing the cached data via MCP resource read.

Fetch and cache the ENTIRE workspace's nodes to disk — a full snapshot of every node. Run this ONLY when the user explicitly wants the whole workspace cached. For targeted work, prefer search_workspace_content, get_workspace_node, or get_workspace_subgraph; for a profile use analyze_workspace_patterns. detail=false is much cheaper and sufficient for inventory; detail=true on a large workspace produces a very large snapshot. Note: the result is a coalesce://cache/... resource link, which clients that do not support MCP resources (e.g. Snowflake Cortex Code) cannot read.

Args:

• workspaceID (string, required): The workspace ID

• detail (boolean, optional): Fetch expanded node details. Defaults to true

• pageSize (number, optional): API page size for collection. Defaults to 250, max 500

• orderBy (string, optional): Sort field for paginated collection. Defaults to id

• orderByDirection ('asc'|'desc', optional): Sort direction

Returns: Cache metadata with resourceUri (coalesce://cache/...) for accessing the cached data via MCP resource read.

Cancel an in-progress Coalesce run. Destructive — the run will be terminated immediately. Canceling a running pipeline mid-execution can leave data in an inconsistent state (partial loads, half-transformed tables). There is no 'undo cancel'.

Args:

• runID (string, required): Numeric run ID to cancel

• environmentID (string, required): Environment the run belongs to

• orgID (string, optional): Organization ID. Falls back to COALESCE_ORG_ID env var or orgID in the active ~/.coa/config profile.

• confirmed (boolean, optional): Set to true after the user explicitly confirms cancellation

Returns: Confirmation with updated run status.

Clear the MCP server's local data cache. Removes all cached artifacts from disk.

Args:

• confirmed (boolean, optional): Set to true after the user explicitly confirms cache clearing

Returns: { deleted: boolean, fileCount: number, totalBytes: number, message: string }

Scaffold source-node YAML files from warehouse tables. Wraps coa sources add --json. Database and schema are read from the workspace's storage-location config and copied onto each scaffolded source node — no separate placeholders to fix up afterward, but verify the workspace config itself is correct first (the bootstrap tool seeds placeholders into it).

DESTRUCTIVE: writes files into the project's nodes/ tree. Requires confirmed: true. Existing source nodes are skipped unless overwrite: true.

MUST pass exactly one of location or all (the CLI enforces this in non-TTY mode and so do we).

DRY-RUN: pass dryRun: true to list what would be imported without writing files. The JSON shape is the same as a real write, with wouldImport reflecting the delta. confirmed: true is still required for consistency, but no files are created.

Profile resolution: input profile > COALESCE_PROFILE env > [default].

Usage pattern: call coa_list_warehouse_sources --location <name> first to preview, then call this with the same scope.

Args:

• projectPath (string, required)

• location (string) OR all (boolean): exactly one required

• include (string, optional): glob filter

• overwrite (boolean, optional): re-import existing nodes

• dryRun (boolean, optional): preview without writing

• profile (string, optional)

• confirmed (boolean): must be true to execute. Required even when dryRun: true, for consistency with other destructive tools — no files are written in that case.

Returns: { command, exitCode, stdout, stderr, json?, coaVersion }

Run coa doctor --fix — writes a starter workspaces.yml in the project root, seeded from locations.yml. Safe to re-run; coa will not overwrite a valid existing file.

IMPORTANT: the generated file contains placeholder database/schema values. The user MUST open it and set real values before running coa_create / coa_run — otherwise warehouse operations will target non-existent databases.

KNOWN ISSUE (CD-16983): the workspaces.yml profile controls coa create/run, but coa plan/deploy/refresh fall through to [default] in ~/.coa/config. After bootstrap, check that the two profiles point at the same cloud account before relying on plan/deploy results.

DESTRUCTIVE: writes a new file to the project directory. Requires confirmed=true after explicit user approval.

Args:

• projectPath (string, required): Path to the COA project root (directory with data.yml)

• workspace (string, optional): workspaces.yml workspace name (default: dev)

• confirmed (boolean): must be true to execute

Returns: { command, exitCode, stdout, stderr, json?, coaVersion }

Execute coa create — runs DDL (CREATE/REPLACE) for the selected nodes against the configured warehouse.

DESTRUCTIVE: modifies warehouse schema. Requires confirmed=true after explicit user approval.

Pre-flight checks run before execution (double-quoted refs, missing workspaces.yml, bad selector patterns). Errors block execution; warnings are returned alongside the result.

V2 NOTICE: when the project contains V2 artifacts (fileVersion: 2 node types or .sql nodes), a V2_DETECTED preflight warning attaches to the result. Execution is no longer blocked — annotation sync (CD-16972) and UNION ALL shipped in COA 7.35 closed the biggest V2 risks. Two rough edges remain: coa validate false positives on aliased columns, and zero-column CTAS when a SELECT has a parse error. See coalesce://context/sql-node-v2-policy.

Args:

• projectPath (string, required)

• workspace, include, exclude (optional)

• confirmed (boolean): must be true to execute

Returns: { command, exitCode, stdout, stderr, preflightWarnings?, coaVersion }

Apply a plan JSON to a cloud environment. Changes environment schema/state.

DESTRUCTIVE: modifies the deployed environment. Requires confirmed=true.

The plan file must exist (produced by coa_plan). Does NOT re-validate project contents — validates the plan structure only.

Args:

• environmentID (string, required)

• plan (string, required): path to coa-plan.json

• profile, token (optional)

• confirmed (boolean): must be true to execute

Returns: { command, exitCode, stdout, stderr, coaVersion }

Fetch a section of COA's self-describing documentation. Wraps coa describe <topic> [<subtopic>].

Well-known topics (also available as coalesce://coa/describe/* resources): overview, commands, selectors, schemas, workflow, structure, concepts, sql-format, node-types, config.

Use subtopic for the parameterized topics:

• topic='command', subtopic='' — deep-dive on a specific command

• topic='schema', subtopic='' — full JSON schema for a file type

Args:

• topic (string, required)

• subtopic (string, optional)

• refresh (boolean, optional): bypass the on-disk cache and re-run COA

Returns: { topic, subtopic?, source (memory|disk|coa), content, coaVersion }

Run coa doctor against a local COA project — checks data.yml, workspaces.yml, credentials, and warehouse connectivity.

KNOWN ISSUE (CD-16983): doctor reports the profile selected via workspaces.yml / --workspace, but coa_plan / coa_deploy / coa_refresh resolve profile differently — they fall through to the [default] profile in ~/.coa/config unless --profile or COALESCE_PROFILE is set. A green doctor result does NOT guarantee that plan/deploy will authenticate against the same cloud account. When a user reports plan/deploy auth mismatches, suspect profile divergence before blaming credentials. Platform fix approach still under discussion.

Args:

• projectPath (string, required): Path to the COA project root (directory with data.yml)

• workspace (string, optional): workspaces.yml workspace name (default: dev)

Returns: { command, exitCode, stdout, stderr, timedOut, json?, coaVersion, preflightWarnings? }

Preview the DDL that coa create would execute, without hitting the warehouse. Forces --dry-run --verbose.

Runs entirely offline against local project files — no Coalesce cloud authentication or API calls. coa create (and coa run) are the offline local-dev commands; do not confuse with the scheduler-aware coa deploy / coa plan / coa refresh which target cloud environments.

OUTPUT SHAPE (CD-16959+): dry-run reports pass/fail for every selected node rather than stopping at the first template error. Scan the full stdout — a non-zero exit code means one or more nodes failed, but successful nodes still render their generated SQL above/below the failures. Do not assume early output implies all-clear.

Check the stdout: table names should resolve (not blank), column types should not be UNKNOWN (indicates broken ref() targets), and SQL should look correct. For V2 nodes specifically, watch for CREATE TABLE ... AS SELECT WHERE 1=0 with zero columns — this means the SELECT has a parse error and the dry-run reports success despite producing broken DDL. See coalesce://context/sql-node-v2-policy.

LIMITATION: dry-run only exercises the SQL generator. It does NOT validate that referenced columns or types exist in the actual warehouse — a dry-run can succeed with column references that will fail at run-time with 'invalid identifier'. Use cortex or another Snowflake-capable MCP to confirm the schema when that matters.

Args:

• projectPath (string, required)

• workspace (string, optional)

• include / exclude (string, optional): Node selector

Returns: { command, exitCode, stdout, stderr, coaVersion }

Preview the DML that coa run would execute, without hitting the warehouse. Forces --dry-run --verbose.

Runs entirely offline against local project files — no Coalesce cloud authentication or API calls. coa run (and coa create) are the offline local-dev commands; do not confuse with the scheduler-aware coa deploy / coa plan / coa refresh which target cloud environments.

OUTPUT SHAPE (CD-16959+): dry-run reports pass/fail for every selected node rather than stopping at the first template error. Scan the full stdout — a non-zero exit code means one or more nodes failed, but successful nodes still render their generated SQL above/below the failures.

LIMITATION: dry-run only exercises the SQL generator. It does NOT validate that referenced columns or types exist in the actual warehouse — a dry-run can succeed with column references that will fail at run-time with 'invalid identifier'. Use cortex or another Snowflake-capable MCP to confirm the schema when that matters.

Args:

• projectPath (string, required)

• workspace (string, optional)

• include / exclude (string, optional): Node selector

Returns: { command, exitCode, stdout, stderr, coaVersion }

List all nodes defined in a local COA project (pre-deploy). Wraps coa create --list-nodes.

Different from list_environment_nodes (which lists deployed nodes in a cloud environment via the REST API).

Args:

• projectPath (string, required)

• workspace (string, optional)

Returns: { command, exitCode, stdout, json?, coaVersion }

List warehouse tables visible to each storage location in a COA project. Wraps coa sources list --json.

Three modes via flags:

• Neither location nor all: returns per-location SUMMARY counts (totalTables, importedTables, newTables). Cheap; use this first on unfamiliar projects.

• location: <name>: returns per-table detail for that one location, each row marked alreadyExists: true if a source node has already been scaffolded for it.

• all: true: per-table detail for every location. Potentially large — prefer scoping when you can.

Use this to (a) figure out which locations have un-imported tables before calling coa_add_warehouse_sources, or (b) audit which scaffolded source nodes still match the warehouse.

Read-only: queries the warehouse via the COA cloud profile, writes nothing. Profile resolution: input profile > COALESCE_PROFILE env > [default].

Args:

• projectPath (string, required)

• location (string, optional)

• all (boolean, optional): mutually exclusive with location

• include (string, optional): glob filter on table names

• profile (string, optional)

Returns: { command, exitCode, stdout, stderr, json?, coaVersion }

Generate a deployment plan. Reads the local project, diffs against the target environment, and writes a plan JSON (default coa-plan.json in the project root).

Non-destructive: produces a plan file only. Safe to call without confirmation. The plan is then applied via coa_deploy.

Requires COA cloud credentials (~/.coa/config or profile/token) and an environmentID.

V2 NOTICE: when the project contains V2 artifacts, a V2_DETECTED preflight warning attaches to the result (same shape as coa_create / coa_run). Execution is not blocked; see coalesce://context/sql-node-v2-policy for the two remaining rough edges.

Args:

• projectPath (string, required)

• environmentID (string, required)

• out (string, optional): plan output path

• gitsha, enableCache (optional)

• profile, token (optional)

Returns: { command, exitCode, stdout, stderr, preflightWarnings?, coaVersion }

Run DML for selected nodes in a deployed environment. Does not require a local project — operates purely on the cloud environment.

DESTRUCTIVE: modifies warehouse data in the environment. Requires confirmed=true.

Args:

• environmentID (string, required)

• include, exclude, jobID, parallelism, parameters (optional)

• forceIgnoreEnvironmentStatus (optional)

• profile, token (optional)

• confirmed (boolean): must be true to execute

Returns: { command, exitCode, stdout, stderr, coaVersion }

Delete scaffolded source-node YAML files from the project. Wraps coa sources remove --json --yes (the MCP layer handles confirmation; --yes is always passed to the CLI).

DESTRUCTIVE: removes files from disk. Requires confirmed: true. Hand-renamed ("unmanaged") files are reported but NOT removed — the CLI considers them user-owned.

MUST pass exactly one of location or all.

PROFILE LIMITATION: unlike list/add, the underlying coa sources remove does NOT accept a --profile flag in COA 7.35 (errors unknown option '--profile'). Profile resolution falls back to [default] in ~/.coa/config. If that diverges from the agent's intended profile, the agent should temporarily set [default] or wait for the upstream patch.

Usage pattern: when re-onboarding a location or cleaning up after a schema rename. Pair with coa_list_warehouse_sources to confirm scope first.

Args:

• projectPath (string, required)

• location (string) OR all (boolean): exactly one required

• include (string, optional): glob filter (e.g. 'OLD_*')

• confirmed (boolean): must be true to execute

Returns: { command, exitCode, stdout, stderr, json?, coaVersion }

Execute coa run — runs DML (INSERT/MERGE) to populate the selected nodes.

DESTRUCTIVE: modifies warehouse data. Requires confirmed=true.

Same pre-flight checks as coa_create. A V2_DETECTED preflight warning attaches for V2 projects but does not block execution (see coa_create for the V2 NOTICE). Uses a 30-minute timeout.

Args:

• projectPath (string, required)

• workspace, include, exclude (optional)

• confirmed (boolean): must be true to execute

Returns: { command, exitCode, stdout, stderr, preflightWarnings?, coaVersion }

Run coa validate — scans a project's YAML schemas, storage locations, column references, and types.

Known issue: V2 SQL nodes may produce false-positive column reference errors from the Column References scanner. Those don't block coa_dry_run_create / coa_dry_run_run.

Args:

• projectPath (string, required)

• workspace (string, optional)

• include / exclude (string, optional): Node selector

Returns: { command, exitCode, stdout, stderr, json?, coaVersion }

Run intelligent configuration completion on a workspace node. Analyzes the node's type definition, existing config, and column layout to fill in required and recommended configuration fields.

Both creation tools call this internally, but you can invoke it separately after manual edits.

Args:

• workspaceID (string, required): The workspace ID

• nodeID (string, required): The node ID

• repoPath (string, optional): Local repo path for type definition lookup

Returns: { nodeID, configCompletion? | configCompletionSkipped? }

Convert an existing join node into an aggregated fact table with GROUP BY. This is the REQUIRED follow-up after creating a multi-predecessor node — it completes the join setup.

This tool automatically:

• Generates JOIN ON clauses from common columns between predecessors

• Writes the complete FROM/JOIN/ON/GROUP BY clause to the node's joinCondition (no separate update needed)

• Replaces columns with GROUP BY dimensions + aggregate measures

• Infers datatypes from transform functions (COUNT → NUMBER, SUM → NUMBER(38,4), etc.)

• Sets column-level attributes (isBusinessKey on GROUP BY columns, isChangeTracking on aggregates)

• Validates that all non-aggregate columns are in GROUP BY

• Runs intelligent config completion

Use this to transform a simple join (row-level) into an aggregated fact table (summary-level).

Example: Convert order detail join to customer metrics: { workspaceID: "1", nodeID: "fact-node-id", groupByColumns: ['"STG_ORDER_HEADER"."CUSTOMER_ID"'], aggregates: [ { name: "TOTAL_ORDERS", function: "COUNT", expression: 'DISTINCT "STG_ORDER_HEADER"."ORDER_ID"' }, { name: "LIFETIME_VALUE", function: "SUM", expression: '"STG_ORDER_HEADER"."ORDER_TOTAL"' }, { name: "AVG_ORDER_VALUE", function: "AVG", expression: '"STG_ORDER_HEADER"."ORDER_TOTAL"' } ], joinType: "INNER JOIN" }

Args:

• workspaceID (string, required): The workspace ID

• nodeID (string, required): The node ID of the join to convert

• groupByColumns (string[], required): Columns to group by (dimensions)

• aggregates (array, required): Aggregate columns with functions and expressions

• joinType (string, optional): JOIN type (default: INNER JOIN)

• maintainJoins (boolean, optional): Generate JOINs (default: true)

• repoPath (string, optional): Local repo path for config completion

Returns: Updated node with new columns, joinCondition, GROUP BY analysis, and config completion results.

Create a new Coalesce environment within a project.

Args:

• projectID (string, required): The project to create the environment in

• name (string, required): Name for the new environment

• oauthEnabled (boolean, optional): Enable OAuth (default: false)

• devEnv (boolean, optional): Mark as development environment (default: false)

• connectionAccount (string, optional): Connection account identifier

• runTimeParameters (object, optional): Runtime parameters for the environment

• tagColors (object, optional): UI tag colors { backgroundColor, textColor }

Returns: Created environment object with assigned ID.

Create a new Git account in Coalesce.

Args:

• name (string, required): Account name

• gitUsername (string, required): Git username for authentication

• gitAuthorName (string, required): Author name for git commits

• gitAuthorEmail (string, required): Email address for git commits

• gitToken (string, required): Personal access token for the git provider

• provider (enum, optional): 'github' | 'gitlab' | 'bitbucket' | 'azureDevOps'

• accountOwner (string, optional): User ID of the account owner

Returns: Created Git account with assigned ID.

Create a workspace node whose output columns match an external table schema (e.g., from Snowflake DESCRIBE TABLE, dbt manifest, or any metadata source).

This tool automates the workflow of:

1. Creating a node from predecessor(s) (auto-populates columns from source)

2. Reconciling auto-populated columns against the external target schema

3. Replacing columns to match the external schema exactly

Reconciliation logic:

• Matched columns (by name): Preserves source linkage from predecessor, overrides dataType to match external schema

• New columns (in target but not predecessor): Added without source mapping, flagged as needing a transform

• Dropped columns (in predecessor but not target): Removed from the node

The response includes a reconciliation object showing exactly what was matched, added, dropped, and which types changed.

REQUIRED: Call plan_pipeline first to discover the correct nodeType.

Args:

• workspaceID (string, required): The workspace ID

• nodeType (string, required): Node type from plan_pipeline

• predecessorNodeIDs (string[], required): One or more predecessor node IDs

• targetColumns (array, required): External column definitions to match

• targetName (string, optional): Name for the new node (e.g., 'STG_ORDER_HEADER')

• locationName (string, optional): Storage location name

• repoPath (string, optional): Local repo path for config completion

• goal (string, optional): Intent for node type validation

Returns: { node, reconciliation: { matched, added, dropped, typeChanges }, predecessors, validation, configCompletion?, configCompletionSkipped?, nodeTypeValidation?, nextSteps }

Create a Coalesce pipeline from a previously approved plan. Pass the exact plan object returned by plan_pipeline. Projection-capable node types execute by creating predecessor-based nodes first and then persisting the final full node body via set_workspace_node.

Args:

• workspaceID (string, required): The workspace ID

• plan (object, required): The exact plan object returned by plan_pipeline

• confirmed (boolean, optional): Set to true after user approves the plan. Must be paired with confirmationToken

• confirmationToken (string, optional): Token from prior STOP_AND_CONFIRM response. Required when confirmed=true

• dryRun (boolean, optional): When true, validate without creating nodes

Returns: { created: boolean, nodes?: CreatedNode[], warnings?: string[] }

Plan and create a Coalesce pipeline from user-provided SQL. Pass the user's EXACT SQL unchanged. The SQL may use raw table names or already contain Coalesce {{ ref() }} syntax if that is what the user provided. Do NOT rewrite between styles or otherwise modify the query. The planner resolves workspace sources automatically and generates a Coalesce-compatible joinCondition for the final node.

If you are building a pipeline yourself, use declarative tools directly: create_workspace_node_from_predecessor → convert_join_to_aggregation → replace_workspace_node_columns.

This tool validates candidate node types against currently observed workspace nodes. If a selected type is not observed, the plan will include a warning asking the user to confirm installation in Coalesce.

Consult coalesce://context/node-type-corpus for node type patterns and metadata structures.

Create a new Coalesce project.

Args:

• name (string, required): Project name

• platformKind (enum, required): Target platform — 'snowflake', 'databricks', 'starburst', or 'spark'

• description (string, optional): Project description

• gitAccountID (string, optional): Git account to link

• gitRepo (string, optional): Git repository URL

• gitBranch (string, optional): Default git branch

Returns: Created project object with assigned ID.

Create a new job in a Coalesce workspace. Jobs define which nodes to run together.

Args:

• workspaceID (string, required): The workspace ID

• name (string, required): Job name

• includeSelector (string, required): Node selector. Format: '{ location: LOC name: NAME } OR { location: LOC name: NAME }'. Use empty string to include nothing

• excludeSelector (string, required): Node exclusion selector. Same format as includeSelector. Use empty string to exclude nothing

Returns: Created job with assigned ID.

Create a workspace node from one or more predecessor nodes, fetch it, and verify that columns were auto-populated from those predecessors before applying any optional changes.

SINGLE-CALL WORKFLOW: You can create a node AND apply column transforms, WHERE filters, or aggregation in one call:

• columns + whereCondition: Replace auto-populated columns with specific transforms and add a WHERE filter — no separate replace_workspace_node_columns needed

• groupByColumns + aggregates: Convert to an aggregation node with GROUP BY — no separate convert_join_to_aggregation needed These are mutually exclusive: use columns OR groupByColumns+aggregates, not both.

REQUIRED: Before calling this tool, call plan_pipeline with goal, sourceNodeIDs, and repoPath to discover and rank available node types. Use the nodeType from the plan result — do NOT guess or hardcode node types like 'Stage', 'View', or numeric IDs like '65'. The planner scans all committed node type definitions and scores them against your use case.

SPECIALIZED TYPES WARNING: Do NOT use Dynamic Tables, Incremental Load, Materialized View, or other specialized types unless the user explicitly requests that pattern (e.g., 'near-real-time refresh', 'continuous refresh', 'incremental processing'). For standard batch ETL, CTE decomposition, and general transforms, use Stage or Work. The response includes nodeTypeValidation.warning if a specialized pattern was detected without matching context — always check this field.

JOIN INTELLIGENCE: For multi-predecessor nodes (joins), this tool automatically:

• Analyzes common columns between each predecessor pair

• Returns joinSuggestions with normalized column names and their left/right counterparts

• Reports which predecessors are represented in the resulting column references

• Warns if any predecessor is missing from the auto-populated columns

AUTOMATIC CONFIG: When repoPath is provided, this tool automatically runs intelligent config completion after creation — reading the node type definition, setting node-level config defaults, and applying column-level attributes (isBusinessKey, isChangeTracking, etc.). The configCompletion result shows what was applied.

Do not use overrideSQL or override.* fields; SQL override is disallowed in this project.

For guidance on node types, storage locations, and SQL patterns, see resources: coalesce://context/data-engineering-principles, coalesce://context/storage-mappings, coalesce://context/sql-platform-selection

Args:

• workspaceID (string, required): The workspace ID

• nodeType (string, required): Node type from plan_pipeline

• predecessorNodeIDs (string[], required): One or more predecessor node IDs

• changes (object, optional): Partial fields to apply after creation

• columns (array, optional): Replace auto-populated columns (mutually exclusive with groupByColumns)

• whereCondition (string, optional): WHERE filter (only with columns)

• groupByColumns (string[], optional): GROUP BY columns (with aggregates)

• aggregates (array, optional): Aggregate columns (with groupByColumns)

• joinType (string, optional): JOIN type for multi-predecessor aggregation

• repoPath (string, optional): Local repo path for config completion

• goal (string, optional): Intent for node type validation

Returns: { nodeID, created, joinSuggestions?, nodeTypeValidation?, configCompletion? }

Create a workspace node from scratch with NO predecessors. Only use this when the node truly has no upstream nodes — for example, a standalone utility node. If the node has ANY upstream/source nodes, use create_workspace_node_from_predecessor instead.

REQUIRED: Before calling this tool, call plan_pipeline with goal + repoPath to discover the correct nodeType. Do not guess or hardcode node types — the planner ranks all available types and returns the best match.

SPECIALIZED TYPES WARNING: Do NOT use Dynamic Tables, Incremental Load, Materialized View, or other specialized types unless the user explicitly requests that pattern (e.g., 'near-real-time refresh', 'incremental processing'). For standard batch ETL, CTE decomposition, and general transforms, use Stage or Work. The response includes nodeTypeValidation.warning if a specialized pattern was detected without matching context.

Defaults to completionLevel='configured', which REQUIRES both name and metadata.columns to be provided. If you don't have column definitions yet, set completionLevel to 'created' or 'named' instead.

AUTOMATIC CONFIG: When repoPath is provided, this tool automatically runs intelligent config completion after creation — reading the node type definition, setting node-level config defaults, and applying column-level attributes. The configCompletion result shows what was applied.

Do not use overrideSQL or override.* fields; SQL override is disallowed in this project.

Create a subgraph in a Coalesce workspace. Subgraphs group nodes visually. The assigned UUID is cached locally so future edits can reference the subgraph by name.

Args:

• workspaceID (string, required): The workspace ID

• name (string, required): Subgraph name

• steps (string[], required): Array of node IDs to include

Returns: { subgraphID, subgraph, cached, message } — subgraphID is the UUID; cache it if you need to edit this subgraph later.

Permanently delete a Coalesce environment. This is destructive and cannot be undone.

Args:

• environmentID (string, required): The environment ID to delete

• confirmed (boolean, optional): Set to true after the user explicitly confirms deletion

Returns: Confirmation message.

Remove a user's role from a specific environment. Destructive — the user will lose environment access immediately.

Args:

• userID (string, required): The user ID

• environmentID (string, required): The environment ID

• confirmed (boolean, optional): Set to true after the user explicitly confirms the role removal

Returns: Confirmation message.

Permanently delete a Git account. Destructive and cannot be undone — if this is the only git account linked to a project, it breaks the CI/CD connection.

Args:

• gitAccountID (string, required): The account ID

• accountOwner (string, optional): User ID of the account owner

• confirmed (boolean, optional): Set to true after the user explicitly confirms deletion

Returns: Confirmation message.

Permanently delete a Coalesce project. This is destructive and cannot be undone.

Args:

• projectID (string, required): The project ID

• confirmed (boolean, optional): Set to true after the user explicitly confirms deletion

Returns: Confirmation message.

Remove a user's role from a specific project. Destructive — the user will lose project access immediately.

Args:

• userID (string, required): The user ID

• projectID (string, required): The project ID

• confirmed (boolean, optional): Set to true after the user explicitly confirms the role removal

Returns: Confirmation message.

Delete a job from a workspace. Destructive — jobs define which nodes run together; deleting the wrong one breaks scheduled pipelines.

Args:

• workspaceID (string, required): The workspace ID

• jobID (string, required): The job ID

• confirmed (boolean, optional): Set to true after the user explicitly confirms deletion

Returns: Confirmation message.

Permanently delete a workspace node. Destructive — check for downstream dependencies first. Before mutating, the tool resolves the node via get_workspace_node and blocks the delete if the ID does not exist.

Args:

• workspaceID (string, required): The workspace ID

• nodeID (string, required): The node ID

• confirmed (boolean, optional): Set to true after the user explicitly confirms deletion

Returns: Confirmation message plus the resolved node name.

Delete a subgraph from a workspace. Destructive — the subgraph is removed but its member nodes are NOT deleted. Pass either subgraphID (preferred) or subgraphName with optional repoPath.

Args:

• workspaceID (string, required): The workspace ID

• subgraphID (string, optional): The subgraph ID. Preferred when known.

• subgraphName (string, optional): The subgraph name. Resolved via cache → repo when subgraphID is absent (the Coalesce API has no subgraph list endpoint).

• repoPath (string, optional): Coalesce repo path for subgraph YAML lookup.

• confirmed (boolean, optional): Set to true after the user explicitly confirms deletion

Returns: Confirmation message.

Diagnose a failed Coalesce run. Fetches run metadata and per-node results, classifies each failure (SQL error, missing object, permission issue, data type mismatch, timeout, configuration error), and returns actionable fix suggestions.

Use this when a run has failed and the user wants to understand what went wrong and how to fix it. Works best with completed (failed) runs — for in-progress runs, use run_status instead.

Returns: run summary, per-node failure diagnosis with error classification, and prioritized recommendations.

Stateless probe that reports which first-time-setup pieces are configured: Coalesce access token, Snowflake credentials (for run tools + coa_create/coa_run), local repo path + whether it's a COA project, and a best-effort coa doctor check when applicable.

Returns a structured report plus ordered nextSteps. Use this during or after the /coalesce-setup prompt flow to confirm progress between phases.

Never throws. Safe to call repeatedly.

Returns: { accessToken: { status, ... }, snowflakeCreds: { status, ... }, repoPath: { status, ... }, coaDoctor: { status, ... }, nextSteps: string[], ready: boolean }

Fuzzy-match jobs in an environment by name (case-insensitive substring), and return each match with its most recent runs. Use this when the user references a job by name and you need the job's ID or recent execution history.

Scans the last 50 runs in the environment and groups them by matched job. Runs that fall outside that window are not returned — for older history call list_runs with explicit pagination.

Args:

• environmentID (string, required): The environment ID

• jobName (string, required): Substring to match (case-insensitive)

• runLimitPerJob (integer, optional): Max recent runs per matched job (default 5)

Returns: { matches: [{ job: {id, name, includeSelector, excludeSelector}, recentRuns: [{runID, runCounter, runStatus, runType, runStartTime, runEndTime}] }], summary: { jobsMatched, totalRunsReturned, runScanLimit } }

Generate a YAML-friendly set_workspace_node body template either from a raw node definition object or by resolving a committed node type from a local repo. Prefer repo mode when a local committed repo contains the definition; use the corpus tools when repo-backed resolution is unavailable. SQL override controls are removed from returned templates because they are disallowed in this project.

Generate a set_workspace_node body template from a node-type corpus variant stored in the committed snapshot. This avoids requiring the original external node source repo at runtime, rejects partial variants unless allowPartial=true, and can optionally compare the inferred template against a live workspace node. SQL override controls are removed from returned templates because they are disallowed in this project.

Trace a specific column through the entire pipeline — upstream to its sources and downstream to every column that depends on it.

Args: workspaceID: Workspace to query nodeID: Node that contains the column columnID: Column ID to trace

Returns: Array of column lineage entries with nodeID, nodeName, nodeType, columnID, columnName, direction (upstream/downstream), and depth. Uses column-level references (metadata.columns[].sources[].columnReferences[]) to trace the full path.

Requires a lineage cache — will fetch all workspace nodes with detail=true on first call.

Walk the full downstream dependency graph for a node and return every dependent with its depth level.

Args: workspaceID: Workspace to query nodeID: Starting node whose downstream dependents to trace

Returns: Array of dependent nodes with nodeID, nodeName, nodeType, and depth (1 = direct child). Traverses the entire graph with no depth limit. Nodes are deduplicated.

Requires a lineage cache — will fetch all workspace nodes with detail=true on first call.

Get details of a specific Coalesce environment by ID.

Returns full environment configuration including connection details, runtime parameters, and tag colors.

Args:

• environmentID (string, required): The environment ID

Returns: Full environment object with ID, name, project, connection settings, and configuration.

Get a comprehensive health dashboard for a deployed environment. Composes multiple API calls into a single health summary.

This tool paginates through all environment nodes and all environment runs before scoring health, so it may take longer on large or busy environments.

Args:

• environmentID (string, required): The environment ID

Returns: { environmentID, assessedAt, totalNodes, nodesByType: { Stage: 5, Dimension: 3, ... }, nodeRunStatus: [{ nodeID, nodeName, lastRunStatus, lastRunTime }], failedRunsLast24h: [{ runID, runStatus, startTime, endTime }], staleNodes: [{ nodeID, nodeName, nodeType, lastRunTime, daysSinceLastRun }], dependencyHealth: { orphanNodes: [...], totalDependencyEdges }, healthScore: "healthy" | "warning" | "critical", healthReasons: ["..."] }

Get details of a specific job in an environment.

Args:

• environmentID (string, required): The environment ID

• jobID (string, required): The job ID

Returns: Job object with name, node list, schedule, and configuration.

Get details of a specific node deployed in an environment.

Args:

• environmentID (string, required): The environment ID

• nodeID (string, required): The node ID

Returns: Full node object with columns, config, metadata, and deployment state.

Get environment details and all its deployed nodes in a single call.

Args:

• environmentID (string, required): The environment ID

Returns: { environment: EnvironmentObject, nodes: NodeObject[] }

Get details of a specific Git account.

Args:

• gitAccountID (string, required): The Git account ID

• accountOwner (string, optional): User ID of the account owner

Returns: Git account object with connection details.

Fuzzy-match a single environment job by name and return the full details of its most recent run (and optionally run results). Errors if the name matches zero or multiple jobs — use find_jobs_by_name first to disambiguate.

Looks at the last 50 runs in the environment to find the job's latest run. Older runs are not considered.

Args:

• environmentID (string, required): The environment ID

• jobName (string, required): Substring to match (case-insensitive). Must match exactly one job.

• includeResults (boolean, optional): Include per-node run results (default true)

Returns: { job, run, results? }

Get one node-type corpus variant from the committed snapshot by variantKey. Use search_node_type_variants first when you need discovery.

Get the current state of a pipeline workshop session, including all planned nodes, their configuration, and the instruction history.

Get details of a specific Coalesce project.

Args:

• projectID (string, required): The project ID

• includeWorkspaces (boolean, optional): Include nested workspace data

• includeJobs (boolean, optional): Include nested job data

Returns: Full project object with ID, name, description, git configuration.

Resolve one exact node type from a committed local Coalesce repo. Supports direct identifiers like Stage or 65 and package-backed identifiers like alias:::id. If the repo cannot resolve the definition exactly, use the corpus tools as the fallback path.

Get details of a specific Coalesce run.

Args:

• runID (string, required): Numeric run ID (integer, e.g. '401'). Use the runCounter value from start_run or run_status — not the UUID from run URLs.

Returns: Full run object with status, timing, node results, and configuration.

Get run metadata and execution results in a single call. Combines get_run and get_run_results.

Args:

• runID (string, required): Numeric run ID (integer). Use runCounter, not the UUID.

Returns: { run: RunObject, results: ResultsObject, resultsError?: ErrorObject }

Get the execution results of a specific Coalesce run.

Args:

• runID (string, required): Numeric run ID (integer). Use runCounter, not the UUID.

Returns: Run results including per-node execution status, row counts, and errors.

Walk the full upstream dependency graph for a node and return every ancestor with its depth level.

Args: workspaceID: Workspace to query nodeID: Starting node whose upstream lineage to trace

Returns: Array of ancestor nodes with nodeID, nodeName, nodeType, and depth (1 = direct parent). Traverses the entire graph with no depth limit. Nodes are deduplicated.

Requires a lineage cache — will fetch all workspace nodes with detail=true on first call (may take a moment for large workspaces). Subsequent calls use the cached graph (default TTL: 30 min).

Get roles assigned to a specific user, optionally scoped to a project or environment.

Args:

• userID (string, required): The user ID

• projectID (string, optional): Scope to a specific project

• environmentID (string, optional): Scope to a specific environment

Returns: Role assignments for the user.

Get details of a specific Coalesce workspace by ID.

Args:

• workspaceID (string, required): The workspace ID

Returns: Full workspace object with ID, name, project association, and settings.

Get details of a specific node in a workspace. Use list_workspaces to find workspace IDs.

Args:

• workspaceID (string, required): The workspace ID

• nodeID (string, required): The node ID

Returns: Full workspace node with columns, transforms, joins, config, and metadata.

Get details of a specific subgraph.

Args:

• workspaceID (string, required): The workspace ID

• subgraphID (string, required): The subgraph ID

Returns: Subgraph object with name and node steps.

List all jobs deployed to a Coalesce environment. Jobs define which nodes run together — pair this with list_environment_nodes when planning a refresh, or with create_workspace_job when authoring new schedules.

Different from listing workspace-side jobs: this returns the jobs currently deployed to the target environment (what the scheduler will execute), not the in-flight workspace edits that may not be deployed yet.

Args:

• environmentID (string, required): The environment ID

• limit, startingFrom, orderBy, orderByDirection: Pagination

Returns: { data: Job[], next?: string, total?: number }

List nodes deployed in a Coalesce environment. Returns ONE page (default 100 nodes, or 25 when detail=true). If the response has hasMore: true, you have NOT seen all nodes — you must page (call again with startingFrom set to the returned next, same orderBy) before drawing any conclusion about the environment, or you will undercount it. When you know the node, prefer get_environment_node by ID rather than paging.

Args:

• environmentID (string, required): The environment ID

• detail (boolean, optional): Include full node details

• limit, startingFrom, orderBy, orderByDirection: Pagination (limit defaults to 100, or 25 when detail=true)

Returns: { data: Node[], next?: string, hasMore?: boolean, retrieved?: number }

List all available Coalesce environments with optional pagination.

Returns environment IDs, names, and configuration. Use this to discover environment IDs needed by run, node, and job tools.

Args:

• limit (number, optional): Max results per page

• startingFrom (string, optional): Pagination cursor from previous response

• orderBy (string, optional): Sort field (requires startingFrom)

• orderByDirection ('asc'|'desc', optional): Sort direction

• detail (boolean, optional): Include expanded environment configuration

Returns: { data: Environment[], next?: string, total?: number }

Use get_environment for a single environment by ID.

List all Git accounts configured in Coalesce.

Args:

• accountOwner (string, optional): User ID of the account owner. Org admins can manage other users' accounts

Returns: { data: GitAccount[], next?: string, total?: number }

Resolve a workspace job's selectors into concrete workspace nodes, grouped by subgraph. Composes getWorkspaceJob + listWorkspaceNodes + the local repo's subgraphs/ folder to evaluate the includeSelector/excludeSelector DSL (supported clauses: { subgraph: NAME } and { location: LOC name: NAME }, joined by OR).

Subgraph resolution note: the public Coalesce API has no subgraph list endpoint. { subgraph: NAME } terms can only be resolved when repoPath is set (or COALESCE_REPO_PATH). Without a repo, such terms land in unresolved and a warning is added to summary.warnings.

Args:

• workspaceID (string, required): The workspace that owns the job

• jobID (string, optional): The job ID. Preferred when known.

• jobName (string, optional): The job name. Resolved against workspace jobs when jobID is absent.

• repoPath (string, optional): Coalesce repo path for subgraph YAML lookup. Falls back to COALESCE_REPO_PATH or the coa profile.

Returns: { job: { id, name, includeSelector, excludeSelector }, summary: { totalNodes, subgraphCount, unattachedCount, unresolvedCount, warnings }, nodesBySubgraph: [{ subgraphID, subgraphName, nodes: [{ id, name, location, nodeType }] }], unattached: [...], // nodes matched by the job but not in any subgraph unresolved: [{ term, reason }] // selector terms that matched nothing (stale selectors or missing repoPath) }

List all users in the Coalesce organization.

Args:

• limit, startingFrom, orderBy, orderByDirection: Pagination controls

Returns: { data: User[], next?: string, total?: number }

List all Coalesce projects.

Args:

• includeWorkspaces (boolean, optional): Include nested workspace data

• includeJobs (boolean, optional): Include nested job data for all workspaces

Returns: { data: Project[], next?: string, total?: number }

Inspect a committed local Coalesce repo and list exact resolvable node-type identifiers from nodeTypes/, optionally filtered to one package alias. Repo-backed discovery is preferred when the repo contains the committed definition; otherwise use the corpus tools.

Inspect a committed local Coalesce repo and list package aliases from packages/*.yml. Use this when a local repo is available and you want repo-backed node-type discovery before falling back to the corpus.

List Coalesce runs with optional filters for type, status, and environment.

Args:

• runType ('deploy'|'refresh', optional): Filter by type

• runStatus ('completed'|'failed'|'canceled'|'running'|'waitingToRun', optional): Filter by status

• environmentID (string, optional): Filter by environment

• detail (boolean, optional): Include full run details

• limit, startingFrom, orderBy, orderByDirection: Pagination controls

Returns: { data: Run[], next?: string, total?: number }

List roles for all users in the organization, optionally scoped.

Args:

• projectID (string, optional): Scope to a project

• environmentID (string, optional): Scope to an environment

Returns: { data: RoleAssignment[], next?: string, total?: number }

List nodes in a Coalesce workspace (use list_workspaces to find workspace IDs). Returns ONE page (default 100 nodes, or 25 when detail=true).

IMPORTANT: if the response has hasMore: true, this is NOT the whole workspace — treating one page as complete will undercount it. Either page through the rest (call again with startingFrom set to the returned next, same orderBy), or better, switch tools: use analyze_workspace_patterns for a complete whole-workspace profile in one call, or search_workspace_content / get_workspace_node by ID to find specific nodes. Only page the full workspace when the user explicitly wants a full inventory.

Args:

• workspaceID (string, required): The workspace ID

• detail (boolean, optional): Include full node details

• limit, startingFrom, orderBy, orderByDirection: Pagination (limit defaults to 100, or 25 when detail=true)

Returns: { data: Node[], next?: string, hasMore?: boolean, retrieved?: number }

List distinct node types observed in current workspace nodes. This scans existing nodes only; it is not a true installed-type registry.

WARNING: Do NOT use these values directly as the nodeType parameter for create_workspace_node_from_predecessor or create_workspace_node_from_scratch. The observed values may be bare numeric IDs (e.g. '31') that differ from the proper package-prefixed format (e.g. 'base-nodes:::Stage'). Always call plan_pipeline first to discover the correct nodeType.

Args:

• workspaceID (string, required): The workspace ID

Returns: { nodeTypes: string[], counts: Record<string, number>, total: number } — nodeTypes is sorted by frequency descending; counts maps each type to its usage count.

List all Coalesce workspaces.

Returns workspace IDs needed by node, job, and subgraph tools. Each workspace includes its projectID.

Returns: { data: Workspace[] }

Convert an on-disk coa node YAML (the nodes/*.yml format) into a cloud workspace-node body suitable for set_workspace_node or update_workspace_node. Returns the cloud-shape object.

Use this when local-dev edits to a YAML node need to be pushed back to a cloud workspace without manually translating the schema (operation: → flat top-level, stepCounter/columnCounter → nodeID/columnID, sourceColumnReferences[] → sources[]).

For nodes that originated in the cloud, UUIDs round-trip and the cloud will treat the result as an idempotent update. For nodes authored from scratch on disk, the UUIDs are local-only — use create_workspace_node_from_predecessor or create_workspace_node_from_scratch instead of pushing this body via set/update.

Provide one of:

• yaml: raw YAML string (will be parsed)

• diskNode: pre-parsed disk-shape object

Parse a SQL statement into its structural components without touching the workspace. Returns CTEs (if any), source table references (FROM/JOIN), and projected columns (SELECT list). Use this as the first step in a multi-step pipeline creation workflow to inspect the SQL decomposition before choosing node types or building a plan.

For CTE-based SQL, each CTE is returned with its columns (with transform detection), WHERE filters, source tables, structural flags (hasJoin, hasGroupBy), and inter-CTE dependency references.

For non-CTE SQL, returns the parsed source refs and SELECT items with column/expression classification.

This tool is pure parsing — no workspace reads, no node type selection, no mutations.

Export all bundled Coalesce skill files to a local directory for customization. Each skill gets two files: coalesce_skills.{name}.md (the default) and user_skills.{name}.md (your overrides). Edit user_skills files to augment or override the defaults. Idempotent — never overwrites existing files.

Close a pipeline workshop session and clean up the session state. If there are uncreated nodes in the plan, use build_pipeline_from_intent or plan_pipeline to create them before closing.

Send a natural language instruction to an open pipeline workshop session. The instruction modifies the current plan — you can:

• Add nodes: 'add a staging node for PAYMENTS'

• Join sources: 'join CUSTOMERS and ORDERS on CUSTOMER_ID'

• Add aggregation: 'aggregate total REVENUE by REGION'

• Change join key: 'change the join key to ORDER_ID'

• Add filters: 'add filter for STATUS = active'

• Add/remove columns: 'add column FULL_NAME' or 'remove column MIDDLE_NAME'

• Rename nodes: 'rename STG_ORDERS to STG_SALES'

• Remove nodes: 'remove the ORPHAN node'

Each instruction is processed against the current session state, and the updated plan is returned.

Open a new pipeline workshop session for iterative, conversational pipeline building. The workshop maintains state between calls so you can incrementally add nodes, change join keys, add filters, rename nodes, and refine the plan before creating anything.

Optionally provide an initial intent (e.g., 'join customers and orders on customer_id') to bootstrap the session with initial nodes.

Returns a sessionID that must be passed to subsequent workshop calls.

Plan a Coalesce pipeline by discovering and ranking all available node types from the repo. ALWAYS call this before creating nodes to get the correct node type.

The planner scans the repo for all committed node type definitions, scores them against your use case, and returns ranked candidates. When available, it also returns a cached planSummaryUri MCP resource for the ranked node type summary so you can reuse that guidance throughout the pipeline without calling the planner again.

IMPORTANT — DO NOT WRITE SQL: The sql parameter is ONLY for converting SQL that the USER provided (pasted or typed). If you are building a pipeline yourself, provide goal + sourceNodeIDs instead.

PREREQUISITE: Before calling this tool, use list_workspace_nodes to discover available source/upstream nodes and their IDs in the workspace.

Preferred approach: Provide goal AND sourceNodeIDs. The planner selects the best node type and scaffolds the pipeline. Without sourceNodeIDs, the planner returns clarification questions.

User-provided SQL: When a user pastes SQL, pass it in sql. The planner parses refs and column projections.

Consult coalesce://context/node-type-corpus for node type patterns and metadata structures.

⚠️ WRITE operation — Updates all downstream columns that depend on a source column. Use this after renaming a column or changing its data type to propagate the change through the entire pipeline.

Args: workspaceID: Workspace to modify nodeID: Node containing the source column columnID: Column ID that was changed changes: Object with optional columnName and/or dataType to propagate

Returns: Pre-mutation snapshot summary (column-level changes), snapshotPath to a disk file with full node bodies, list of updated nodes/columns, total count, and any errors encountered. The disk snapshot at snapshotPath captures each downstream node's complete nodeBody before mutation, enabling manual reversal of partial failures via set_workspace_node. Each downstream node is fetched, its column updated, and the full node PUT back via API. The lineage cache is invalidated after propagation.

Requires a lineage cache — will fetch all workspace nodes with detail=true on first call. Note: Propagation targets are determined from the cached lineage graph (up to 30 min old). Downstream nodes added after the cache was built will not be included. Refresh lineage first if the workspace structure has changed recently.

Replace all columns in a workspace node with a new set of columns, optionally applying a WHERE filter and additional changes in a single call.

Do not use overrideSQL or override.* fields; SQL override is disallowed in this project.

Use this when:

• Applying column transforms (UPPER, LEFT, COALESCE, etc.) after node creation

• Adding WHERE filters at the same time as column transforms

• Converting from a simple join to GROUP BY aggregation

• Completely replacing column definitions with aggregate functions

Prefer this over separate update_workspace_node calls. Combine column replacement + WHERE filter in one call.

Example: Apply transforms and filter in one call: { columns: [ { name: 'CUSTOMER_ID', transform: '"CUSTOMER_LOYALTY"."CUSTOMER_ID"' }, { name: 'CITY', transform: 'UPPER("CUSTOMER_LOYALTY"."CITY")' }, { name: 'CONTACT_INFO', transform: 'COALESCE("CUSTOMER_LOYALTY"."E_MAIL", "CUSTOMER_LOYALTY"."PHONE_NUMBER")' } ], whereCondition: '"CUSTOMER_LOYALTY"."CUSTOMER_ID" IS NOT NULL AND ("CUSTOMER_LOYALTY"."E_MAIL" IS NOT NULL OR "CUSTOMER_LOYALTY"."PHONE_NUMBER" IS NOT NULL)' }

IMPORTANT: Use whereCondition for WHERE filters — do NOT construct {{ ref() }} syntax yourself. The FROM clause is already set up from node creation. The whereCondition is appended to the existing joinCondition automatically.

Args:

• workspaceID (string, required): The workspace ID

• nodeID (string, required): The node ID

• columns (array, required): Complete new columns array

• whereCondition (string, optional): WHERE filter to append

• additionalChanges (object, optional): Additional fields to update

Returns: { nodeID, warning?, validation? }

Retry a failed Coalesce run and poll until completion or timeout. Returns a task that can be polled for status.

Requires Snowflake auth via environment variables (Key Pair or PAT).

Args:

• runDetails.runID (string, required): The run ID to retry

• runDetails.forceIgnoreWorkspaceStatus (boolean, optional): Force retry

• parameters (object, optional): Runtime parameters

• pollInterval (number, optional): Seconds between checks (default: 10)

• timeout (number, optional): Max wait seconds (default: 1800)

Returns: { status, results, resultsError?, incomplete?, timedOut? }

Inspect timedOut, incomplete, and resultsError fields before continuing.

Retry a failed Coalesce run. Requires Snowflake auth via environment variables (Key Pair or PAT).

Args:

• runDetails.runID (string, required): The run ID to retry

• runDetails.forceIgnoreWorkspaceStatus (boolean, optional): Force retry even if deploy failed

• parameters (object, optional): Runtime parameters

Returns: { runCounter, runStatus, message }

Prefer retry_and_wait when you need the final outcome in a single call.

Analyze an existing pipeline in a Coalesce workspace and suggest improvements. Walks the node DAG, inspects column transforms, join conditions, node types, naming conventions, and layer architecture to identify issues and optimization opportunities.

Returns findings sorted by severity (critical → warning → suggestion) with actionable fix suggestions.

Checks for:

• Redundant passthrough nodes (no transforms added)

• Missing join conditions (multi-predecessor nodes without FROM/JOIN)

• Layer violations (skipping staging/intermediate layers)

• Node type mismatches (View used for joins, Dimension in staging layer)

• Orphan nodes (disconnected from the pipeline)

• Deep chains (8+ nodes deep)

• High fan-out risk (10+ downstream dependents)

• Naming inconsistencies

• Unused columns (>50% not referenced downstream)

Use nodeIDs to scope the review to a specific pipeline section (e.g., from a subgraph).

Start a Coalesce refresh run and poll until completion or timeout. Returns a task that can be polled for status.

Requires Snowflake auth via environment variables (Key Pair or PAT). Provide exactly one of runDetails.environmentID or runDetails.workspaceID. If the user provides a job name instead of an ID, look it up with find_jobs_by_name (or list_environment_jobs) first.

Args:

• runDetails.environmentID (string, optional): Target deployed environment (numeric ID as string)

• runDetails.workspaceID (string, optional): Target workspace for a development run (numeric ID as string)

• runDetails.jobID (string, optional): Specific job to run

• runDetails.includeNodesSelector (string, optional): Node filter

• runDetails.excludeNodesSelector (string, optional): Node exclusion

• runDetails.parallelism (number, optional): Max parallel nodes

• runDetails.forceIgnoreWorkspaceStatus (boolean, optional): Force run

• confirmRunAllNodes (boolean): Required when no job/node scope

• parameters (object, optional): Runtime parameters

• pollInterval (number, optional): Seconds between checks (default: 10, range: 5–300)

• timeout (number, optional): Max wait seconds (default: 1800, range: 30–3600)

Returns: { status, results, resultsError?, incomplete?, timedOut? }

Inspect timedOut, incomplete, and resultsError fields before continuing.

Get the current status of a Coalesce run by run counter.

Terminal statuses: completed, failed, canceled. Non-terminal: waitingToRun, running.

Args:

• runCounter (number, required): The numeric run counter

Returns: { runCounter, runStatus, message }

Search the generated node-type corpus snapshot by normalized family, package, primitive, or support status. This tool queries the committed snapshot and does not require access to the original external node source repo at runtime.

Search across node names, SQL, column names, descriptions, and config values in a workspace using the lineage cache as the data source.

Args: workspaceID: Workspace to search query: Text to search for (case-insensitive substring match) fields: (optional) Array of fields to search — any of: name, nodeType, sql, columnName, columnDataType, description, config. Defaults to all fields. nodeType: (optional) Filter results to a specific node type limit: (optional) Max results to return (1-200, default 50)

Returns: Matching nodes with the fields that matched and content snippets. Efficient for large workspaces — searches the in-memory cache instead of making per-node API calls.

Requires a populated lineage cache — will fetch all workspace nodes with detail=true on first call (may take a moment for large workspaces). Subsequent calls use the cached data (default TTL: 30 min).

Rank and select the best Coalesce node type for a specific pipeline step. When repoPath or COALESCE_REPO_PATH is configured, scans the local repo for committed node type definitions. Otherwise, falls back to workspace-observed node types. Scores candidates against the provided context and returns ranked candidates with confidence levels.

Use this after parse_sql_structure to select node types for each structural piece (e.g., each CTE, or the main query). Provide structural hints like sourceCount, hasJoin, hasGroupBy for more accurate selection.

The tool runs the full deliberative selection loop: score all candidates, challenge the top pick against the intent corpus, disqualify if challenged, re-rank, and challenge again (2 rounds max).

Returns the selected node type, confidence level, full ranking with scores, and any warnings. Use the selectedNodeType in subsequent plan_pipeline, create_workspace_node_from_predecessor, or create_workspace_node_from_scratch calls.

This tool reads workspace node type inventory for ranking but does not mutate anything.

Fetch a workspace node from the cloud and convert it to the on-disk coa YAML shape (the nodes/*.yml format). Returns both the parsed disk-shape object and a YAML string ready to write to disk.

Use this when an editor or local-dev workflow needs the disk representation of a cloud node — for example, to drop the YAML into a coa project and run coa create --dry-run to preview the generated SQL without an extra round-trip.

The conversion handles the schema diff (top-level → operation: wrapper, nodeID/columnID → stepCounter/columnCounter, sources[] → sourceColumnReferences[], synthesized columnReference per column, fileVersion: 1 header).

UUIDs round-trip; a node serialized this way and pushed back via parse_disk_node_to_workspace_body produces the same cloud body. The converter is lossy on cloud-only metadata (createdAt, updatedAt, etc.) — those are dropped.

Set a user's role for a specific environment. Idempotent.

Args:

• userID (string, required): The user ID

• environmentID (string, required): The environment ID

• role (string, required): Role to assign

Returns: Updated role assignment.

Set the organization-level role for a user. Idempotent — safe to call multiple times.

Args:

• userID (string, required): The user ID

• role (string, required): Role to assign (e.g., 'admin', 'member', 'viewer')

Returns: Updated role assignment.

Set a user's role for a specific project. Idempotent.

Args:

• userID (string, required): The user ID

• projectID (string, required): The project ID

• role (string, required): Role to assign (e.g., 'admin', 'developer', 'viewer')

Returns: Updated role assignment.

Update a workspace node's full body. Reads current state, merges changes, validates, and writes back.

This is the primary mutation tool for workspace nodes. It handles column linkage preservation, passthrough transform stripping, required API field injection, and metadata cleaning automatically.

Args:

• workspaceID (string, required): The workspace ID

• nodeID (string, required): The node ID

• body (object, required): Fields to update — name, description, nodeType, config, metadata.columns, etc.

Returns: { nodeID, created, warning?, validation?, configCompletion? }

Do NOT set overrideSQL or metadata.sourceMapping through this tool. Use apply_join_condition or convert_join_to_aggregation for join/aggregation changes.

Start a new Coalesce refresh run. Returns a task that resolves once the run has been submitted.

Requires Snowflake auth — credentials read from environment variables (Key Pair: SNOWFLAKE_KEY_PAIR_KEY, or PAT: SNOWFLAKE_PAT, plus SNOWFLAKE_USERNAME, SNOWFLAKE_WAREHOUSE, SNOWFLAKE_ROLE).

Provide exactly one of runDetails.environmentID or runDetails.workspaceID. If the user provides a job name, look up the ID with find_jobs_by_name (or list_environment_jobs) first.

Args:

• runDetails.environmentID (string, optional): Target deployed environment (numeric ID as string)

• runDetails.workspaceID (string, optional): Target workspace for a development run (numeric ID as string)

• runDetails.jobID (string, optional): Specific job to run

• runDetails.includeNodesSelector (string, optional): Node filter for ad-hoc runs

• runDetails.excludeNodesSelector (string, optional): Node exclusion filter

• runDetails.parallelism (number, optional): Max parallel nodes (default: 16)

• runDetails.forceIgnoreWorkspaceStatus (boolean, optional): Allow run even if last deploy failed

• confirmRunAllNodes (boolean): Required when no job/node scope is provided

• parameters (object, optional): Key-value runtime parameters

Returns: { runCounter: number, runStatus: string, message: string }

Prefer run_and_wait when you need the final outcome in a single call.

Update an existing Git account. Partial update — only provided fields are changed.

Args:

• gitAccountID (string, required): The account ID

• name (string, optional): Updated name

• gitUsername (string, optional): Updated git username

• gitAuthorName (string, optional): Updated author name for git commits

• gitAuthorEmail (string, optional): Updated email for git commits

• gitToken (string, optional): Updated personal access token

• provider (enum, optional): 'github' | 'gitlab' | 'bitbucket' | 'azureDevOps'

• accountOwner (string, optional): User ID of the account owner

Returns: Updated Git account object.

Update an existing Coalesce project. Partial update — only provided fields are changed.

Args:

• projectID (string, required): The project ID

• name (string, optional): Updated name

• description (string, optional): Updated description

• gitAccountID, gitRepo, gitBranch (string, optional): Updated git settings

• includeWorkspaces, includeJobs (boolean, optional): Expand response

Returns: Updated project object.

Update an existing workspace job.

Args:

• workspaceID (string, required): The workspace ID

• jobID (string, required): The job ID

• name (string, required): Updated job name

• includeSelector (string, required): Node selector. Format: '{ location: LOC name: NAME } OR { location: LOC name: NAME }'

• excludeSelector (string, required): Node exclusion selector. Same format as includeSelector

Returns: Updated job object.

Safely update selected fields of a workspace node by fetching the current node, applying partial changes, then writing back the full merged body. Object fields are deep-merged; arrays replace the existing array when provided. Use list_workspaces to find workspace IDs.

Do not use overrideSQL or override.* fields; SQL override is disallowed in this project.

NOTE: Arrays (like metadata.columns) are replaced, not merged. For complex column transformations (e.g., converting from join to aggregation), consider using replace_workspace_node_columns instead.

For guidance on SQL platforms and tool usage patterns, see resources: coalesce://context/sql-platform-selection, coalesce://context/tool-usage

Update a subgraph's name and member nodes. Replaces the entire steps array. Pass either subgraphID (fastest) or subgraphName — if only the name is given, the ID is resolved from (1) the local UUID cache, (2) {repoPath}/subgraphs/*.yml. The public Coalesce API has no subgraph list endpoint, so a subgraph created outside this MCP session cannot be resolved by name without a repo checkout.

Args:

• workspaceID (string, required): The workspace ID

• subgraphID (string, optional): The subgraph ID. Preferred when known.

• subgraphName (string, optional): The subgraph name. Used to resolve the ID when subgraphID is absent.

• repoPath (string, optional): Coalesce repo path for subgraph YAML lookup.

• name (string, required): Updated name

• steps (string[], required): Updated node IDs

Returns: { subgraphID, subgraph, resolvedFrom } where resolvedFrom is "input" | "cache" | "repo".