Tool Reference

The RunWhen Platform MCP server exposes tools in three groups: workspace intelligence, chat rules and commands, and task authoring (Tool Builder).

Workspace intelligence

These tools let you query your RunWhen workspace for issues, tasks, run sessions, and resources — or ask the AI assistant directly.

Tool	Description
workspace_chat	Ask the RunWhen AI assistant about your infrastructure. The assistant can search issues, tasks, run sessions, resources, and the knowledge base. Supports graphs and Mermaid diagrams. Use persona_name to select an Engineering Assistant.
list_workspaces	List all workspaces you have access to.
get_workspace_chat_config	Get resolved chat rules and commands for a workspace (metadata only). Optional persona_name.
get_workspace_issues	Get current issues. Optional severity filter (1=critical, 2=high, 3=medium, 4=low).
get_workspace_slxs	List SLXs (health checks and automation tasks) in the workspace.
get_run_sessions	Get recent run session results.
get_workspace_config_index	Get the full workspace configuration — resources, SLXs, and their relationships.
get_issue_details	Get details for a specific issue by ID.
get_slx_runbook	Get the runbook definition for an SLX, including tasks, configuration, and what it checks.
search_workspace	Search tasks, resources, and configuration by keyword.

workspace_chat

This is the most powerful tool. It talks to the RunWhen AI assistant, which has access to 25+ internal tools. Use it for natural language questions about your infrastructure:

Using workspace chat, what's unhealthy in my production namespace?

Using workspace chat, show me a diagram of how my services connect.

The optional persona_name parameter selects which Engineering Assistant handles the request (e.g. eager-edgar, cautious-cathy). This matters for workspaces where your role is readandrunwithassistant — the persona determines which tasks the assistant can run.

Chat rules and commands

These tools manage the rules and slash-commands that customize your Engineering Assistants’ behavior.

Tool	Description
list_chat_rules	List chat rules. Filter by scope_type, scope_id, is_active.
get_chat_rule	Get a chat rule by ID (full content).
create_chat_rule	Create a new chat rule.
update_chat_rule	Update an existing chat rule by ID.
list_chat_commands	List chat commands (slash-commands).
get_chat_command	Get a chat command by ID (full content).
create_chat_command	Create a new chat command.
update_chat_command	Update an existing chat command by ID.

Scope types

Rules and commands can be scoped to different levels:

Scope	Applies to
platform	All workspaces across the platform
org	All workspaces in an organization
workspace	A specific workspace
persona	A specific Engineering Assistant
user	A specific user

Task authoring — Tool Builder

These tools let you write, test, and deploy automation scripts as SLXs directly from your IDE.

Tool	Description
get_workspace_context	Load the project’s RUNWHEN.md file with infrastructure conventions, naming patterns, and constraints. Call this before writing scripts.
validate_script	Check that a script follows the RunWhen contract (correct main() function, output format, etc.).
run_script	Send a script to a RunWhen runner for execution. Returns a run_id for polling.
get_run_status	Poll the status of a script run (RUNNING, SUCCEEDED, FAILED).
get_run_output	Get parsed output from a completed run — issues, stdout, stderr.
run_script_and_wait	Convenience tool that combines run_script + get_run_status + get_run_output in one call.
commit_slx	Commit a tested script as an SLX to the workspace. Supports task-only, task + custom SLI, or task + cron-scheduled SLI.
delete_slx	Remove an SLX from the workspace Git repo.
get_workspace_secrets	List available secret key names (e.g. kubeconfig, api-token).
get_workspace_locations	List runner locations where scripts can execute.

Key parameters

run_script / run_script_and_wait:

Parameter	Type	Description
script	string	Full script source code
location	string	Runner location (from get_workspace_locations)
interpreter	string	bash or python
run_type	string	task or sli
env_vars	object	Environment variables (e.g. {"NAMESPACE": "default"})
secret_vars	object	Secret mappings — env var name to workspace secret key (e.g. {"kubeconfig": "kubeconfig"})

commit_slx:

Parameter	Type	Description
slx_name	string	Short name in kebab-case (e.g. k8s-pod-health)
alias	string	Human-readable display name
statement	string	What should be true (e.g. “All pods should be running”)
script	string	The task script source code
task_title	string	Human-readable task title
location	string	Runner location
interpreter	string	bash or python
sli_script	string	Optional custom SLI script (returns 0-1)
cron_schedule	string	Optional cron expression to schedule the task
access	string	read-write or read-only
data	string	logs-bulk, config, or logs-stacktrace

See Tool Builder for the full authoring workflow and script contract.