ppsspp-dfx

Overview Schema Source Related Servers Discussions Admin

ppsspp_state_observer

Instructions

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.

ROUTING: recurring sampled probes across loops -> here; one-shot paused snapshot -> ppsspp_frame_snapshot; single-address access watch -> ppsspp_breakpoint(action="trace"). BEHAVIOR: STATE-CHANGE. register/clear mutate the registry; observe is reliable while RUNNING. The registry is PER-SESSION (keyed by session_id), seeded from addresses.yaml state_probes; clear removes user-registered probes only, so the configured baseline survives. Delete semantics are IDEMPOTENT: clearing an unknown probe name succeeds (ok), unlike ppsspp_breakpoint mem_remove which rejects missing targets.

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

Input Schema

TableJSON Schema

Name	Required	Description	Default
`name`	No	Probe name. Required for action='register'; optional for action='observe' (comma-separated names; omit to observe all registered probes). Ignored for list / clear.
`size`	No	Read width in bytes (1 = u8, 2 = u16, 4 = u32). Default 4. Used by action='register'. Ignored for all other actions (probe's stored size is used at observe time).
`names`	No	Comma-separated probe names for action='observe'. If empty, all registered probes are observed. Ignored for all other actions.
`action`	Yes	Observer operation. Valid values: - 'register': add a probe to the runtime registry (requires name + address; optional size default 4, optional description). - 'list': list all registered probes. - 'observe': read current value of named probe(s) (optional names — omit to observe all); optional samples (default 1) for multi-sample median. - 'clear': clear the runtime registry.
`address`	No	Required for action='register'. Absolute runtime address to read, as a hex string (e.g. '0x08804000'). Not used by the other actions. The schema default of '0x0' exists for legacy callers -- do NOT rely on it when the action is 'register'.	0x0
`samples`	No	Number of samples to take per probe for action='observe' (default 1). If >1, samples are taken with a short yield between reads; the final value is the last read (caller can inspect stability by comparing samples externally).
`session_id`	Yes	Active session ID.
`description`	No	Optional human-readable note for action='register'.

Output Schema

TableJSON Schema

Name	Required	Description
`data`	Yes	Raw PPSSPP echo (reserved)
`count`	Yes	Probe count (register/list/clear) or observation count (observe)
`action`	Yes	Observer action executed
`probes`	Yes	All probes (action=list only)
`registered`	Yes	Probe added (action=register only)
`observations`	Yes	Per-probe readings (action=observe only)
`failure_count`	Yes	Failed observations (action=observe only)
`success_count`	Yes	Successful observations (action=observe only)

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.1.7Oct 7, 2026

changedInput schema / properties / address / description

Previous value: -"Absolute runtime address to read, as a hex string (e.g. '0x08804000'). Required for action='register'; ignored for all other actions."New value: +"Required for action='register'. Absolute runtime address to read, as a hex string (e.g. '0x08804000'). Not used by the other actions. The schema default of '0x0' exists for legacy callers -- do NOT rely on it when the action is 'register'."

addedOutput schema / $defs / ProbeObservationView / properties / note

Added value: +{
+  "default": "",
+  "description": "Empty unless value_status is suspicious",
+  "title": "Note",
+  "type": "string"
+}

addedOutput schema / $defs / ProbeObservationView / properties / value_status

Added value: +{
+  "default": "ok",
+  "description": "'ok' or 'stale_address_suspected'. The latter means this address has read zero on several consecutive readings, so the probe address may have drifted -- a suspicion, not a verdict",
+  "title": "Value Status",
+  "type": "string"
+}

First observedv0.1.0Sep 16, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the annotations, the description discloses that register/clear mutate state, the registry is PER-SESSION keyed by session_id, it is seeded from addresses.yaml, and clear removes only user-registered probes so the configured baseline survives. It even contrasts delete semantics with ppsspp_breakpoint mem_remove. The one nuance is that the description calls clear idempotent while idempotentHint=false applies to the whole multi-action tool — a refinement rather than a hard contradiction, since register is not idempotent.

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

Conciseness4/5

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

Labeled sections (PURPOSE/USAGE/ROUTING/BEHAVIOR/RETURNS) make it front-loaded and scannable, and every section carries non-redundant information. It is somewhat long for a single tool, and the RETURNS line partly duplicates the existing output schema, keeping it just below a 5.

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 high-complexity tool (8 params, 4 actions) the description covers the action model, per-session registry lifetime, mutation semantics, idempotent delete behavior, and the return shape — with an output schema and annotations also present. Nothing an agent needs to invoke it correctly is missing.

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 schema already documents name, size, names, samples, address and the action enum in detail. The description restates the action/parameter pairing ('register needs name + address (+size 1/2/4, description); observe takes comma-separated names') but adds no syntax or format meaning beyond what the schema provides. Baseline 3 is correct.

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 verb+resource pairing — 'Named memory-probe registry plus running-state observation' — and immediately distinguishes the two modes (register once, sample cheaply). The ROUTING section names the exact siblings it is not (ppsspp_frame_snapshot, ppsspp_breakpoint trace), so an agent can separate this from adjacent memory tools without opening a schema.

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?

ROUTING gives explicit when-to-use-this-vs-alternatives: recurring sampled probes across loops go here, one-shot paused snapshots go to ppsspp_frame_snapshot, single-address access watches go to ppsspp_breakpoint(action='trace'). The USAGE line also spells out which parameters each action requires.

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