Sora Commander

Overview Schema Source Related Servers Discussions Admin

run_task

Starts one named Owner task preset and opens the Owner approval window for each run; returns pending status so the operation can be continued.

Instructions

Start one Owner task preset by name; the normal Owner approval window opens for every run.

Same as run_command_wait with the preset's executable, argv, cwd, timeout and output_limit: same window, policy, results and pending flow. Use once per operation. On PENDING or timeout, continue through await_command_result with the returned pending_id; never call run_task again for the same operation. 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. An unknown name returns DENY UnknownTask and starts nothing.

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": {
      "name": "<name>"
    },
    "name": "run_task"
  }
}

Input Schema

Name	Required	Description
`name`	Yes	Exact preset name from list_tasks (lowercase letters, digits and hyphens). It selects the Owner's fixed command; no argument can be added or changed.
`request_id`	No	Optional original request correlation ID (32 lowercase hex characters); NOT Owner permission.
`wait_seconds`	No	Seconds to await Owner click and original job, 0 to 90; default 50. On timeout use await_command_result, not run_task again.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.1.5Nov 10, 2026

TDQS

A4.8/5.0

Behavior5/5

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

No annotations are provided, so the description carries the full burden, and it does: it discloses the Owner approval window on every run, the PENDING/timeout flow, the specific OWNER_SESSION_UNAVAILABLE/REVIEW_BUSY/OWNER_REVIEW_FAILED error states with launch_outcome NOT_STARTED meaning nothing ran, and that an unknown name returns DENY UnknownTask. It also warns that request_id is not Owner permission and that no arguments can be added or changed.

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 purpose, then the sibling equivalence, then the operational rules and error taxonomy in a logical order. It is dense but every clause carries a rule, with only mild redundancy between 'the normal Owner approval window opens for every run' and the later 'same window, policy, results and pending flow'.

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

Completeness5/5

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

Given an output schema exists, the description need not describe return values, and it covers everything else an agent needs for a mutation-with-approval tool: the approval gate, the pending/continuation protocol, error semantics, and the fact that failed launches started nothing. Nothing material is missing for correct invocation.

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 the baseline is 3; the description adds value by explaining that the name selects a fixed Owner command whose arguments cannot be modified, and that the preset supplies executable/argv/cwd/timeout/output_limit. It also reinforces wait_seconds' consequence (on timeout use await_command_result), though most per-parameter detail remains in the schema.

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?

States a specific verb and resource ('Start one Owner task preset by name') and immediately scopes it relative to the sibling run_command_wait, explaining that the preset supplies executable, argv, cwd, timeout and output_limit. An agent can distinguish it from run_command_wait and list_tasks without opening any 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?

Gives explicit when-to-use ('use once per operation'), when-not ('never call run_task again for the same operation'), and the alternative to use instead (await_command_result with the returned pending_id). It also tells the agent what to do on the error path rather than merely describing it.

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