Commit a tested script as an SLX to the workspace Git repo.

Skills:

• runwhen-skill://build-runwhen-task (authoring workflow)

• runwhen-skill://discover-secrets (secret_vars mapping)

• runwhen-skill://discover-locations (location selection)

• runwhen-skill://configure-hierarchy (hierarchy/resource_path)

Creates a new SLX with the script as a Task (runbook) and/or SLI. The script should already be tested via run_script or run_script_and_wait.

This writes slx.yaml + runbook.yaml (for tasks) or slx.yaml + sli.yaml (for SLIs) to the workspace repository.

Script-source parameter matrix (provide exactly one task variant; SLI variants mirror the names):

For very large scripts (combined task+SLI >~50KB) prefer publishing as a registry codebundle and using deploy_registry_codebundle.

To commit BOTH a task AND an SLI on the same SLX:

1. Custom SLI script (preferred): set task_type="task" and provide a separate lightweight sli_script that emits ONE float between 0 and 1 (e.g. failing_pods / total_pods). The SLI script MUST be its own small probe — DO NOT duplicate the task body. The server rejects identical task+SLI content.

2. Cron-scheduler SLI: set task_type="task" and provide cron_schedule with a cron expression (e.g. "0 */2 * * *"). The SLI will trigger the task's runbook on that schedule. No sli_script needed.

Output contracts (the two scripts are NOT interchangeable):

• Task (interpreter, task_type='task'): returns/writes a List[Dict] of issues with keys 'issue title', 'issue description', 'issue severity' (1-4), 'issue next steps'.

• SLI (sli_interpreter, implied task_type='sli'): returns/writes ONE float between 0 and 1.

Script-content footguns:

• Bash scripts must NOT include main "$@" at the bottom. The runner sources the script and invokes main() itself with FD 3 wired to a run_output.json file. A trailing main "$@" triggers a preflight invocation with FD 3 read-only, producing misleading "Bad file descriptor" errors. Just define main() and stop there.

• secret_vars entries are injected at runtime as env vars whose VALUE is a FILE PATH on the runner — not the secret value itself. Tools that read paths natively (kubectl/KUBECONFIG, gcloud/ GOOGLE_APPLICATION_CREDENTIALS) work unchanged. For tokens/passwords the script must cat "$VAR" (bash) or open(os.environ["VAR"]).read() (python) to get the actual value.

Create a new AI assistant (persona) in a workspace.

Skill: runwhen-skill://create-ai-assistant (full setup workflow).

An assistant is a persona that tailors how the RunWhen AI investigates and acts — e.g. an "Azure DevOps Helper" focused on a specific tech stack. The short_name you choose becomes the persona_name for workspace_chat.

After creating the assistant, shape its behavior by attaching persona-scoped rules and commands:

create_chat_rule(scope_type="persona", scope_id=short_name, ...)
create_chat_command(scope_type="persona", scope_id=short_name, ...)

This is an UPSERT — calling it again with an existing short_name REPLACES the assistant's full configuration (omitted fields reset to defaults). To change a few fields on an existing assistant, use update_assistant.

Create a chat command (slash-command). Name must be alphanumeric, underscore, or hyphen only.

Skill: runwhen-skill://manage-commands (scoping, scheduling, sinks).

Commands are invoked in chat as /label.

To run a command on a schedule, set cron_schedule plus sink_configs, run_as_user, and assistant_name. Results are delivered to each sink (email or Slack) when the cron fires.

Create a chat rule. Uses AgentFarm internal API.

Skill: runwhen-skill://manage-rules (scoping + wording guidance).

Create a new Knowledge Base article in a workspace.

Skill: runwhen-skill://manage-knowledge (article scoping + lifecycle).

KB articles are indexed into the Knowledge Overlay Graph and become searchable by the workspace AI assistant and other tools.

Content should be informative operational knowledge — architecture notes, troubleshooting guides, runbook context, dependency documentation, etc.

Delete (soft-delete) an AI assistant (persona) from a workspace.

