PURPOSE: Filter a PPSSPP log file for ERROR / WARNING / CRASH lines.

USAGE: log_path optional (defaults to the server-mirrored PPSSPP broadcast log at .ppsspp-dfx/output/ppsspp.log, written while a session runs); filter optional (keyword); session_id optional.

BEHAVIOR: READ-ONLY. Reads and filters a log file. Does not contact PPSSPP.

RETURNS: {log_path, matches: [{line_no, text}...], count, filter}.

PURPOSE: Convert an address between IDA and PPSSPP address spaces (offset ±0x08804000).

USAGE: address required; mode optional ('auto' default / 'ida_to_ppsspp' / 'ppsspp_to_ida'); session_id optional.

BEHAVIOR: READ-ONLY. Pure arithmetic on the address; no PPSSPP contact.

RETURNS: {original, converted, mode, top_base_ppsspp, top_base_ida}.

PURPOSE: Assemble MIPS instruction(s) and write the resulting bytes to memory.

USAGE: session_id + address + code ('

' or ';' separated — PPSSPP assembles one line per call so the tool loops; armips-style ';' comments are NOT supported here).

BEHAVIOR: DESTRUCTIVE. Protected ranges (kernel, top.prx code) need force=true. A partial write is reported with an error directing you to disassemble and inspect.

RETURNS: {address, code, bytes_written, response, text}.

PURPOSE: Simulate a single PSP button press for a duration.

USAGE: session_id + button required; duration optional (default 10 frames). Valid button names: cross / circle / triangle / square / up / down / left / right / start / select / ltrigger / rtrigger.

BEHAVIOR: STATE-CHANGE. Sends input events to PPSSPP. Button state returns to released after the duration elapses.

RETURNS: {button, duration}.

PURPOSE: Hold a combination of PSP buttons until a subsequent call changes the state.

USAGE: session_id + buttons required (pipe-separated combination, e.g. 'cross|circle'). Valid names: cross / circle / triangle / square / up / down / left / right / start / select / ltrigger / rtrigger.

BEHAVIOR: STATE-CHANGE. Sets button-held state in PPSSPP; persists until next hold_buttons / send_analog call.

RETURNS: {buttons}.

PURPOSE: Send an analog stick position (x, y in [0, 255], 128 = center).

USAGE: session_id + x + y required. 0 = full left / up, 255 = full right / down.

BEHAVIOR: STATE-CHANGE. Sets analog stick position; persists until next send_analog call.

RETURNS: {x, y}.

PURPOSE: Wait N frames (wall-clock sleep at 60 FPS by default) to let the emulator advance.

USAGE: session_id + frames required; interval optional (default 1/60 s).

BEHAVIOR: STATE-CHANGE. Sleeps the caller; emulator advances N frames. Session must be alive (validated before sleep).

RETURNS: {frames, elapsed_s}.

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}.

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}.

PURPOSE: Request cancellation of a queued or running background batch job.

USAGE: batch_id from ppsspp_batch_step(background=true).

BEHAVIOR: STATE-CHANGE. Cancels the detached task; the job's own finally block releases the session lock, so subsequent tool calls are free to use the session immediately. The abort happens at the current step boundary (a press finishes, a mid-wait cuts within ~1s). Cancelling an already-finished job is an error — check ppsspp_batch_status first if unsure.

RETURNS: {batch_id, status, note} — poll ppsspp_batch_status for the terminal state.

PURPOSE: Survey all background batch jobs currently retained by the registry — the list companion to ppsspp_batch_status / ppsspp_batch_cancel.

USAGE: no parameters. Use it to recover a batch_id after the submit response was lost (e.g. client timeout) or to survey background activity before touching the session.

BEHAVIOR: Lock-free registry read — never opens the WS transport and never waits for the per-session lock. Jobs appear in submission order; finished jobs beyond the retention window (retention_jobs, in job count) are already evicted and absent. READ-ONLY.

RETURNS: {jobs: [{batch_id, session_id, status: queued|running|completed|failed|cancelled, executed, total, error, result_present}], retention_jobs}.

PURPOSE: Set, remove, update, and list CPU execution breakpoints and memory watchpoints.

