ppsspp-dfx

Overview Schema Source Related Servers Discussions Admin

ppsspp_batch_step

Execute an ordered sequence of press, wait, state probe, and screenshot steps on the PPSSPP emulator in one call. Optionally run it as a background task that outlives client timeouts.

Instructions

PURPOSE: Execute an ordered automation sequence of press / wait / state_probe / screenshot steps in one call, optionally on a detached background task that outlives the client timeout.

USAGE: session_id + steps:[{type: press|wait|state_probe|screenshot, ...}]; on_failure='continue'|'abort' (default continue); background=false|true.

ROUTING: ordered multi-step automation -> here; single CPU-step -> ppsspp_step; background job survey -> ppsspp_batch_status(batch_id omitted). BEHAVIOR: STATE-CHANGE. Foreground (default) holds the session lock for the whole batch; frames are 60fps wall-clock equivalents; sequences estimated >25s are rejected up-front with BATCH_BUDGET_EXCEEDED (the MCP client aborts tool calls at ~30s, killing the remaining steps server-side). Per-step MCP progress is reported when the client requests it. background=true validates and submits instantly, returns {action:'submitted', batch_id,...}, keeps the session lock for the batch duration, and reports progress via ppsspp_batch_status. If any foreground step fails the whole call is isError BATCH_STEP_FAILED — inspect results[] per step. Screenshots are auto-skipped during replay recording.

RETURNS: foreground {total, executed, succeeded, failed, skipped, recording_mode, results[], aborted}; background {action:'submitted', batch_id, session_id, total, estimated_s, hint}.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`steps`	Yes	Ordered list of step dicts to execute. Each step must have a 'type' field. Supported types: - press: {type:'press', button:'cross', duration:30} - wait: {type:'wait', frames:60} - state_probe: {type:'state_probe', names:'game_mode', samples:1} - screenshot: {type:'screenshot', source:'render'}
`background`	No	Run on a detached server task that survives the MCP client's ~30s tool-call timeout (default false). Foreground calls exceeding the 25s budget are rejected with BATCH_BUDGET_EXCEEDED; background calls return a batch_id immediately — poll ppsspp_batch_status for progress and the final result, cancel via ppsspp_batch_cancel. Background jobs have no per-step MCP progress notifications; use the status poll.
`on_failure`	No	What to do when a step fails (default 'continue'). 'continue' keeps running subsequent steps; 'abort' stops the batch immediately. Screenshot steps that are skipped due to recording mode are NOT failures.	continue
`session_id`	Yes	Active session ID.

Output Schema

TableJSON Schema

Name	Required	Description
`hint`	No	How to poll / cancel this background batch
`total`	No	Total steps in the batch
`action`	No	Always 'submitted'
`failed`	No	Steps with status='failure'
`aborted`	No	Whether batch aborted early on failure
`results`	No	Per-step results, in order
`skipped`	No	Steps with status='skipped'
`batch_id`	No	Job id for ppsspp_batch_status / _cancel
`executed`	No	Steps actually executed (excludes skipped)
`succeeded`	No	Steps with status='success'
`session_id`	No	Session the batch will execute on
`estimated_s`	No	Heuristic wall-clock estimate in seconds
`abort_reason`	No	Empty if not aborted
`recording_mode`	No	Whether session was recording a replay when batch ran

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedv0.1.6Oct 4, 2026

addedInput schema / $defs / CpuStepStep

Added value: +{
+  "description": "{type:'cpu_step', mode, count} — N CPU instructions (into/over/out).",
+  "properties": {
+    "count": {
+      "description": "Number of CPU steps to execute (1..1000; default 1).",
+      "title": "Count",
+      "type": "integer"
+    },
+    "mode": {
+      "description": "CPU stepping mode: 'into', 'over', or 'out'.",
+      "enum": [
+        "into",
+        "over",
+        "out"
+      ],
+      "title": "Mode",
+      "type": "string"
+    },
+    "type": {
+      "const": "cpu_step",
+      "title": "Type",
+      "type": "string"
+    }
+  },
+  "required": [
+    "type",
+    "mode",
+    "count"
+  ],
+  "title": "CpuStepStep",
+  "type": "object"
+}

