Sora Commander

Overview Schema Source Related Servers Discussions Admin

run_command

Submit a legacy immediate command to a Windows PC and receive a pending ID when Owner review is required; use only for immediate submission, not normal waiting workflows.

Instructions

Legacy immediate-start API. REVIEW returns pending_id.

    interactive=True requires background=True and the DEV_ONLY isolated
    Python numeric REPL allowlist, with explicit local launch review.

    Prefer run_command_wait for normal work: it observes the Owner GUI
    click and returns job output without asking the Owner to type
    'approved'. Do not reissue a command merely to check its result.

Use only for legacy immediate command submission. A REVIEW result needs a later status/wait call; normally prefer run_command_wait. Owner approval is local to Windows. Never resubmit the same operation on timeout or UNKNOWN. 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"
  }
}

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.
`background`	No	Whether to return immediately after launch; default false, unlike the wait API.
`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.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.2Nov 9, 2026

TDQS

A4/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and does substantial work: Owner approval is local to Windows, REVIEW produces only a pending_id rather than output, interactive mode requires background plus the DEV_ONLY isolated Python REPL allowlist, and ERROR OwnerReviewUnavailable means nothing ran. It does not describe what the command can affect on the host or permission/rate constraints beyond 'local Owner policy', leaving some side-effect risk undisclosed.

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?

Front-loaded and broken into short paragraphs, but the 'prefer run_command_wait' guidance is repeated twice (mid-description and again in the closing paragraph), and the never-resubmit advice appears in two variants. Removing that duplication would tighten a description that already reads as dense internal documentation.

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 an 8-parameter command-execution tool with an output schema, it covers the async/review lifecycle, the non-resubmit rule, and the OwnerReviewUnavailable error semantics with its reason codes. It stops short of naming which sibling (await_command_result, review_status, status) to call after a REVIEW result, which would have closed the loop with the surrounding tool set.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3; every parameter already has its own description including ranges and defaults. The description adds only cross-parameter meaning for interactive (must be paired with background=True and the DEV_ONLY allowlist and is the correct choice only for isolated Python operation).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states this is a legacy immediate-start command submission API that returns a pending_id for REVIEW outcomes, which lets an agent separate it from the wait-style sibling. It is jargon-dense ('immediate-start', 'REVIEW') but the verb+resource is identifiable. It does not spell out plainly that it launches an OS process, though 'executable/argv/cwd' in the schema fill that in.

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?

Explicitly scoped: 'Use only for legacy immediate command submission' and 'Prefer run_command_wait for normal work', with the reason given (the wait API observes the Owner GUI click and returns output). It also gives a negative rule — 'Do not reissue a command merely to check its result' — and a follow-up path for REVIEW (a later status/wait call).

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