USAGE: action + session_id; set/remove/update manage CPU exec breakpoints (address required); mem_set/mem_remove/mem_update manage memory watchpoints (size 1/2/4+, read/write flags); list/mem_list take no address.

BEHAVIOR: MUTATING. Reliable hits need CPUCore=2 (IR Interpreter). mem_remove resolves the watchpoint's real size via mem_list first (address+size matching); mem_update merges existing read/write/change unconditionally (PPSSPP zero-omits omitted bools). CPU set/remove return no data — the tool follows with a list for verification.

RETURNS: {action, address, enabled, breakpoints[]}.

PURPOSE: Evaluate a debugger expression (register names, hex literals, simple arithmetic).

USAGE: session_id + expression. No '*addr' dereference syntax — read memory with read_u32 instead.

BEHAVIOR: READ-ONLY. Pauses/resumes the CPU internally.

RETURNS: {expression, value, response, text}.

PURPOSE: Capture the next rendered frame's GE command stream as a binary dump file.

USAGE: session_id. The CPU must be RUNNING — a paused GPU never flips a frame; the MCP pre-probe converts that into a clean CPU_STATE_ERROR.

BEHAVIOR: READ-ONLY. Captures to a binary file under output/gpu_dumps/ (not JSON).

RETURNS: {size_bytes, file_path, raw, text}.

PURPOSE: Query GPU counters — fps, vblanks per second, timing info.

USAGE: session_id. The CPU must be RUNNING; paused, the MCP pre-probe returns CPU_STATE_ERROR instead of hanging — which doubles as the cheapest paused-CPU probe.

BEHAVIOR: READ-ONLY.

RETURNS: {fps, vblanks_per_second, info, timing, raw, text}.

PURPOSE: Probe MCP server liveness and readiness without contacting PPSSPP. Use this before any session-dependent tool to verify the server is up.

USAGE: No parameters.

BEHAVIOR: READ-ONLY. Reads in-memory server counters (uptime, registered tool count, active session count). Does not contact PPSSPP and does not modify any state.

RETURNS: Dict with status ('ok'/'degraded'), version, python_version, pydantic_version, uptime_s, tool_count, session_count.

PURPOSE: List the project's known address constants from addresses.yaml — the single source of truth; never guess hex addresses.

USAGE: optional section filter; an unknown section returns an error listing the valid ones.

BEHAVIOR: READ-ONLY. Int values ≥0x1000 are returned as hex strings that can be pasted straight into address parameters.

RETURNS: {sections, count, section_filter}.

PURPOSE: Read memory (read_bytes / read_u32 / read_string) or scan a region for a byte pattern.

USAGE: action; session_id optional when exactly one session is active; address as '0x' hex string; read_bytes ≤65536 per call (split larger reads); scan takes pattern (hex/ascii, ≤4096B) + start_addr/end_addr (≤256MiB) + chunk_size.

BEHAVIOR: READ-ONLY. Unreadable scan blocks are skipped silently. read_u32 on JIT-IR code returns IR encoding (IR_ENCODING_DETECTED) — disassemble code instead. read_string is ASCII-only (use read_bytes + Shift-JIS decode for game text).

RETURNS: {action, address, value, size, text, file} — value is the match list for scan. read_bytes has output=value (default; byte list + hex text) / hex (text only, value=null) / file (paths + 64-byte preview; payload saved under .ppsspp-dfx/output/memory_reads/).

PURPOSE: Write u8/u16/u32 or raw bytes to memory.

USAGE: session_id + address ('0x' hex) + data + format ('u8'|'u16'|'u32'|'bytes'; bytes accepts hex or base64).

BEHAVIOR: DESTRUCTIVE. Protected ranges (kernel, top.prx code) need force=true (PROTECTED_ADDRESS).

RETURNS: {address, format, bytes_written, value, text}.

PURPOSE: Disassemble N MIPS instructions at a given address.

USAGE: address required; session_id optional when exactly one session is active; count optional (default 10).

BEHAVIOR: READ-ONLY. Calls memory.disasm via WebSocket. Does not modify memory or CPU state.

