ppsspp-dfx

Overview Schema Source Related Servers Discussions Admin

ppsspp_context

Read-onlyIdempotent

Triage a PPSSPP crash address with one call: get identity, region, disassembly window, and optional backtrace for debugging.

Instructions

PURPOSE: One-call crash-triage pack — identity + disassembly window + optional backtrace for an address.

USAGE: pass a crash PC or call target; identity resolves via addresses.yaml known_functions (IDA offset applied); disasm covers window instructions before/after; include_backtrace=true adds the call stack (pauses the CPU briefly).

BEHAVIOR: READ-ONLY. Unknown addresses return identity=null and the raw window instead of failing; backtrace is skipped (not an error) when the CPU is running — the note field says why. SCOPE: identity/region come from a TOPX-specific address knowledge base (addresses.yaml). For any other ISO they come back empty and note says so explicitly -- an empty identity means 'not in the tables', NOT 'bad address'.

ROUTING: persistent breakpoints around this address -> ppsspp_breakpoint; one armed hit-capture -> ppsspp_breakpoint(action="trace"); recurring sampling -> ppsspp_state_observer.

RETURNS: {address, identity: {name, start, offset} | null, region, disasm: [{address, text}], backtrace: [...], backtrace_note}.

Input Schema

TableJSON Schema

Name	Required	Description
`window`	No	Disassembly instructions BEFORE the address (same count after, so 2*window+1 total; default 8, cap 32).
`address`	Yes	Address to triage, hex ('0x088EF0F4') or decimal — typically a crash PC or a call target.
`session_id`	No	Active session ID; auto-resolved when exactly one session is active.
`include_backtrace`	No	Include the call stack (default false). Requires a paused CPU — the tool pauses/resumes around it; concurrent readers block briefly.

Output Schema

TableJSON Schema

Name	Required	Description
`disasm`	Yes	Instructions around the address (window before / at / after).
`region`	Yes	Memory-map region containing the address (e.g. 'user'), '' when unmapped.
`address`	Yes	Queried address (hex).
`identity`	Yes	Nearest known function at/below the address; None when unknown.
`backtrace`	Yes	Call stack (paused CPU only; empty when skipped).
`backtrace_note`	Yes	Why the backtrace is empty (e.g. 'CPU running — pause first').

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.1.6Oct 4, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond the read-only/idempotent annotations: unknown addresses return identity=null rather than failing, backtrace is silently skipped (not an error) when the CPU is running with the reason in `note`, the CPU is briefly paused for backtrace and concurrent readers block, and identity comes from a TOPX-specific KB where an empty result means 'not in tables' not 'bad address'.

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?

Header-labeled sections (PURPOSE/USAGE/BEHAVIOR/SCOPE/ROUTING/RETURNS) make it front-loaded and scannable, and each sentence carries signal. The RETURNS block is somewhat redundant given an output schema exists, costing a point.

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?

An output schema exists so return values needn't be spelled out, yet the description still covers the non-obvious cases (null identity, skipped backtrace, ISO-specific empty results, brief CPU pause) that an agent must know to interpret responses correctly.

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 description reinforces that address is a crash PC/call target and that window covers instructions before/after, but the schema already documents the window count, cap, and the backtrace pause/concurrency behavior, so little is added beyond structured fields.

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+resource pack ('one-call crash-triage pack — identity + disassembly window + optional backtrace for an address') and explicitly names sibling tools in the ROUTING section, so an agent can distinguish it from ppsspp_breakpoint and ppsspp_disassemble without opening schemas.

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?

Provides explicit when-to-use ('pass a crash PC or call target') and explicit alternatives with their selecting conditions: persistent breakpoints -> ppsspp_breakpoint, one armed hit-capture -> ppsspp_breakpoint(action="trace"), recurring sampling -> ppsspp_state_observer.

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