ppsspp-dfx

Overview Schema Source Related Servers Discussions Admin

ppsspp_read_memory

Read-onlyIdempotent

Read PPSSPP emulator memory or scan for byte patterns to debug PSP games. Supports reading raw bytes, 32-bit integers, strings, and hex/ASCII pattern searches.

Instructions

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/).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`size`	No	Number of bytes to read (read_bytes only).
`action`	Yes	Read action. Valid values: - 'read_bytes': read raw bytes (requires address + size). - 'read_u32': read a 32-bit unsigned int (requires address). - 'read_string': read a string (requires address). - 'scan': scan memory for a pattern (requires pattern + start_addr + end_addr). Optional max_results (default 100).
`length`	No	(deprecated, ignored) PPSSPP memory.readString does not accept a length parameter. Kept for backward schema compatibility.
`output`	No	Payload channel for read_bytes (ignored by other actions). 'value' (default) returns the byte list inline plus a hex dump in `text`. 'hex' keeps only the hex dump in `text` (value=null) — roughly half the characters. 'file' saves raw bytes + hex dump under .ppsspp-dfx/output/memory_reads/ and returns the paths plus a 64-byte preview — use for reads near the 65536-byte cap.	value
`address`	No	Starting address for read_bytes/read_u32/read_string, as a hex string (e.g. '0x08804000'). Ignored for scan (use start_addr).	0x0
`max_len`	No	Maximum string length in bytes for read_string (0 = default cap 4096). Always uses read_bytes + local NUL scan — PPSSPP memory.readString is never called (its strnlen scans to memory end and a giant response can kill the WebSocket). Values are clamped to 65536. Ignored for other actions.
`pattern`	No	Pattern to scan for (scan only). Interpreted according to `pattern_type`: 'hex' (default) expects even-length hex digits like 'AABBCCDD'; 'ascii' treats the string as literal ASCII bytes like 'hello'.
`end_addr`	No	Scan end address, exclusive (scan only), hex string (same format as `address`).	0x0
`chunk_size`	No	Bytes per read request during scan (scan only, default 4096). Larger values reduce round-trips but increase per-read latency.
`session_id`	No	Active session ID; omit to auto-resolve when exactly one session is active.
`start_addr`	No	Scan start address, inclusive (scan only), hex string (same format as `address`).	0x0
`max_results`	No	Maximum number of matches to return (scan only, default 100).
`pattern_type`	No	How to interpret `pattern` (scan only). 'hex' (default) decodes as hex string; 'ascii' encodes the pattern string as literal ASCII bytes.	hex

Output Schema

TableJSON Schema

Name	Required	Description
`file`	Yes	Absolute path of the saved raw-byte file when read_bytes ran with output='file' (hex dump sits beside it as <file>.hex.txt); empty string otherwise.
`size`	Yes	Number of bytes read (read_bytes), or number of matches (scan). Unused for read_u32 / read_string.
`text`	Yes	Unified text representation following spec conventions: '0xADDR: VAL (0xVAL_HEX)' for read_u32, hex dump for read_bytes, repr for read_string, 'scan: N matches at 0xA1, 0xA2, ...' for scan.
`value`	Yes	Read value (int/str/list[int]/list[dict] depending on action).
`action`	Yes	Read action performed ('read_bytes'/'read_u32'/'read_string'/'scan').
`address`	Yes	Starting address, hex string (e.g. '0x08804000').

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 16, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the readOnly/idempotent/non-destructive annotations, it discloses silent skipping of unreadable scan blocks, the IR_ENCODING_DETECTED sentinel for JIT-IR, ASCII-only string handling, and the exact return payload fields. No annotation contradiction exists.

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?

The PURPOSE/USAGE/BEHAVIOR/RETURNS structure front-loads the core capability and packs each sentence with operational detail; there is no filler and the caveats are placed where they are likely to be consulted.

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 13-parameter memory tool with rich annotations, the description covers invocation, limits, return shape, and edge cases; nothing needed to call it correctly appears missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, the description still adds meaning: byte-size limits, split-large-read guidance, scan range and chunk-size trade-offs, max_len's 4096 cap and NUL-scan behavior, and output-mode selection guidance for near-cap reads.

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 ('Read memory') and enumerates the four concrete actions (read_bytes, read_u32, read_string, scan), clearly distinguishing the read/scan scope from write, assemble, and disassemble siblings.

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?

Gives explicit operational constraints (size cap, split larger reads, scan region limits, chunk_size) and one direct routing cue: use disassemble instead of read_u32 on JIT-IR code. It does not broadly compare this tool to all read-related siblings, but the guidance provided is concrete and actionable.

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