RETURNS: {address, count, instructions: [{address, text}...]}.

PURPOSE: Search PPSSPP's memory-tracking metadata for allocation/texture tags matching a string.

USAGE: session_id + match (case-insensitive substring, required); optional address/end/type filters.

BEHAVIOR: READ-ONLY. Returns a single extent per matching tag.

RETURNS: {regions[], count, raw, text}.

PURPOSE: Get the PPSSPP memory region map (user / kernel / VRAM ranges).

USAGE: session_id.

BEHAVIOR: READ-ONLY.

RETURNS: {ranges[], mapping, text}.

PURPOSE: Aggregate game-state queries — game_state, registers (all or one), backtrace, threads, modules, and function-list management (funcs/func_scan/func_add/func_remove).

USAGE: action + session_id; 'register' needs name; func_scan/func_remove need address; top_n defaults to 100 (pass 0 for the full list — hle.func.list can reach 700+KB).

BEHAVIOR: READ-ONLY. Lookups only — func_add/func_remove mutate the debugger function list. backtrace/threads/func_* REQUIRE the CPU paused (pause first, or use get_pc); RUNNING-state PC/isCurrent is LOW trust.

RETURNS: {action, data, trust_level} — data shape depends on the action.

PURPOSE: Safely read the current Program Counter.

USAGE: session_id optional when exactly one session is active.

BEHAVIOR: READ-ONLY. Pauses CPU temporarily for read consistency, then resumes. trust_level='high'.

RETURNS: {pc, trust_level}.

PURPOSE: Aggregate PPSSPP replay subsystem — record input sequences, execute them, and save/load .ppr recordings.

USAGE: action + session_id; actions: begin/abort/flush/execute/status/time_get/time_set/save/load/wait_complete; execute needs version + base64_input; time_set needs value; save/load take a bare file name (always under output/replays/).

BEHAVIOR: STATE-CHANGE. Recording requires the CPU RUNNING (real input timing); screenshots are rejected while recording. Replay timelines use ABSOLUTE game-clock timestamps anchored at the RECORDING session's boot — a replay only injects correctly when a fresh boot's clock is aligned to them: execute/load ONLY loads the event table and returns t0_s / estimated_end_s + the boot-aligned sequence (reset -> wait_ready -> wait boot+estimated_end_s -> abort); it does NOT play by itself. executing/saving NEVER clear on their own — only abort clears them — so wait_complete times out on any un-aborted replay; completion = the timeline estimate + explicit abort. execute/load auto-abort a live executing/saving state first (R4). restore_rtc defaults to False: setting it rewinds the game-visible wall clock of the RUNNING session and pollutes every in-game timer (R2); when needed, set it before the boot-aligned reset.

RETURNS: {action, executing, saving, version, size, base64, base_rtc, data} — execute/load data carries t0_s, estimated_end_s, event_count and boot_aligned_sequence; fields depend on the action.

PURPOSE: Capture the framebuffer as an image (ImageContent) plus metadata.

USAGE: session_id optional when exactly one session is active; source='render' (default; empty frames auto-fall back to VRAM — colors unreliable there) or 'output' (CRASH-RISK, do not use); mutually exclusive with the deprecated mode param.

BEHAVIOR: READ-ONLY. An empty capture returns empty=true instead of an error — advance to a rendered scene and retry.

RETURNS: structuredContent metadata (mode/source/size_bytes/width/height/file_path/format/empty); the image itself arrives as an ImageContent block. The auto-saved PNG/JPG path is in file_path.

PURPOSE: Dump the currently-bound GPU texture as an image plus metadata.

USAGE: session_id. Only the CURRENTLY bound texture — no VRAM-address targeting.

BEHAVIOR: READ-ONLY. An empty capture raises CAPTURE_EMPTY — enter a scene that renders and retry.

RETURNS: structuredContent metadata (level/file_path/size_bytes/format); the image itself arrives as an ImageContent block.

PURPOSE: Dump the currently-bound CLUT palette as an image plus metadata.

USAGE: session_id. Only the CURRENTLY bound palette can be captured — no VRAM-address targeting.

