RunWhen Platform MCP

Run Script And Wait

run_script_and_wait

Execute a script, poll until completion, and return the full output in one call, replacing separate run, status-check, and output steps.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`script`	No	The full script source code (raw text).
`env_vars`	No	Environment variables for the script.
`location`	No	Runner location (use get_workspace_locations).
`run_type`	No	'task' or 'sli'.	task
`interpreter`	No	'bash' or 'python'.	bash
`script_path`	No	Local file path to read the script from. stdio mode only. Mutually exclusive with the other script_* params.
`secret_vars`	No	Secret mappings (env var name to workspace secret key).
`script_base64`	No	UTF-8 script as standard base64. Prefer over inline 'script' when JSON-escaping multiline content is error-prone.
`workspace_name`	Yes	The workspace to run in (e.g. 't-oncall').
`script_base64_path`	No	Local file path to a file containing the base64-encoded script. stdio mode only.
`script_gzip_base64`	No	UTF-8 script as base64(gzip(...)). Best inline option for scripts >5KB — 3-5x denser than 'script_base64'.
`runtime_var_overrides`	No	Per-run override values for script variables (name → value). Merged into envVars at test time. Overrides win on name collision.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Jul 7, 2026

TDQS

A4.3/5.0

Behavior4/5

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

With no annotations, the description must carry behavioral burden and largely does: it discloses the blocking wait semantics, the RunWhen main() contract per run_type/interpreter, and the non-obvious secret_vars behavior (values are file paths, not secrets). It omits timeout limits, failure/error semantics, and any rate-limit or permission requirements, so it is strong but not exhaustive.

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?

Front-loaded with purpose before the contract details, and bulleted structure keeps the dense content scannable. Given 12 parameters and a non-trivial execution contract, the length is mostly justified, though a few lines (e.g. the FD 3 pitfall) are verbose relative to their selection value.

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

Completeness4/5

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

For a 12-parameter execution tool with no annotations and an output schema (so returns need not be restated), the description covers the script contract, parameter selection, and secret handling. It is still missing timeout, error-handling, and permission/auth context needed to predict failure modes.

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 100%, so baseline is 3, but the description adds real meaning: it enumerates the mutually-exclusive script_* variants, recommends script_gzip_base64 for scripts over 5KB, and explains that secret_vars inject file paths rather than values. That is substantive semantics beyond the schema text.

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?

Names a specific verb+resource (execute a script) and states the composite behavior (run + poll + output) in the first line. It explicitly distinguishes itself from the sibling tools run_script, get_run_status, and get_run_output, so an agent can route without opening schemas.

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

Usage Guidelines4/5

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

States when to use it ('Use this instead of calling run_script + get_run_status + get_run_output separately') and names the concrete alternatives. It does not specify when NOT to use it, e.g. for long-running scripts where fire-and-poll may be preferable, so it falls short of full when/when-not coverage.

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

Deploy Server