Persona-scoped rules and commands attached to this assistant are not removed automatically — clean them up separately if no longer needed.

Delete a Knowledge Base article.

Removes the article from the workspace and the Knowledge Overlay Graph index.

Soft-delete an SLX from the workspace via the v4 short-name endpoint.

Uses DELETE /api/v4/workspaces/{ws}/slxs/{slx_short_name}, which tombstones the SLX row (deleted_by / deleted_at) and lets the corestate reconcile loop clean up the corresponding runbook and SLI rows. This is the same endpoint the UI hits, so behaviour matches what users see in the platform.

Deletion is workspace-global — it is not scoped to a Git branch. The v4 endpoint tombstones the SLX row in PAPI; there is no per-branch variant. Callers previously wired to a Git-oriented delete path should stop passing branch / commit_message (both removed) and rely on the workspace-scoped soft delete.

Deploy a registry codebundle as an SLX to a workspace.

Unlike commit_slx (which embeds inline scripts via the Tool Builder codebundle), this deploys a pre-built codebundle from its own codecollection repository. The runbook.robot / sli.robot live in the codebundle's git repo — no inline script is needed.

Use search_registry + get_registry_codebundle to find the right codebundle, then call this tool with the values from the registry.

Get a single AI assistant (persona) by its short name (full config).

Get a single chat command by ID (full content).

Get a single chat rule by ID (full content).

Get detailed information about a specific issue (structured JSON).

NOTE: Prefer workspace_chat for investigative questions about an issue (e.g. root cause, related resources, next steps). Use this tool only when you already have an issue ID and need raw JSON.

Get a specific Knowledge Base article by ID.

Get full details of a specific codebundle from the registry.

Use after search_registry to get complete information including configuration templates, environment variables, and deployment instructions.

Get the output artifacts from a completed script run.

Returns parsed, human-readable results including:

• issues: list of issues found by the script (title, severity, details, nextSteps)

• stdout: script stdout output

• stderr: script stderr output

• status: run status (SUCCEEDED, FAILED, RUNNING)

Get recent run sessions for a workspace (structured JSON).

Run sessions are executions of SLX runbooks — they contain the output of health checks, troubleshooting tasks, and automation runs.

NOTE: For investigative questions like "what ran recently for service X?" or "show me recent failures", prefer workspace_chat — it can search, filter, and correlate run sessions with issues and resources. Use this tool only when you need raw JSON for programmatic processing.

Check the status of a script run.

Poll this after run_script to check if execution has completed. Status values: RUNNING, SUCCEEDED, FAILED.

Return the full body of a skill by name.

Returns {name, description, uri, body, path} on success or {error, available} when the name is unknown so the agent can self- correct without a second round-trip.

Get the runbook for a specific SLX (structured JSON).

Returns the runbook definition including what tasks it runs, how they're configured, and what they check.

NOTE: For questions like "what does this SLX do?" or "what tasks does it run?", prefer workspace_chat — it provides contextual explanations. Use this tool when you need the raw runbook YAML/JSON (e.g. for task authoring or programmatic inspection).

Get resolved chat rules and commands for a workspace.

Returns the list of rules and commands that apply to the workspace (and optional persona). These are the same rules and commands the workspace chat assistant sees. Response includes metadata only (id, name, scope); full rule/command content is not included in this endpoint.

Get the workspace configuration index (structured JSON).

Returns an overview of all configured resources, SLXs, and their relationships in the workspace. Useful for understanding what's monitored and how things are connected.

This tool accepts only workspace_name. It does NOT accept resource_path, slx_name, filter, or other parameters — those fail with unexpected_keyword_argument. To set resource_path on an SLX, use commit_slx or deploy_registry_codebundle. To find SLXs at a path, use workspace_chat or search_workspace.

NOTE: For questions like "what's monitored in namespace X?" or "how are resources connected?", prefer workspace_chat — it can traverse the resource graph and provide contextual answers. Use this tool only when you need the raw configuration index for programmatic processing.

Get domain-specific context for building RunWhen tasks.

