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 AI 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 AI 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 AI 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 AI 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 (via the sync/delete API).
get_workspace_secrets	List available secret key names (e.g. kubeconfig, api-token).
get_workspace_locations	List runner locations where scripts can execute.
render_codecollection_skill	Render a tested task as a private Custom Discovery CodeCollection bundle (generation rules + Jinja templates + SKILL_TEMPLATE.md + raw_script.{py,sh}). Writes to disk in stdio mode or returns files inline.
run_slx	Execute an already-committed SLX’s runbook tasks on the runner. Use task_titles="*" (not display titles).
search_registry	Search the RunWhen CodeBundle Registry for reusable, production-tested automation. Always try this before writing a custom script.
get_registry_codebundle	Get full details of a specific codebundle from the registry (config templates, env vars, deployment instructions).
deploy_registry_codebundle	Deploy a registry codebundle as an SLX to a workspace (no inline script needed).
list_assistants / get_assistant / create_assistant / update_assistant / delete_assistant	List, inspect, create, update, and delete AI Assistants (personas). An assistant’s short_name is the persona_name for workspace_chat.
list_knowledge_base_articles / get_knowledge_base_article / create_knowledge_base_article / update_knowledge_base_article / delete_knowledge_base_article	Manage Knowledge Base articles (operational knowledge indexed into the Knowledge Overlay Graph).

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
resource_path	string	Resource path for search indexing (auto-prefixed with custom/)
hierarchy	list[string]	Tag names for hierarchical grouping (e.g. ["platform", "workspace"])

render_codecollection_skill:

Parameter	Type	Description
bundle_name	string	Codebundle directory name (kebab-case)
alias	string	Human-readable SLX display name
statement	string	SLX statement describing what should be true
workspace_name	string	Workspace used during testing (provenance)
script	string	The full script source code
interpreter	string	bash or python
env_vars	object	Environment variables baked into the TaskSet config
secret_vars	object	Secret name → workspace secret key mappings
runtime_vars	list[object]	Per-run runtime variables (task-only)
access	string	read-write or read-only
data	string	logs-bulk, config, or logs-stacktrace
resource_path	string	Resource path for search indexing (auto-prefixed with custom/)
hierarchy	list[string]	Tag names for hierarchical grouping
platform	string	Generation rule platform (default runwhen)
resource_types	list[string]	Resource types to match (default ["workspace"])
match_rules	list[object]	Match predicates for the generation rule
include_sli	bool	Also emit an SLI template (requires sli_script)
sli_script	string	Separate SLI script (required when include_sli=True)
sli_interpreter	string	Interpreter for the SLI script
output_dir	string	Write rendered files to this directory (stdio mode only)

See Tool Builder for the full authoring workflow and script contract, and the Author Custom Tasks with MCP guide for the GitOps CodeCollection flow.