ppsspp-dfx

Overview Schema Source Related Servers Discussions Admin

ppsspp_batch_step

Batch multiple PPSSPP automation steps—press, wait, state probe, screenshot—into one ordered sequence. Run it in the background to avoid client timeouts and monitor progress via status polling.

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.

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
`total`	No	Total steps in the batch
`action`	No	Always 'run'
`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'
`executed`	No	Steps actually executed (excludes skipped)
`succeeded`	No	Steps with status='success'
`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.

First observedv0.1.0Sep 16, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Beyond annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description discloses substantial behavioral detail: 'STATE-CHANGE,' session-lock hold duration, the 25s/30s budget-timeout interaction and BATCH_BUDGET_EXCEEDED error, per-step MCP progress semantics, foreground isError behavior with BATCH_STEP_FAILED, background immediate-submit semantics, and screenshot auto-skip during replay recording. This richly exceeds what the annotations convey.

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?

The description is long but organized into labeled PURPOSE/USAGE/BEHAVIOR/RETURNS sections that front-load the core intent and make scanning easy. The BEHAVIOR section is dense with critical operational facts that have no home in the schema, so its length is justified. Minor redundancy exists between USAGE and the already-rich schema parameter descriptions.

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?

For a tool with this complexity — four step types, two execution modes, timeout interactions, and failure semantics — the description is complete: error codes, return shapes for both foreground and background, lock behavior, and routing to status/cancel siblings are all present. With a 100%-coverage schema and an output schema present, nothing an agent needs to select and invoke this tool correctly 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%, so the baseline is 3 and the schema already documents every parameter thoroughly, including examples in the steps array and timeout context in background. The description's USAGE/RETURNS lines summarize this structure but add no meaning beyond the schema — the 60fps frame detail, budget rejection, and polling routes all also appear 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?

The PURPOSE line names a specific verb+resource: 'Execute an ordered automation sequence of press / wait / state_probe / screenshot steps in one call,' which immediately differentiates it from single-step siblings like ppsspp_press_button, ppsspp_wait_frames, and ppsspp_screenshot. It also names the optional detached-background mode, so an agent knows both what the tool does and how it differs from related tools.

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?

The USAGE line gives the required call shape (session_id + steps, on_failure, background), and the background parameter explicitly routes the agent to ppsspp_batch_status for polling and ppsspp_batch_cancel for cancellation, naming the sibling alternatives. However, it never explicitly says 'for a single press/wait/screenshot use the dedicated single-step tool,' so the when-not-to-use guidance is implied rather than stated.

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