Reads the project's RUNWHEN.md file, which contains infrastructure conventions, database access rules, naming patterns, architectural knowledge, and other constraints that scripts must follow.

The file is auto-discovered by walking up from the current working directory. Override with the RUNWHEN_CONTEXT_FILE env var if needed.

IMPORTANT: Call this BEFORE writing any task or script to understand the target environment's rules and relationships.

Get current issues for a workspace (structured JSON).

Issues represent detected problems in your infrastructure that RunWhen has identified through automated health checks.

NOTE: For questions like "issues related to neo4j" or "what's failing in namespace X", prefer workspace_chat — it has semantic search and keyword filtering that produce materially better results. Use this tool only when you need raw JSON for programmatic processing.

List runner locations with auto-resolution guidance and recommendations.

Returns a structured payload that tells the agent which location to use (or to omit the parameter entirely when auto-resolution can pick). The raw list is preserved in locations for backward compatibility.

Response shape::

{ "workspace": "", "count": , "locations": [], "private": [], # workspace-type runners (preferred) "public": [], # shared runners (fallback) "recommended": "<name|null>", "auto_resolves": , # True when run_*/commit_slx can pick alone "disambiguation_hint": "...", "skill_reference": "runwhen-skill://discover-locations", }

recommended is the name run_script / run_script_and_wait / commit_slx WILL pick when the location parameter is omitted. When auto_resolves is True the agent should NOT pass a location argument at all.

List available secret keys with platform grouping and mapping guidance.

Returns a structured payload that helps agents pick the right secret_vars mapping for a task. The raw key list is preserved in secrets for backward compatibility.

Response shape::

{ "workspace": "", "secrets": [], "platform_groups": { "kubernetes": ["kubeconfig"], "azure": [...], ... }, "recommended_secret_vars": { "kubernetes": { "kubeconfig": "kubeconfig" }, "azure": { "AZURE_CLIENT_ID": "...", ... }, ... }, "runtime_semantics": "", "skill_reference": "runwhen-skill://discover-secrets", }

Critical for agents: workspace secrets are injected into scripts as FILE PATHS, not literal values. See the discover-secrets skill for the read_secret helper pattern.

List ALL SLXs in a workspace (structured JSON). No filtering.

SLXs are the fundamental unit of work in RunWhen — each represents a health check, task, or automation runbook for a piece of infrastructure.

The underlying PAPI endpoint is paginated (100 SLXs per page); this tool auto-paginates internally, following next until exhausted, so the returned results are the complete list for the workspace — never just the first page. count reflects the true total and next is always null (there is nothing left to page).

It accepts only workspace_name. It does NOT accept slx_name, filter, alias, tag, or any other filtering parameter — those would fail with unexpected_keyword_argument.

For other shapes:

• One specific SLX (runbook detail): get_slx_runbook(workspace_name=..., slx_name=...)

• Search / filter by topic (e.g. "neo4j health checks"): workspace_chat

• Search by resource (e.g. "what monitors namespace X"): workspace_chat

Use this raw-list tool only when you need to enumerate every SLX for programmatic processing (counting, batch operations, etc).

List AI assistants (personas) configured in a workspace.

An assistant is a persona — its shortName is the value you pass as persona_name to workspace_chat. Use this to discover which assistants already exist before creating a new one.

List chat commands (slash-command instructions).

List chat rules (workspace chat rules).

Uses AgentFarm internal API; may require network access.

List supported generation-rule platforms and default render settings.

Skills:

• runwhen-skill://commit-to-codecollection

• runwhen-skill://author-generation-rules

Call this before render_codecollection_skill when the user has not confirmed whether they want workspace-scoped output (runwhen) or per-resource cloud/Kubernetes discovery (kubernetes, azure, aws, gcp). Ask the user to pick a platform and scope, then look up valid resource_types with list_indexed_resource_types(search=...). All catalog data is bundled offline — no docs.runwhen.com access required.

Search bundled indexer catalogs for valid generation-rule resourceTypes.

Skills:

• runwhen-skill://author-generation-rules

• runwhen-skill://commit-to-codecollection

Fully offline — reads catalogs/indexed-resource-types.json (or bundled markdown catalogs) shipped with the MCP package. No network access required.

For azure/aws/gcp, search must be at least 2 characters (large catalogs). Kubernetes CRD types use plural.group[/version] syntax when not listed.

List Knowledge Base articles (notes) in a workspace (structured JSON).

Returns KB articles that feed the workspace's Knowledge Overlay Graph. Articles can contain operational knowledge, runbook context, architecture notes, or any information useful for troubleshooting.

NOTE: For questions like "what do we know about service X?", prefer workspace_chat — it searches KB articles semantically. Use this tool for programmatic KB management (listing, filtering by status).

List every progressive-disclosure skill the server exposes.

Returns [{name, description, uri}]. Use this when you want to know what guidance is available before running a tool — read the description to decide whether you need the full body, then fetch it with get_skill(name) (or, if your client supports MCP resources directly, read the uri via the resource read API).

Cross-vendor note: this is the same information that list_resources returns for the runwhen-skill:// family. Clients that surface MCP resources should prefer that path; this tool is the explicit fallback.

List all workspaces you have access to.

Returns workspace names, display names, and basic metadata.

Render a tested tool-builder task as a private Custom Discovery CodeCollection.

Skills:

• runwhen-skill://commit-to-codecollection (GitOps workflow)

• runwhen-skill://build-runwhen-task (authoring + testing first)

Emits the standard codecollection layout (generation rule + Jinja templates) for workspace-builder discovery. Templates delegate runtime to rw-generic-codecollection/codebundles/tool-builder with base64 GEN_CMD.

Also writes .runwhen/SKILL_TEMPLATE.md with the decoded script summary and .runwhen/raw_script.{py,sh} with the full decoded script so PR reviewers and automated systems never need to base64-decode TaskSet templates.

This tool does not push to git or mutate the workspace — it renders files locally (or returns them inline) for you to git add / commit / push.

Default generation rule uses platform: runwhen and resourceTypes: [workspace]. For cloud/Kubernetes discovery, set platform to kubernetes, azure, aws, or gcp and pass resource_types / match_rules / slx_qualifiers from the bundled indexer catalogs (list_indexed_resource_types). Discovery SLX templates include the platform tag/hierarchy includes (e.g. kubernetes-tags.yaml).

Requires runwhen-local with the matching platform indexer enabled.

Execute a script on a RunWhen runner for testing.

Sends the script to the workspace's runner at the specified location. Returns a run ID that can be used with get_run_status and get_run_output to monitor execution and retrieve results.

The script must follow the RunWhen contract:

• Python task: define main() returning List[Dict] with keys 'issue title', 'issue description', 'issue severity' (1-4), 'issue next steps'.

• Python SLI: define main() returning a float 0-1.

• Bash task: define main() writing issue JSON array to FD 3 (>&3).

• Bash SLI: define main() writing a metric float to FD 3.

Provide exactly one of: script | script_base64 | script_gzip_base64 | script_path (stdio) | script_base64_path (stdio). Use script_gzip_base64 for scripts >5KB to maximise transport headroom.

Use validate_script first to check compliance.

Execute a script and wait for results (combines run + poll + output).

This is a convenience tool that runs a script, polls until completion, and returns the full output — all in one call. Use this instead of calling run_script + get_run_status + get_run_output separately.

The script must follow the RunWhen contract:

• Python task: define main() returning List[Dict] with keys 'issue title', 'issue description', 'issue severity' (1-4), 'issue next steps'.

• Python SLI: define main() returning a float 0-1.

• Bash task: define main() writing issue JSON array to FD 3 (>&3).

• Bash SLI: define main() writing a metric float to FD 3.

Provide exactly one of: script | script_base64 | script_gzip_base64 | script_path (stdio) | script_base64_path (stdio). Use script_gzip_base64 for scripts >5KB to maximise transport headroom.

Bash scripts must NOT include main "$@" at the bottom. The runner sources the script and invokes main() itself with FD 3 wired to a run_output.json file. A trailing main "$@" triggers a preflight invocation with FD 3 read-only and produces misleading "Bad file descriptor" errors.

secret_vars entries are injected as env vars whose VALUE is a FILE PATH on the runner — not the secret value itself. kubectl/KUBECONFIG and gcloud/GOOGLE_APPLICATION_CREDENTIALS work unchanged. For tokens/ passwords the script must cat "$VAR" (bash) or open(os.environ["VAR"]).read() (python) to get the actual value.

Run an existing SLX's runbook tasks on the workspace runner.

Skill: runwhen-skill://run-existing-slx — and default task_titles="*" (a literal resolved title produces empty passedTitles).

This triggers execution of a previously committed SLX (not an ad-hoc script). Use this when you want to run a health check, troubleshooting task, or automation that already exists in the workspace.

IMPORTANT: This is different from run_script / run_script_and_wait, which execute ad-hoc scripts. Use run_slx to trigger SLXs that are already committed and configured in the workspace.

NOTE: workspace_chat CANNOT run tasks directly — it can only search for and describe them. Use this tool to actually execute an SLX.

The tool creates a RunSession with the run request, polls until completion, and returns the results including pass/fail status and any issues found.

Search the RunWhen CodeBundle Registry for reusable automation.

Skill: runwhen-skill://find-and-deploy-codebundle (search → deploy workflow).

Use this BEFORE writing a custom script — there may already be a production-ready codebundle for the task. Returns codebundles with their tasks, SLIs, required env vars, and deployment metadata.

Search for tasks, resources, and configuration in a workspace.

Uses the workspace's task search / autocomplete to find matching items.

NOTE: Prefer workspace_chat for most search queries — it uses semantic search and keyword grep across issues, resources, SLXs, and run sessions with much richer results. Use this tool only as a lightweight autocomplete fallback.

Partially update an existing AI assistant (persona).

Fetches the current configuration, applies only the fields you provide (leaving everything else intact), then writes the merged result back. Use this instead of create_assistant when you only want to change a few settings without resetting the rest.

Update an existing chat command by ID.

Omitted fields are left unchanged. Schedule fields (cron_schedule, sink_configs, run_as_user, assistant_name, etc.) follow the same partial-update semantics as the PAPI. Use clear_max_runs=True to remove an existing run cap (MCP cannot send bare null for max_runs).

Update an existing chat rule by ID.

Update an existing Knowledge Base article.

Only provided fields are updated; omitted fields remain unchanged.

Validate a script against the RunWhen contract before running it.

Checks that the script follows the required structure (main function, correct output format, etc.) and extracts referenced environment variables.

Task scripts must return/write issues with keys: 'issue title', 'issue description', 'issue severity' (1-4), 'issue next steps', and optionally 'issue observed at'.

Script-source parameter matrix (provide exactly one):

Skill: runwhen-skill://build-runwhen-task (full authoring workflow).

Ask the RunWhen AI assistant about your infrastructure.

This is the PRIMARY tool for investigating infrastructure. It sends your message to the RunWhen workspace AI agent, which searches (keyword, semantic, and fuzzy), navigates and correlates across resources, SLXs, issues, run sessions, and the knowledge base, and returns rich markdown reports, diagrams, and tables.

PREFER THIS TOOL over direct read/query tools (get_workspace_issues, get_workspace_slxs, search_workspace, etc.) for any question that involves searching by topic, keyword, or context — e.g. "issues related to neo4j", "what's failing in namespace X?", "health of the watcher cluster". workspace_chat produces materially better answers because it can search, filter, and correlate across all workspace data internally.

Use direct tools instead ONLY for: executing tasks (run_slx), task authoring, registry operations, chat config CRUD, KB mutations, or when you specifically need raw structured JSON for programmatic processing.

Returns: JSON with message, sessionId, widgets, chatUrl (full browser URL to continue this session in the RunWhen UI — run tasks, review history), and chatExportLink (shareable chat-export path when available).