skypilot-mcp

skypilot_pool_apply

Create or update a long-lived SkyPilot worker pool to host multiple managed jobs, using a task YAML and rolling or blue-green updates. Returns a request_id.

Instructions

Create or update a worker pool. A worker pool is a long-lived set of compute resources that can host multiple managed jobs. Accepts a SkyPilot task YAML string defining the pool's resources. Set mode to 'rolling' (default) or 'blue_green' for the update strategy. Returns a request_id.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "pool_name": "<pool_name>"
    },
    "name": "skypilot_pool_apply"
  }
}

Input Schema

Name	Required	Default
`mode`	No	rolling
`workers`	No
`pool_name`	Yes
`task_yaml`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 13, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations declare openWorldHint=true and destructiveHint=false, so the safety profile is partially covered. The description adds useful behavioral context: the tool is an apply-style upsert, it accepts a SkyPilot YAML, it supports rolling vs blue_green update strategies, and it returns a request_id. It does not discuss permissions or side effects on existing workers, but it meaningfully extends annotations.

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?

Four front-loaded sentences with no filler. The definition of a worker pool is useful but slightly verbose for the space; overall efficient.

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

Completeness3/5

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

An output schema exists (returns a request_id) so return format is covered externally. However, with 0% schema description coverage and no annotations for auth, the description should ideally mention pool_name semantics, workers, and when an update would disrupt existing jobs. It is adequate but leaves notable gaps for a mutating, open-world tool.

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 0%, so the description must compensate. It explains that task_yaml is a SkyPilot YAML string defining resources and that mode selects 'rolling' (default) or 'blue_green'. It does not mention the workers parameter or pool_name, leaving two of four parameters unexplained, but it covers the two most semantically loaded parameters.

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?

The description states a specific verb+resource ('Create or update a worker pool') and defines what a pool is ('a long-lived set of compute resources that can host multiple managed jobs'), which cleanly distinguishes it from sibling tools like skypilot_cluster_launch or skypilot_managed_job_launch.

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

Usage Guidelines3/5

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

The description implies usage (create/update pools, choose update strategy) but never states when to prefer this over alternatives like skypilot_cluster_launch or skypilot_serve_up, nor prerequisites. It's implied but not explicit guidance.

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

Deploy Server