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.

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.

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	Absolute runtime address to read, as a hex string (e.g. '0x08804000'). Required for action='register'; ignored for all other actions.	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.

First observedv0.1.0Sep 16, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Without relying on annotations, the description discloses side effects (register/clear mutate registry), process-wide sharing, seeding from addresses.yaml, and non-reseeding after clear. It also details idempotent clear semantics and contrasts with ppsspp_breakpoint mem_remove, going far beyond the sparse annotations.

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 selection and invocation information. Each sentence earns its place with minimal 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?

The description captures the registry lifecycle, cross-session scope, idempotency exception, and return envelope shape; combined with the output schema this gives an agent everything needed to call the tool safely. The only minor gap is a lack of explicit sibling-selection guidance, but that does not undermine completeness for correct invocation.

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 coverage is 100%, so the baseline is 3; the description adds only a condensed action-parameter summary and does not introduce semantics absent from the schema. The samples behavior and per-action parameter roles are already fully described in the input schema.

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?

Opens with a PURPOSE line that names a specific mechanism (named memory-probe registry) and a distinct use case (register once, sample cheaply every loop). This differentiates it from sibling memory tools like ppsspp_read_memory and ppsspp_breakpoint.

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 gives action-parameter mappings (register needs name+address, observe takes names+samples), which is clear operational context. It does not explicitly state when to prefer this tool over siblings or list exclusions, so it stops short of full differentiation.

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