BEHAVIOR: READ-ONLY. An empty capture raises CAPTURE_EMPTY — advance to a scene that uses the palette and retry.

RETURNS: structuredContent metadata (file_path/size_bytes/format); the image itself arrives as an ImageContent block.

PURPOSE: List diagnostic scripts declared in .ppsspp-dfx/config/scripts.manifest.yaml.

USAGE: category optional filter (eboot / state / p0ab / ndx / memory / misc / recipe).

BEHAVIOR: READ-ONLY. Reads the in-memory manifest registry (loaded at startup). Does not execute any script.

RETURNS: {scripts: [ScriptEntryView...], count, category}.

PURPOSE: Invoke a manifest-registered diagnostic script by name with validated input.

USAGE: name (see ppsspp_list_scripts; skeleton scripts return not_implemented); input dict validated against the script's Pydantic model; session_id required when the script declares requires_ppsspp (missing → SESSION_NOT_FOUND).

BEHAVIOR: STATE-CHANGE. Runs manifest-registered script code. Unknown names → SCRIPT_NOT_FOUND.

RETURNS: {name, output, output_model}.

PURPOSE: Manually reload the script manifest YAML and clear the script module cache.

USAGE: No parameters.

BEHAVIOR: MUTATING. Re-reads the manifest file and invalidates cached script modules. Reversible: re-reading an unchanged file produces an equal registry. When the exposed tool set ACTUALLY changes (tools added or removed), the server notifies the client with a tool-list-changed notification so cached tools/list results are invalidated; a no-op reload sends nothing.

RETURNS: {reloaded_count, exposed_count, manifest_path, scripts: [ScriptEntryView...]}.

PURPOSE: Loop-search disassembly for a substring, collecting matching instructions with context.

USAGE: session_id + match (a leading '$' is stripped); start address; end=0 wraps the search around the whole region; max_results default 100.

BEHAVIOR: READ-ONLY.

RETURNS: {address, match, end, results[{address, text, name, params}], text}.

PURPOSE: Start / stop / inspect PPSSPP debug sessions — action=start / stop / get / wait_ready; wait_ready blocks until the emulated CPU is up.

USAGE: action='start' needs iso_path (pass wait_ready=true to block until the CPU is up in the same call); stop/get/wait_ready need session_id. Call wait_ready AFTER start and BEFORE any memory tool — PPSSPP answers WebSocket before the CPU boots. start(resilient=true) self-heals boot wedges (blacklist quarantine + relaunch with the same session_id, ≤2 retries).

BEHAVIOR: STATE-CHANGE. start spawns a PPSSPP subprocess + WS debugger; stop terminates it (never taskkill the process yourself); wait_ready polls the probe lock-free and fails [BOOT_TIMEOUT] on wedge suspicion; get is read-only.

RETURNS: SessionResponse {session_id, iso_path, pid, ws_url, created_at, last_active_at, exec_count, ws_connected, recovered, ppsspp_version} — or, for wait_ready, {action, ready, elapsed_s, probe_addr, probe_value, note}.

PURPOSE: List all active PPSSPP sessions.

USAGE: No parameters. Idle sessions (>30 min) are auto-GC'd as a side effect.

BEHAVIOR: READ-ONLY. Reads the session manager's in-memory session dict. The idle-GC side effect reaps stale sessions but does not mutate the caller's state.

NOT a per-session status probe: for session health use ppsspp_smoke_test; for CPU/game state use ppsspp_get_pc or ppsspp_query(game_state). Reader tools whose session_id is optional auto-resolve when exactly one session is active, so you normally do NOT need to call this first just to obtain an ID.

RETURNS: {sessions: [SessionResponse...], count}.

PURPOSE: Four-point session health check — iso_loaded, cpu_running, ws_connected, game_mode_valid.

USAGE: session_id. NOT an ISO boot-acceptance test — use session wait_ready + analyze_log for boot triage.

BEHAVIOR: READ-ONLY. Battery of probes.

RETURNS: {checks[{name, passed, detail}], overall_status}.

PURPOSE: Named memory-probe registry plus running-state observation — register probes once, then sample them cheaply every loop.

USAGE: action + session_id for observe; register needs name + address (+size 1/2/4, description); observe takes comma-separated names and samples.

