Playbook Tools

Tools for working with playbooks in Mission Control.

Playbooks as tools

Every playbook the caller is allowed to run is registered as its own MCP tool, rather than being run through one generic tool. The tool name is derived from the playbook:

<title-or-name>_<namespace>_<category>

So a playbook titled Scale Deployment in the mc namespace under the Kubernetes category becomes the tool scale-deployment_mc_kubernetes.

The tool's input schema is generated from the playbook's parameters, plus the resource the playbook runs on:

Field	Description	Scheme
agent_id	UUID of the agent to run the playbook on. Optional	string
check_id	UUID of the health check. Required when the playbook declares spec.checks	string
component_id	UUID of the component. Required when the playbook declares spec.components	string
config_id	UUID of the config item, from search_catalog results. Required when the playbook declares spec.configs	string
params	The playbook's own parameters. Every value is a string; checkbox parameters accept "true" or "false"	object

Use the mcp field on the playbook spec to control the tool's title, description, tags and behavioural hints. The playbook's category and MCP tags are appended to the tool description so the model can find it.

Permissions

A playbook only appears as a tool when the caller holds the mcp:run action on it.

Example Usage

Prompt: "Scale the web-app deployment to 3 replicas in staging"

AI Response: "I'll scale the web-app deployment to 3 replicas in the staging namespace."

Tool Called: scale-deployment_mc_kubernetes

Parameters Used:

{
  "config_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "params": {
    "replicas": "3"
  }
}

Result: Executes the scaling operation and returns the run status.

get_playbook_recent_runs

Get recent playbook execution history as a JSON array. Each entry contains run details, status, timing, and results.

Field	Description	Scheme
limit	Maximum number of recent runs to return. Defaults to 20	number
playbook_id	UUID of a playbook to filter runs by. When omitted, returns runs for all playbooks	string

Example Usage

Prompt: "Show me the last 5 playbook runs"

AI Response: "I'll get the 5 most recent playbook execution runs for you."

Example Output:

[
  {
    "id": "run-123",
    "playbook_name": "Restart Pod",
    "status": "success",
    "started_at": "2025-01-20T10:30:00Z",
    "completed_at": "2025-01-20T10:32:15Z",
    "duration": "2m15s"
  },
  {
    "id": "run-122",
    "playbook_name": "Scale Deployment",
    "status": "failed",
    "started_at": "2025-01-20T09:15:00Z",
    "error": "Insufficient permissions"
  }
]

get_playbook_failed_runs

Get recent failed playbook runs as a JSON array. Each entry contains failure details, error messages, and timing information.

Field	Description	Scheme
limit	Maximum number of failed runs to return. Defaults to 20	number
playbook_id	UUID of a playbook to filter runs by. When omitted, returns failed runs for all playbooks	string

Example Usage

Prompt: "Show me recent playbook failures so I can investigate what went wrong"

AI Response: "I'll get the recent failed playbook runs to help you identify issues."

Example Output:

[
  {
    "id": "run-122",
    "playbook_name": "Scale Deployment",
    "status": "failed",
    "started_at": "2025-01-20T09:15:00Z",
    "error": "Insufficient permissions to scale deployment in namespace 'production'",
    "parameters": {
      "namespace": "production",
      "deployment_name": "web-app",
      "replicas": 5
    }
  }
]

get_playbook_run_steps

Get detailed information about a playbook run, including all of its actions. Actions from child runs are included, ordered by start time.

Field	Description	Scheme
run_id*	UUID of the playbook run	string
withResult	Include each action's result. Set to false to reduce the response size. Defaults to true	boolean

Example Usage

Prompt: "Why did run 4f2a… fail?"

Result: Returns each action in the run with its status, timing, and — unless withResult is disabled — the output it produced.