ppsspp-dfx

Overview Schema Source Related Servers Discussions Admin

ppsspp_trace_memory_access

Find which code reads or writes a memory address by setting a temporary breakpoint, capturing the program counter, registers, and backtrace on hit, then removing the breakpoint.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`size`	No	Watch size in bytes: 1, 2, or 4 (default 4).
`access`	No	Access kind to trap: 'read', 'write', or 'read_write' (default 'read').	read
`address`	Yes	Address to trace, as a hex string (e.g. '0x08A0D000').
`timeout_s`	No	Wait budget in seconds (default 30, clamped to [0.5, 300]). On timeout: hit=false, breakpoint removed.
`session_id`	Yes	Active session ID.
`want_backtrace`	No	Include the HLE backtrace in the hit (CPU is paused at the hit, so the trace is valid).
`want_registers`	No	Include the full CPU register dump in the hit.

Output Schema

TableJSON Schema

Name	Required	Description
`hit`	Yes	True when at least one access was captured.
`hits`	Yes	Captured hits (pc/related_address hex strings; 'registers' / 'backtrace' included when requested).
`note`	Yes	Optional human context (e.g. cleanup caveats).
`access`	Yes	Access kind traced: 'read' / 'write' / 'read_write'.
`address`	Yes	Traced address, hex string.
`resumed`	Yes	True when the tool resumed the CPU it had seen running at arm time (a hit pauses the CPU; the tool restores it).
`timeout_s`	Yes	The wait budget that was applied.
`bp_removed`	Yes	True when the tool's memory breakpoint is confirmed gone (list-verified) — always true on normal return.
`already_paused`	Yes	True when the CPU was already paused at arm time — nothing can hit while paused, so no breakpoint was armed.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 16, 2026

TDQS

A4.7/5.0

Behavior5/5

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

The BEHAVIOR section is exemplary: it discloses that the tool MUTATES by arming a temporary breakpoint, guarantees the breakpoint is always removed even on error paths, explains the lock is only held for arm/capture/cleanup, and warns about the first-broadcast-wins race. This adds substantial behavioral context beyond the annotations, which are all false and provide no safety or mutation hints.

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 description is organized into PURPOSE, USAGE, BEHAVIOR, and RETURNS sections, making it scannable for an agent. Although long, nearly every sentence carries non-obvious operational detail, and the most important purpose and usage constraints are front-loaded.

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 7 parameters and complex runtime behavior, the description covers inputs, preconditions, concurrency hazards, cleanup guarantees, and the full return shape. The RETURNS field enumerates the result object with nested hit fields, so nothing essential is missing even without viewing the output schema.

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; the schema already documents defaults, ranges, and behavior for each parameter. The description mostly restates access types, size 1/2/4, timeout_s, and optional flags without adding new parameter-level meaning. It does add some context, like needing a running session, but this is more usage guidance than parameter 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 description opens with a specific purpose: 'One-call answer to what code reads/writes this address', and spells out the operational sequence (arm breakpoint, wait, capture pc, remove breakpoint, resume). This clearly differentiates it from sibling tools like ppsspp_breakpoint, ppsspp_step, and ppsspp_wait_breakpoint by framing it as a complete trace operation rather than a component.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The USAGE section explicitly states required inputs, optional flags, and a critical precondition: 'Game must be RUNNING (call after session wait_ready).' It also gives a clear exclusion rule: 'Do NOT run other breakpoint/step tools during the wait: the first cpu.stepping broadcast wins.' This tells the agent exactly when and how to invoke the tool, and what to avoid.

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