dbx-mcp

Manage clusters

manage_cluster

Destructive

Create, update, resize, start, restart, stop, or delete all-purpose Databricks clusters, and list or inspect cluster events. Destructive actions require confirmation.

Instructions

Manage all-purpose clusters.

Actions: list (optionally filtered by state), get, events (recent cluster events), create (spec = Clusters API create body, e.g. {"cluster_name","spark_version","node_type_id", "num_workers" or "autoscale","autotermination_minutes"}), update (partial update: spec holds only the fields to change), resize, start, restart, terminate (stop; restartable) and delete (permanent). restart/terminate/delete require confirm=true and are refused for clusters whose name/tags match the protected (production) patterns. Lifecycle actions return immediately with the current state unless wait=true.

Safety classification: list, get, events = READ_ONLY; create, update, resize, start = WRITE; restart, terminate, delete = DESTRUCTIVE.

Input Schema

TableJSON Schema

Name	Required	Description
`spec`	No	Request body fields for create/update, using the Databricks REST API field names (snake_case). Unknown fields are rejected.
`wait`	No	Wait (bounded) for the operation to reach a steady state.
`action`	Yes	terminate = stop (restartable); delete = permanent removal.
`states`	No	For list: filter by states, e.g. ['RUNNING','PENDING'].
`confirm`	No	Set to true ONLY after the user has reviewed the plan returned by a previous call with status 'confirmation_required'. Required for destructive/security-sensitive actions.
`dry_run`	No	If true, validate and return the planned change without executing it.
`page_size`	No	Max items to return (server caps this).
`cluster_id`	No	Cluster id (all actions except list/create).
`page_token`	No	next_page_token from a previous response.
`num_workers`	No	For resize: fixed worker count.
`timeout_seconds`	No	Max seconds to wait when wait=true (capped by DBX_MCP_MAX_WAIT_SECONDS).
`autoscale_max_workers`	No	For resize: autoscale maximum.
`autoscale_min_workers`	No	For resize: autoscale minimum.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`data`	No
`page`	No
`plan`	No
`tool`	Yes
`action`	No
`safety`	No
`status`	No		success
`summary`	Yes
`warnings`	No
`next_steps`	No	Suggested follow-up calls.
`request_id`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 3, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses behavior far beyond annotations: confirm gating, refusal for clusters matching protected production name/tag patterns, immediate vs. wait behavior for lifecycle actions, and a full safety classification mapping each action to READ_ONLY/WRITE/DESTRUCTIVE. This is exactly the context a mutation dispatcher needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded and well-sectioned under 'Actions:' and 'Safety classification:', with no filler sentences. It repeats the terminate/delete semantics already in the action enum description, a minor redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-parameter, 10-action dispatcher with an output schema present, the description covers every action, the confirm/dry_run/wait contract, and the safety profile. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% so the baseline is 3, but the description adds real value by supplying the create spec body example field names ({cluster_name, spark_version, node_type_id, num_workers/autoscale, autotermination_minutes}) and the partial-update semantics for spec, which the schema does not enumerate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Manage all-purpose clusters') and enumerates every action (list, get, events, create, update, resize, start, restart, terminate, delete) with a parenthetical clarifying each. An agent can distinguish it from siblings like list_compute or manage_jobs without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear per-action conditions: confirm=true is required for restart/terminate/delete, wait=true controls whether lifecycle actions return immediately, and list can be state-filtered. It never names alternative sibling tools to route to, so it stops short of explicit when-not/alternatives guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server