Sora Commander

Overview Schema Source Related Servers Discussions Admin

run_command_wait

Run local commands that require Owner GUI approval, wait for approval and bounded output, then continue with the returned pending ID on timeout instead of reissuing.

Instructions

Run, wait for local Owner approval, then return bounded output.

    interactive=True opts into the DEV_ONLY isolated numeric Python REPL.
    Use wait_seconds=0 for prompt asynchronous observation, then send_input.

    Owner permission comes only from the Windows GUI, not MCP. On a
    wait timeout use await_command_result(pending_id) or existing output
    tools; never repeat run_command_wait to avoid duplicate execution.

Preferred command submission for tasks needing Owner GUI approval and a bounded wait for output. Use once per operation. On PENDING or timeout, continue through await_command_result with the returned pending_id; never reissue this command. ERROR OwnerReviewUnavailable (reason OWNER_SESSION_UNAVAILABLE, REVIEW_BUSY or OWNER_REVIEW_FAILED; launch_outcome NOT_STARTED) means no Owner dialog was shown and nothing ran: report it and wait for the Owner, never resubmit automatically.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "executable": "<executable>",
      "argv": "<argv>",
      "cwd": "<cwd>"
    },
    "name": "run_command_wait"
  }
}

Input Schema

Name	Required	Description
`cwd`	Yes	Absolute working directory for the process within the local Owner policy.
`argv`	Yes	Exact string argument vector for one command; avoid credentials, scripts or private file content.
`timeout`	No	Execution timeout in seconds, 0.01 to 3600; default 5.
`executable`	Yes	Absolute path to the program binary; this is not a shell command string.
`request_id`	No	Optional original request correlation ID (32 lowercase hex characters); NOT Owner permission.
`interactive`	No	DEV_ONLY opt-in stdin PIPE for an Owner-reviewed isolated Python numeric REPL; default false. Requires background or asynchronous invocation.
`output_limit`	No	Maximum captured output bytes, 128 to 65536; default 8192.
`wait_seconds`	No	Seconds to await Owner click and original job, 0 to 90; default 50. On timeout use await_command_result, not run_command_wait again.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.2Nov 9, 2026

TDQS

A4.6/5.0

Behavior5/5

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

No annotations are supplied, so the description carries the full burden and does so: it discloses that Owner permission comes only from the Windows GUI and not MCP, that interactive mode is DEV_ONLY and requires background/async invocation, that output is bounded, and that duplicate execution is a real hazard. It further documents a named error surface (OwnerReviewUnavailable) with reason codes and the guarantee that launch_outcome NOT_STARTED means nothing executed — exactly the operational context an agent cannot infer.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The critical warning is front-loaded and the error guidance is well structured, but the central rule 'never repeat run_command_wait / use await_command_result' is stated three separate times across the description, which is redundant bulk in a tool an agent may read under time pressure. Tightening to one statement plus the error paragraph would lose no information.

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?

An output schema exists, so return-value explanation is correctly omitted, and the description covers the risky parts an agent must know: approval flow, async pattern, timeout behavior, and duplicate-execution avoidance. Minor residual gap: it does not state how this differs operationally from plain run_command when no approval wait is wanted, which an agent choosing between the two siblings must infer.

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 description coverage is 100%, so the schema already documents all eight parameters and baseline is 3. The description adds real meaning beyond it for the two parameters that matter semantically: interactive=True opts into an isolated numeric REPL, and wait_seconds=0 is the async-observation mode — neither of which is derivable from the type/default alone.

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?

The opening sentence names a specific verb chain (run, wait for Owner approval, return bounded output), which distinguishes it functionally from run_command (no wait) and await_command_result (resume after the fact). The interactive/REPL mode is also called out explicitly, so an agent can tell what class of operation this is before 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 Guidelines5/5

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

Usage is explicit and conditional: use wait_seconds=0 for asynchronous observation then send_input; on a wait timeout use await_command_result(pending_id) or existing output tools; never repeat run_command_wait. The exclusions ('never reissue this command') and the error-recovery path (OWNER_SESSION_UNAVAILABLE / REVIEW_BUSY / OWNER_REVIEW_FAILED means nothing ran) give the agent a complete decision tree including alternatives.

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