ppsspp-dfx

Overview Schema Source Related Servers Discussions Admin

ppsspp_diff_memory

Read-only

Snapshot a PPSSPP memory range, then compare it after game actions to list changed addresses and bytes, helping locate dynamic variables.

Instructions

PURPOSE: Snapshot a memory range and diff it against current memory — the classic "what changed?" variable-locator.

USAGE: diff_memory(action="snapshot", start=..., end=...) → handle; act in game; diff_memory(action="compare", handle=...) → changed-byte list; action="drop"/"list" manage handles.

BEHAVIOR: READ-ONLY. Memory is never written — only the per-server snapshot registry mutates. Large ranges are read across multiple reads; per-snapshot cap 8 MiB; registry cap 4 with FIFO eviction. The registry is process-global: parallel sessions share one cap and FIFO order, so another session's snapshots can evict yours under load. compare requires the handle's exact range.

RETURNS: snapshot → {handle, start, size_bytes, checksum}; compare → {handle, start, size_bytes, changed_count, truncated, changes: [{address, old, new}]}; drop → {handle, dropped}; list → {handles: [...], count, max_snapshots}.

Input Schema

TableJSON Schema

Name	Required	Description
`end`	No	Range end (exclusive), same format — required for snapshot unless 'address'+'size' are given.
`size`	No	Range length in bytes. Provided for naming consistency with read_memory/write_memory/scan, which all take 'size'. Use either address+size or start+end.
`start`	No	Range start, hex ('0x08804000') or decimal — required for snapshot unless 'address'+'size' are given.
`action`	Yes	Diff operation. Valid values: - 'snapshot': read [start, start+size) and store it under a new handle (registry cap 4, FIFO eviction). - 'compare': read the same range now and diff against the handle's snapshot; returns a changed-byte list (inline cap 256, truncated flag keeps the true count). - 'drop': release a handle. - 'list': live handles.
`handle`	No	Snapshot handle — required for compare/drop.
`address`	No	Range start, same format as 'start'. Provided for naming consistency with read_memory/write_memory/scan, which all take 'address'. Use either address+size or start+end.
`session_id`	No	Active session ID; auto-resolved when exactly one session is active (required for snapshot/compare, ignored for drop/list).

Output Schema

TableJSON Schema

Name	Required	Description
`count`	No	Number of live snapshots.
`start`	No	Start address (hex).
`handle`	No	Dropped handle.
`changes`	No	First N changed bytes (address + old/new).
`dropped`	No	True when the handle existed and was removed.
`handles`	No	Live snapshot handles (oldest first).
`checksum`	No	sha256 of the snapshot bytes (first 16 hex).
`truncated`	No	True when changes exceed the inline cap (see changes list).
`size_bytes`	No	Compared range size in bytes.
`changed_count`	No	Total changed bytes.
`max_snapshots`	No	Registry capacity (FIFO eviction).

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv0.1.7Oct 7, 2026

changedInput schema / properties / action / description

Previous value: -"Diff operation. Valid values:\n- 'snapshot': read [start, start+size) and store it under a new handle (registry cap 4, FIFO eviction).\n- 'compare': read the same range now and diff against the handle's snapshot — returns changed-byte list (inline cap 256, truncated flag keeps the true count).\n- 'drop': release a handle.\n- 'list': live handles."New value: +"Diff operation. Valid values:\n- 'snapshot': read [start, start+size) and store it under a new handle (registry cap 4, FIFO eviction).\n- 'compare': read the same range now and diff against the handle's snapshot; returns a changed-byte list (inline cap 256, truncated flag keeps the true count).\n- 'drop': release a handle.\n- 'list': live handles."

addedInput schema / properties / address

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Range start, same format as 'start'. Provided for naming consistency with read_memory/write_memory/scan, which all take 'address'. Use either address+size or start+end.",
+  "title": "Address"
+}

changedInput schema / properties / end / description

Previous value: -"Range end (exclusive), same format — required for snapshot."New value: +"Range end (exclusive), same format — required for snapshot unless 'address'+'size' are given."

addedInput schema / properties / size

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Range length in bytes. Provided for naming consistency with read_memory/write_memory/scan, which all take 'size'. Use either address+size or start+end.",
+  "title": "Size"
+}

changedInput schema / properties / start / description

Previous value: -"Range start, hex ('0x08804000') or decimal — required for snapshot."New value: +"Range start, hex ('0x08804000') or decimal — required for snapshot unless 'address'+'size' are given."

Addedv0.1.6Oct 4, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, yet the description adds substantial behavior beyond that: the per-snapshot 8 MiB cap, registry cap of 4 with FIFO eviction, and critically the process-global registry shared across parallel sessions so another session can evict your snapshots. These are non-obvious operational traits that materially change how an agent should use the tool.

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?

Four labeled sections (PURPOSE/USAGE/BEHAVIOR/RETURNS) front-load the most important information and every sentence carries payload — caps, eviction semantics, return shapes. No filler or redundancy.

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 7-parameter tool with annotations and an output schema, the description closes the remaining gaps: cross-action parameter requirements, registry capacity and eviction behavior, session-sharing hazards, and return payloads. An agent has everything needed to invoke it correctly.

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

Parameters4/5

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

Schema coverage is already 100%, so the baseline is 3, but the USAGE and RETURNS blocks add call-shape meaning beyond the schema: which params belong to which action (handle required for compare/drop, session_id ignored for drop/list) and what each action returns. The clarification that compare requires the handle's exact range is genuine added semantics.

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 gives a specific verb+resource with an evocative framing (“classic 'what changed?' variable-locator”) that makes the tool instantly identifiable. It is clearly distinguishable from read_memory, write_memory, and scan, which the description later references by name.

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 section lays out the exact workflow (snapshot → act in game → compare) and enumerates how each of the four actions is invoked. It does not, however, state when to prefer this over overlapping siblings like scan or watch_value, so an agent gets strong invocation guidance but no exclusion criteria.

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