BEHAVIOR: STATE-CHANGE. register/clear mutate the registry; observe is reliable while RUNNING. The registry is PROCESS-wide (shared across sessions), seeded from addresses.yaml state_probes, and is NOT re-seeded after clear within the same process. Delete semantics are IDEMPOTENT: clearing an unknown probe name succeeds (ok), unlike ppsspp_breakpoint mem_remove which rejects missing targets (F-5 contract, 2026-09-08).

RETURNS: {registered|probes|observations, count, success_count, failure_count} — shape depends on the action.

PURPOSE: Aggregate CPU step + run-state control (into / over / out, pause, resume, reset, run_until, next_hle).

USAGE: action='into' / 'over' / 'out' / 'pause' / 'resume' / 'reset' / 'next_hle' take only session_id (optional when exactly one session is active); 'run_until' requires address.

BEHAVIOR: STATE-CHANGE. Advances or changes CPU run state. 'reset' reboots the game (lost in-memory state). 'run_until' sets a temp breakpoint and resumes.

RETURNS: {action, address}.

PURPOSE: Block until a breakpoint hit (any kind) — replaces polling gpu_stats errors as a hit probe.

USAGE: session_id; timeout_s default 30. Arm a breakpoint first via ppsspp_breakpoint (set or mem_set). Use when you only need to know a hit happened; call ppsspp_trace_memory_access instead to capture the hit scene (registers/backtrace) in one step.

BEHAVIOR: READ-ONLY. Subscribes to the cpu.stepping broadcast and holds NO session lock — concurrent reads/observes keep working, but do NOT submit step/pause/resume during the wait. An already-paused CPU returns hit=true + already_paused=true with a high-trust pc (a manual pause is indistinguishable from a hit).

RETURNS: {hit, already_paused, timeout_s, pc, reason, related_address, ticks} — timeout returns hit=false (pollable, not an error); reason/related_address may be null on some builds.

PURPOSE: One-call paused scene snapshot — pause (unless already paused), capture pc + registers + optional named probes, then resume.

USAGE: session_id; probes = optional comma-separated state_observer registry names; want_registers default true. Prefer this over a manual pause + query(registers) + resume sequence.

BEHAVIOR: STATE-CHANGE. The session lock is held for the whole call (pause→capture→resume is short). A CPU we paused is resumed before returning; an already-paused CPU stays paused. A failing capture never leaves the game frozen.

RETURNS: {was_stepping, resumed, pc, trust_level, registers, probes} — registers/probes keys are ALWAYS present; they carry null when opted out (want_registers=false / probes omitted) — F-8 nullable-key contract, 2026-09-08.

PURPOSE: One-call answer to 'what code reads/writes this address' — arm a memory breakpoint, wait for the hit, capture pc (+registers/backtrace), remove the breakpoint, and resume.

USAGE: session_id + hex address; access='read'|'write'|'read_write' (default read); size 1/2/4 (default 4); timeout_s default 30; want_registers/want_backtrace optional. Game must be RUNNING (call after session wait_ready).

BEHAVIOR: MUTATING. Arms a temporary breakpoint and always removes it (list-verified real-size removal). The lock is held only for arm/capture/cleanup — the wait is lock-free (concurrent reads OK). Do NOT run other breakpoint/step tools during the wait: the first cpu.stepping broadcast wins. An already-paused CPU short-circuits (nothing can hit). Error paths still remove the breakpoint and resume.

RETURNS: {hit, already_paused, address, access, timeout_s, hits:[{pc, related_address, reason, ticks, mem_hits?, registers?, backtrace?}], bp_removed, resumed, note}. reason/related_address may be null on some builds; mem_hits is the attribution counter.

PURPOSE: Set a CPU register (GPR/FPU/VFPU names, plus pc/hi/lo).

USAGE: session_id + name (MIPS ABI names only — 'r5' normalizes to 'v1') + value (hex).

BEHAVIOR: DESTRUCTIVE. Pauses and resumes the CPU automatically (REQUIRED_STEPPING handled internally) — no manual pause needed.

RETURNS: {name, value, response, text}.