RunWhen Platform MCP

Validate Script

validate_script

Check a script against the RunWhen contract before execution to confirm required structure and output format, and extract referenced environment variables.

Instructions

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):

Variant	Best for	Mode
script	Small scripts <~5KB, readable	any
script_base64	Any size; safe JSON escaping	any
script_gzip_base64	>5KB; 3-5x denser than b64	any
script_path	Local file, raw text	stdio only
script_base64_path	Local file containing base64 blob	stdio only

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

Input Schema

TableJSON Schema

Name	Required	Description	Default
`script`	No	The full script source code (raw text).
`task_type`	No	'task' (returns issues) or 'sli' (returns 0-1 metric).	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.
`script_base64`	No	UTF-8 script as standard base64. Prefer over inline 'script' when JSON-escaping multiline content is error-prone. Mutually exclusive with the other script_* params.
`script_base64_path`	No	Local file path to a file containing the base64-encoded script. stdio mode only. Convenient when the agent has already written the encoded script to a scratch file. Mutually exclusive with the other script_* params.
`script_gzip_base64`	No	UTF-8 script as base64(gzip(...)). Best inline option for scripts >5KB — typically 3-5x denser than 'script_base64'. Encode with: base64.b64encode(gzip.compress(script.encode())).decode(). Mutually exclusive with the other script_* params.

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 carries the behavioral burden and does reasonably well: it discloses the checks performed (structure, main function, output format), the side effect of extracting referenced environment variables, and the task-script issue-key contract. It does not state side effects, idempotency, or failure behavior, but it does convey that validation is a non-executing pre-flight step.

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 the primary purpose, then a compact variant table that earns its space by compressing five mutually exclusive options into a scannable grid. The issue-key paragraph is slightly dense but necessary; overall minimal waste.

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?

Given 7 parameters, a 100% covered schema, an output schema, and no annotations, the description supplies the contract rules, mode constraints, and variant guidance an agent needs to call it correctly. Minor gap: no mention of what a failed validation looks like or whether it can ever mutate state.

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 already 100%, so the baseline is 3; the variant matrix pushes it higher by explaining the selection tradeoffs (small vs. large scripts, density, escaping safety) and the 'provide exactly one' mutual-exclusion rule, adding real decision value beyond the per-property descriptions.

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?

Specific verb (validate) plus resource (script) plus the standard it is checked against (the RunWhen contract), with the temporal scope 'before running it' that separates it from the run_script/run_script_and_wait siblings. An agent can tell exactly what this does without opening the schema.

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?

It clearly states the context of use ('before running it') and enumerates which script-source variant fits which situation, including the stdio-only limitation for path-based variants. It stops short of explicitly naming the run siblings it precedes (run_script, run_script_and_wait), so the routing is implied rather than spelled out.

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

Deploy Server