ppsspp-dfx

Overview Schema Source Related Servers Discussions Admin

ppsspp_batch_status

Read-onlyIdempotent

Check the status and progress of a background batch job using its batch ID. Returns queued, running, completed, failed, or cancelled state with executed step counts, without acquiring session locks.

Instructions

PURPOSE: Poll the state and progress of a background batch job without touching the session.

USAGE: batch_id from ppsspp_batch_step(background=true).

BEHAVIOR: Lock-free registry read — never opens the WS transport and never waits for the per-session lock, so it is safe to call while a background batch (or any other tool) owns the session. Executed-step count updates as steps complete; 'completed' carries the full foreground-shaped result. READ-ONLY.

RETURNS: {batch_id, session_id, status: queued|running|completed|failed|cancelled, executed, total, error, result, retention_jobs}.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`batch_id`	Yes	Job id returned by ppsspp_batch_step(background=true).

Output Schema

TableJSON Schema

Name	Required	Description
`error`	Yes	Error message if failed/cancelled
`total`	Yes	Total steps in the batch
`result`	Yes	Final ppsspp_batch_step-shaped response; present once the batch completed
`status`	Yes	'queued' / 'running' / 'completed' / 'failed' / 'cancelled' (protocol Tasks mapping: 'queued'→'working')
`batch_id`	Yes	Job id
`executed`	Yes	Steps executed so far
`session_id`	Yes	Session the batch runs on
`retention_jobs`	Yes	Finished-job retention window of the registry (in job count, not seconds): completed/failed/cancelled jobs beyond the oldest this many are evicted. Precursor of the protocol-level Task ttl.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 16, 2026

TDQS

A4.5/5.0

Behavior5/5

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

The description goes well beyond the readOnly/idempotent annotations by disclosing the lock-free registry read behavior, that it never opens the WS transport, and that it is safe during session-owning operations. It also explains how executed-step counts update and what 'completed' contains.

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

Conciseness5/5

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

Clearly sectioned PURPOSE, USAGE, BEHAVIOR, and RETURNS makes the content scannable and front-loaded. Every section contributes distinct, useful information without repetition.

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?

With one simple parameter, strong annotations, and a full RETURNS breakdown, the description gives the agent everything needed to call the tool correctly and interpret its result.

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 single parameter's schema description already explains that batch_id is returned by ppsspp_batch_step(background=true). The description reinforces this but adds little beyond the schema's own documentation.

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 states a specific verb and resource: polls the state and progress of a background batch job. It also clarifies what it does not do ('without touching the session'), distinguishing it from other batch tools like ppsspp_batch_cancel and ppsspp_batch_list.

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?

USAGE explicitly tells the agent where to get batch_id (from ppsspp_batch_step(background=true)), giving clear invocation context. It also explains when it is safe to call, though it does not explicitly contrast it with alternatives.

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