addedInput schema / properties / steps / items / discriminator / mapping / cpu_step
```
Added value: +"#/$defs/CpuStepStep"
```

changedInput schema / properties / steps / items / oneOf

Previous value: -[
-  {
-    "$ref": "#/$defs/PressStep"
-  },
-  {
-    "$ref": "#/$defs/WaitStep"
-  },
-  {
-    "$ref": "#/$defs/StateProbeStep"
-  },
-  {
-    "$ref": "#/$defs/ScreenshotStep"
-  }
-]New value: +[
+  {
+    "$ref": "#/$defs/PressStep"
+  },
+  {
+    "$ref": "#/$defs/WaitStep"
+  },
+  {
+    "$ref": "#/$defs/StateProbeStep"
+  },
+  {
+    "$ref": "#/$defs/ScreenshotStep"
+  },
+  {
+    "$ref": "#/$defs/CpuStepStep"
+  }
+]

changedOutput schema / properties / action / description

Previous value: -"Always 'run'"New value: +"Always 'submitted'"

addedOutput schema / properties / batch_id

Added value: +{
+  "description": "Job id for ppsspp_batch_status / _cancel",
+  "title": "Batch Id",
+  "type": "string"
+}

addedOutput schema / properties / estimated_s

Added value: +{
+  "description": "Heuristic wall-clock estimate in seconds",
+  "title": "Estimated S",
+  "type": "number"
+}

addedOutput schema / properties / hint

Added value: +{
+  "description": "How to poll / cancel this background batch",
+  "title": "Hint",
+  "type": "string"
+}

addedOutput schema / properties / session_id

Added value: +{
+  "description": "Session the batch will execute on",
+  "title": "Session Id",
+  "type": "string"
+}

Changed1 schema field changedv0.1.4Sep 17, 2026

addedInput schema / $defs / PressStep / properties / button / enum

Added value: +[
+  "cross",
+  "circle",
+  "triangle",
+  "square",
+  "up",
+  "down",
+  "left",
+  "right",
+  "start",
+  "select",
+  "home",
+  "screen",
+  "note",
+  "ltrigger",
+  "rtrigger",
+  "hold",
+  "wlan",
+  "remote_hold",
+  "vol_up",
+  "vol_down",
+  "disc",
+  "memstick",
+  "forward",
+  "back",
+  "playpause"
+]

First observedv0.1.0Sep 16, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations declare the mutation profile (readOnlyHint=false, idempotentHint=false) but the description adds substantial context beyond them: the session lock is held for the whole batch, sequences estimated >25s are rejected with BATCH_BUDGET_EXCEEDED because the client aborts at ~30s, foreground failure makes the whole call isError BATCH_STEP_FAILED, background returns a batch_id immediately, and screenshots are auto-skipped during replay. This is a rich, non-obvious behavioral disclosure.

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/USAGE/ROUTING/BEHAVIOR/RETURNS headers that make it scannable, and each section earns its place given the tool's complexity. It is dense and long, but the structure keeps it navigable rather than wasteful.

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?

Despite an existing output schema, the definition covers everything an agent needs: supported step types, budget/timeout constraints, lock behavior, failure semantics, background submission flow, and progress reporting. Nothing critical for correct invocation is missing.

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% and the schema already documents session_id, steps, on_failure, and background with detailed per-field descriptions and a discriminator. The description largely restates the defaults already present in the schema, adding only marginal framing, so baseline 3 applies.

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 ('Execute'), the resource ('ordered automation sequence'), and the exact step types (press/wait/state_probe/screenshot), plus the background variant. The ROUTING line explicitly separates it from ppsspp_step and ppsspp_batch_status, so an agent can identify it 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?

ROUTING gives explicit when-to-use routing: ordered multi-step automation goes here, single CPU-step goes to ppsspp_step, background job survey goes to ppsspp_batch_status. Alternatives and the condition selecting them are named outright.

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