This server provides a Model Context Protocol (MCP) interface to control the mGBA Game Boy Advance emulator programmatically, enabling AI clients to inspect, manipulate, and automate running games.
Connectivity & Info
mgba_ping — Verify the bridge connection is alive
mgba_get_info — Retrieve ROM title, game code, platform, frame count, and a capability map of supported mGBA features
Memory Reading
mgba_read8 / mgba_read16 / mgba_read32 — Read 8-, 16-, or 32-bit values from any mapped memory address
mgba_read_range — Read up to 4096 bytes at once as a hex dump
Memory Writing
mgba_write8 / mgba_write16 / mgba_write32 — Write 8-, 16-, or 32-bit values directly to memory (bypasses cartridge bus/MBC mapper)
mgba_write_range — Write up to 4096 bytes in a single call
Input Control
mgba_press_buttons — Queue button presses (A, B, Start, Select, Up, Down, Left, Right, L, R) with configurable hold and release durations; uses a FIFO queue so consecutive presses register as distinct events
Emulation Control
mgba_pause / mgba_unpause — Freeze and resume real-time emulation
mgba_advance_frames — Step emulation by exactly N frames synchronously
mgba_reset — Hard-reset the loaded ROM back to boot state
Screenshots
mgba_screenshot — Capture the current display as a PNG file
Save States
mgba_save_state — Save full emulator state (RAM, registers, timing) to a numbered slot (0–9) or an arbitrary file path
mgba_load_state — Restore emulator state from a slot or file path, enabling snapshot/experiment/restore workflows
An MCP server that exposes the mGBA Game Boy Advance emulator to any MCP-compatible client (Claude Desktop, Claude Code, etc.).
Lets your model read and write GBA memory, inject button presses, take screenshots, and step the emulator — all through a clean tool interface.
Claude driving an in-development homebrew side-scroller through mgba_press_buttons — Start to begin, A to confirm New Game, then Right to walk and A to jump. Each frame is captured via mgba_screenshot.
+------------------+ stdio +------------------+ TCP :8765 +------------------+
| MCP client | JSON-RPC | mcp-mgba | newline JSON | mGBA emulator |
| (Claude / etc.) | ===========> | (Node.js) | ============> | bridge.lua |
+------------------+ +------------------+ +------------------+Two pieces:
lua/bridge.lua — runs inside mGBA's scripting engine, opens a loopback TCP server on port 8765
dist/index.js — Node.js MCP server, talks to the Lua bridge over TCP, exposes tools over stdio
Related MCP server: PokeMCP
mGBA 0.10 or newer (with Lua scripting)
Node.js 22+ (for the MCP server)
npm install -g mcp-mgbaPuts mcp-mgba on your PATH. Verify with mcp-mgba --help (it'll print a startup line and wait for stdio — Ctrl+C to exit).
npx (no install)npx -y mcp-mgbaRun on demand. Good for trying it out without committing to a global install.
git clone https://github.com/dmang-dev/mcp-mgba
cd mcp-mgba
npm install # also runs the build via the `prepare` hookThen reference the absolute path to dist/index.js when registering, or npm install -g . to symlink the bin globally.
Launch mGBA and load any GBA ROM.
Open Tools > Scripting…
Click File > Load script and select lua/bridge.lua from this repo.
You should see in the scripting console:
[mcp-mgba] bridge listening on 127.0.0.1:8765
[mcp-mgba] frame callback registered — bridge is activeIf you see a bind failed error, the previous instance's socket is still held — quit and relaunch mGBA.
claude mcp add mgba --scope user mcp-mgba(if you used Option B without global install, replace mcp-mgba with node /absolute/path/to/dist/index.js)
Verify:
claude mcp list
# mgba: mcp-mgba - ✓ ConnectedEdit claude_desktop_config.json:
Platform | Path |
macOS |
|
Windows |
|
Linux |
|
Add (assuming Option A — globally installed):
{
"mcpServers": {
"mgba": {
"command": "mcp-mgba"
}
}
}Or with explicit Node + path (Option B):
{
"mcpServers": {
"mgba": {
"command": "node",
"args": ["/absolute/path/to/mcp-mgba/dist/index.js"]
}
}
}Restart Claude Desktop after editing.
The server speaks standard MCP over stdio. Run mcp-mgba (or node dist/index.js) and connect any MCP client to its stdio.
Env var | Default | Purpose |
|
| Bridge host to dial |
|
| Bridge port to dial |
Tool | Description |
| Verify bridge connectivity (returns |
| Game title, code, frame count |
| Read memory at an address |
| Write to RAM |
| Read up to 4096 bytes as a byte array |
| Write up to 4096 bytes from a byte array |
| Queue a button press (FIFO; consecutive calls produce distinct events) |
| Step the emulator N frames |
| Pause / resume emulation |
| Reset the loaded ROM |
| Save a PNG of the current display |
| Save/load emulator state to a slot or path |
See docs/RECIPES.md for end-to-end examples (RAM hunting, snapshot-experiment-restore, side-scroller automation, etc.).
A, B, Select, Start, Right, Left, Up, Down, R, L
Range | Region |
| EWRAM (256 KiB, general) |
| IWRAM (32 KiB, fast) |
| I/O registers |
| Palette RAM |
| VRAM |
| OAM |
| ROM (read-only) |
Symptom | Cause / Fix |
| mGBA isn't running, or |
| A previous mGBA instance still holds the socket; quit and relaunch mGBA |
Tool calls hang | The bridge script may have errored out silently after a hot-reload — check the mGBA scripting console |
Tools missing in Claude after install | Restart your MCP client; Claude only enumerates servers on startup |
Tool calls return data shaped like an old version after editing | mGBA doesn't fully tear down a previous script when you reload. The new script's |
| mGBA's |
| This particular build of mGBA doesn't expose that method. The bridge feature-detects on the first frame; check |
| Known mGBA Lua quirk — the typed read methods are flaky via pcall from the frame callback. The bridge already routes |
Multiple | Older |
npm install
npm run dev # tsc --watch — autobuilds on src/ changesThe Lua side (lua/bridge.lua and lua/json.lua) needs no build step. Edit and reload via mGBA's File > Load script.
Browse and call this server's tools interactively with the MCP Inspector:
npm run inspectorBuild first if you've edited src/ since your last npm install (npm run build, or keep npm run dev running). Override the bridge address with MGBA_HOST / MGBA_PORT (default 127.0.0.1:8765). tools/list works even without mGBA connected; calling a tool needs mGBA open with lua/bridge.lua loaded.
PURPOSE: Step emulation by exactly N frames synchronously and return the new frame count. USAGE: Use for frame-precise input automation (combine with mgba_press_buttons to time inputs against in-game animation), letting the system initialize after a hard reset (RAM is mostly zero in the first ~30 frames after mgba_reset), or settling state between memory reads. For long jumps (thousands of frames) prefer mgba_save_state / mgba_load_state of a pre-prepared state — advance_frames scales linearly. To resume real-time playback indefinitely instead of stepping, use mgba_unpause. Works whether emulation is currently paused or running and does NOT change the pause state. BEHAVIOR: Advances mGBA's frame clock by N frames inside the bridge's frame callback. Each step costs roughly one real frame (~16ms at 60Hz GBA / ~16.7ms at 60Hz GB) plus one bridge round-trip — so advancing 600 frames takes ~10 seconds wall-clock. This method is build-dependent on mGBA; check capabilities.frameAdvance in mgba_get_info first. Returns an error if the capability is missing on this build. RETURNS: Single line 'Advanced N frame(s). Current frame: NEW_COUNT'.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Number of frames to advance (≥1, default 1). Latency scales linearly: ~16ms per frame at 60Hz. New frame count = previous frame count + count. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it advances the frame clock, does not change pause state, costs ~16ms per frame wall-clock, is build-dependent, and returns an error if capability missing. No annotations provided, so description carries full burden and meets it thoroughly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear PURPOSE, USAGE, BEHAVIOR, and RETURNS sections. Every sentence provides essential information; no redundancy or unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully explains the return format. For a single-parameter tool with moderate complexity, all aspects (input, behavior, edge cases) are covered completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds value: default value of 1, latency scaling (~16ms per frame), and explicit formula for new frame count. Surpasses baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Step emulation by exactly N frames synchronously and return the new frame count.' It distinguishes from sibling tools like mgba_save_state/load_state for long jumps and mgba_unpause for real-time playback.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use (frame-precise automation, after reset, settling state) and when not to use (long jumps, real-time playback), with named alternatives (mgba_save_state/load_state, mgba_unpause).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Get the loaded ROM's title, internal game code (e.g. 'AGBE' for GBA Pokemon Emerald US, 'BPRE' for FireRed), platform identifier (GBA vs GB/GBC), current frame count, and a capabilities map listing which optional emu methods this mGBA build exposes (pause, unpause, frameAdvance, saveStateSlot, saveStateFile, screenshot, etc.). USAGE: Call after mgba_ping at the start of a session to identify the loaded ROM and feature-detect optional capabilities BEFORE invoking tools that depend on them — pause/unpause/reset/save_state/load_state/advance_frames are all build-dependent on mGBA. The platform field tells you whether to address memory using the GBA layout (32-bit, EWRAM 0x02000000) or the GB/GBC layout (16-bit, WRAM 0xC000). BEHAVIOR: No side effects — pure read of emulator metadata. Returns '(unavailable)' for fields the loaded core can't expose (title when no ROM is loaded, code on systems without a header, etc.). Never throws on a partial read. RETURNS: Multi-line text with Title, Code, Platform, Frame, then the lists of present and missing capabilities for this build.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It clearly states: 'No side effects — pure read of emulator metadata. Returns '(unavailable)' for fields the loaded core can't expose... Never throws on a partial read.' Covers safety, error behavior, and partial data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with PURPOSE, USAGE, BEHAVIOR, RETURNS headings. Front-loaded purpose. Slightly verbose but every sentence adds value. Could tighten phrasing slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description thoroughly explains return format: multi-line text with Title, Code, Platform, Frame, and capabilities lists. Covers edge cases (unavailable fields, partial reads). Complete for a metadata read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0 parameters. Rubric gives baseline 4 for 0-param tools. Description adds no param info (none needed).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states specific verb+resource: 'Get the loaded ROM's title, internal game code, platform identifier, current frame count, and a capabilities map.' It clearly distinguishes from sibling tools that perform actions like advancing frames or saving states.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: 'Call after mgba_ping at the start of a session to identify the loaded ROM and feature-detect optional capabilities BEFORE invoking tools that depend on them.' Also explains how platform field affects memory addressing, providing when-to-use and prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Restore the emulator from a previously saved slot or .ss state file. USAGE: Counterpart to mgba_save_state. Use to undo a sequence of writes/inputs (the snapshot/experiment/restore workflow), to jump to a bookmarked game state, or to start each tool-call sequence from a known baseline. EXACTLY ONE of slot or path must be supplied (passing both, or neither, returns an error). To start fresh from console boot instead of a snapshot, use mgba_reset. BEHAVIOR: DESTRUCTIVE TO LIVE STATE: replaces ALL current emulator state (RAM, registers, mapper, audio, frame count, in-flight DMA) with the snapshot's contents. Anything not previously snapshotted is lost (unsaved in-game progress, queued button presses, paused state). The state file/slot MUST come from the same ROM and a compatible mGBA version that produced it — loading mismatched data typically produces a corrupt run or a hard error. Returns an error if neither slot nor path is supplied, the file doesn't exist or isn't a valid mGBA state, the slot is empty or out of range, or the relevant bridge load-state method (loadStateSlot vs loadStateFile) is missing on this build (check capabilities in mgba_get_info). RETURNS: Single line 'Loaded state from PATH' or 'Loaded state from slot N' depending on which form you used.
| Name | Required | Description | Default |
|---|---|---|---|
| slot | No | Save state slot number (0-9) to load. Mutually exclusive with `path` — supply exactly one. Loading an empty slot returns an error. Out-of-range slot numbers return an error. | |
| path | No | Absolute filesystem path to an existing .ss state file produced by mgba_save_state (or mGBA's UI) on this same ROM and a compatible mGBA version. Mutually exclusive with `slot` — supply exactly one. Loading mismatched files typically produces a corrupt run or a hard error. Only works on mGBA builds that expose the loadStateFile capability. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. Discloses destructive nature ('replaces ALL current emulator state'), lists what is lost (RAM, registers, etc.), and warns about compatibility issues with mismatched ROM/version. Covers error conditions and return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with labeled sections (PURPOSE, USAGE, BEHAVIOR, RETURNS). Every sentence adds value, though slightly lengthy due to comprehensive detail. Nearly optimal for the information density required.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 params, no output schema, and no annotations, the description covers all necessary aspects: purpose, usage context, behavioral side effects, parameter constraints, error handling, and return values. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage, so baseline is 3. Description adds significant value: clarifies mutual exclusivity, error cases for empty slot/out-of-range, and compatibility details for path. This goes well beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Restore the emulator from a previously saved slot or .ss state file.' Distinguishes from sibling mgba_reset (start fresh) and identifies as counterpart to mgba_save_state. Verb+resource+scope is specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists use cases (undo writes, jump to bookmark, start from baseline) and alternative mgba_reset for fresh start. Also specifies that exactly one of slot/path must be supplied, providing clear when-to and when-not-to guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Pause emulation — freeze the game-logic clock and hold the current frame on screen. USAGE: Use before a sequence of memory-inspect / write / screenshot calls when you need a stable game state across calls (so the game doesn't advance between your reads). Use mgba_unpause to resume; use mgba_advance_frames to step single frames without leaving pause. Memory reads and writes work the same way whether paused or not, so pause is only required when you specifically need a coherent snapshot — for one-shot reads it's optional. BEHAVIOR: Modifies emulator run state. The Lua bridge keeps polling the socket while paused, so all other tool calls (memory r/w, screenshot, save_state, etc.) still work. This method is build-dependent on mGBA; check capabilities.pause in mgba_get_info first to handle missing capability gracefully. Returns an error if the capability is missing on this build. Calling pause when already paused is a no-op. RETURNS: Single line 'Emulation paused'.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully discloses behavioral traits: it modifies run state, confirms all other tool calls still work, notes build-dependency with a capability check, and clarifies that calling pause when already paused is a no-op. This exceeds what annotations would typically provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (PURPOSE, USAGE, BEHAVIOR, RETURNS), making it easy to scan. While every sentence adds value, there is a slight redundancy in explaining that memory reads/writes work regardless of pause state, which could be more concise. Still, it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description covers all necessary context: purpose, usage boundaries, behavioral implications, dependencies, error handling, and return value. The RETURNS line explicitly states the output format. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the description does not need to elaborate on parameter semantics. The baseline for zero parameters is 4, and the description appropriately avoids adding unnecessary detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'PURPOSE: Pause emulation — freeze the game-logic clock and hold the current frame on screen.' The verb 'Pause' and resource 'emulation' are clear, and it distinguishes itself from siblings like mgba_unpause and mgba_advance_frames by explaining their differences.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The USAGE section provides explicit when-to-use ('before a sequence of memory-inspect / write / screenshot calls') and when-not-to-use ('for one-shot reads it's optional') guidance. It also names alternatives: mgba_unpause for resuming and mgba_advance_frames for stepping frames without leaving pause.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Verify that the mGBA Lua bridge is connected and responding to RPC over the TCP socket. USAGE: Call this once at start-of-session before issuing other tool calls; if it succeeds, every other tool will at least be reachable (individual tools may still fail if the loaded mGBA build doesn't expose a particular emu method — see mgba_get_info → capabilities for that). BEHAVIOR: No side effects — pure liveness probe. Times out after a few seconds with a clear error if mGBA isn't running, isn't pointed at the right host:port, or hasn't loaded the bridge Lua script (Tools → Scripting in mGBA). RETURNS: The literal string 'pong' on success.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. States 'No side effects — pure liveness probe', mentions timeout behavior, and error conditions. Fully discloses behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Structured with clear sections (PURPOSE, USAGE, BEHAVIOR, RETURNS). Concise without redundancy; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, no output schema, and no annotations, the description fully covers all necessary information: purpose, usage, behavior, error conditions, and return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters with 100% coverage. Description implicitly confirms no parameters needed and adds meaning by explaining the toll's purpose and return value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses 'liveness probe' and 'verify connection' with the specific verb 'Verify' and resource 'mGBA Lua bridge'. It clearly distinguishes from sibling tools by being a pure probe without side effects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Call this once at start-of-session before issuing other tool calls' and explains that success guarantees reachability but individual tools may fail based on capabilities. Provides clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Append a button-press to mGBA's input FIFO — hold the given buttons for frames frames, then release for release_frames frames before the next queued press starts. USAGE: Use to drive games with input. Each call APPENDS to the queue rather than overwriting, so consecutive calls produce distinct edge events that ROMs see as separate presses (rather than one continuous hold). To press the same button twice in a row reliably, send two presses — release_frames between them gives the ROM time to detect a key-up, which most input handlers require to register the second press. To advance emulation manually (without queueing inputs), use mgba_advance_frames. To inspect input-state side effects, pause first with mgba_pause and read RAM between presses. BEHAVIOR: Modifies the bridge's input queue; the press fires asynchronously on mGBA's frame callback. The call returns immediately with the new queue size — it does NOT block until the press completes. Returns an error if buttons contains a name not in the valid-key set, or if the bridge's input handling isn't installed on this build. RETURNS: Single line 'Queued press: KEYS (hold Nf, release Mf). Queue size: K'.
Valid button names: A, B, Select, Start, Right, Left, Up, Down, R, L.
| Name | Required | Description | Default |
|---|---|---|---|
| buttons | Yes | List of button names to hold simultaneously for this press (e.g. ["A"], ["Down", "B"] for a Konami-code-style combo). Names are case-sensitive. An unknown name returns an error rather than being silently ignored. | |
| frames | No | Number of frames to hold the buttons down (at 60 fps; default 1). For a normal menu-confirm tap, 2-4 is usually plenty; for held-direction movement on slower games, increase as needed. | |
| release_frames | No | Number of frames to release ALL keys after the hold, before the next queued press fires (default 1). Increase to 2-4 if a ROM debounces input and misses back-to-back presses; this gap is what lets the ROM see two distinct edge events instead of one long hold. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits: queue is appended (not overwritten), press fires asynchronously, returns immediately with queue size, and errors on invalid buttons or missing bridge support. This covers all important side effects and async behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (PURPOSE, USAGE, BEHAVIOR, RETURNS) and provides comprehensive information. While slightly verbose, every sentence adds value. It could be trimmed slightly without losing clarity, but overall it's efficient for its depth.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers all necessary context: return format, error conditions, async behavior, and usage scenarios. It is complete for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema already includes descriptions for all three parameters (100% coverage), the description adds meaningful context: typical frames values (2-4 for tap, higher for held movement), release_frames purpose (avoid debounce), and case sensitivity for button names. This enriches understanding beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool appends a button-press to the input FIFO, specifying hold and release frames. It distinguishes itself from mgba_advance_frames by noting the latter advances emulation without queueing inputs. The purpose is precise and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: use to drive games with input, explains that consecutive calls produce distinct edge events, and advises on sending two presses for reliable double-tap. It also tells when to use alternatives: mgba_advance_frames for manual advance, and mgba_pause for inspecting side effects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Read an unsigned 16-bit little-endian value from emulated memory at the given system bus address. USAGE: Use for 16-bit fields (most game-state values: HP, score, coordinates on 16-bit-flavoured layouts). For single bytes use mgba_read8; for 32-bit values use mgba_read32; for non-aligned spans, big-endian fields, or arbitrary structures use mgba_read_range and decode the bytes yourself (this tool always interprets bytes as little-endian, which matches both GBA and GB/GBC native endianness). BEHAVIOR: No side effects — pure read. Reads two consecutive bytes (low byte at address, high byte at address+1) and combines them as little-endian. Returns an error if the address is unmapped, the read straddles a region boundary, or the bridge method is missing on this build. RETURNS: Single line 'ADDR_HEX: VAL_DEC (0xVAL_HEX)'.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | System bus address. On GBA pass full 32-bit addresses (e.g. 0x02000000 for EWRAM start, 0x03000000 for IWRAM, 0x08000000 for ROM); on GB/GBC pass 16-bit addresses (e.g. 0xC000 for WRAM, 0xA000 for cartridge SRAM). Reads 2 consecutive bytes starting here. Should be 2-byte aligned (multiple of 2); misaligned reads on ARM-class regions can return zero or stale bus values without raising an error. Returns an error if the address is outside the platform's mapped regions or if the named bridge method is missing on this mGBA build (check mgba_get_info → capabilities). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses behavior: pure read with no side effects, memory access details (two bytes, little-endian), and error conditions for unmapped addresses or region boundaries.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into clear sections (PURPOSE, USAGE, BEHAVIOR, RETURNS) and is concise with no extraneous information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool with one parameter and no output schema, the description is complete: covers purpose, usage, behavior, return format, and error conditions. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the single parameter well (100% coverage), but the description adds valuable context about alignment, region-specific address hints, and error scenarios, going beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool reads an unsigned 16-bit little-endian value from emulated memory, with a specific verb and resource. It distinguishes itself from siblings by naming alternative tools (mgba_read8, mgba_read32, mgba_read_range) uses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear when-to-use guidance: for 16-bit fields, and explicitly states when to use alternatives for different data sizes or endianness. It also mentions alignment considerations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Read an unsigned 32-bit little-endian value from emulated memory at the given system bus address. USAGE: Use for 32-bit fields (timestamps, large counters, pointers on GBA, RGBA colours). For 8/16-bit reads use mgba_read8/read16; for big-endian or unaligned multi-word reads use mgba_read_range and decode yourself. BEHAVIOR: No side effects — pure read. mGBA's native emu.read32 is intermittently flaky when called via pcall on certain builds, so the bridge transparently routes 32-bit reads through readRange(addr, 4) and reassembles them little-endian — you get a stable answer either way. Returns an error only if the address is unmapped or the underlying readRange itself fails. RETURNS: Single line 'ADDR_HEX: VAL_DEC (0xVAL_HEX)'.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | System bus address. On GBA pass full 32-bit addresses (e.g. 0x02000000 for EWRAM start, 0x03000000 for IWRAM, 0x08000000 for ROM); on GB/GBC pass 16-bit addresses (e.g. 0xC000 for WRAM, 0xA000 for cartridge SRAM). Reads 4 consecutive bytes starting here. Should be 4-byte aligned (multiple of 4); misaligned reads on ARM-class regions can return zero or stale bus values without raising an error. Returns an error if the address is outside the platform's mapped regions or if the named bridge method is missing on this mGBA build (check mgba_get_info → capabilities). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description fully carries the burden. Discloses no side effects, addresses flaky native read32 and transparent routing, error conditions (unmapped address, readRange failure), and return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Structured with clear headings (PURPOSE, USAGE, BEHAVIOR, RETURNS). Each sentence adds value; no fluff. Front-loads the essential purpose and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with no output schema, description is fully complete: covers purpose, usage, behavioral details (flakiness, routing), error conditions, and return format. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers address parameter fully, but description adds valuable extra context: alignment warnings, platform-specific address examples (GBA vs GB/GBC), and error conditions. This goes beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb ('Read'), resource ('unsigned 32-bit little-endian value from emulated memory'), and format. Differentiates from siblings by explicitly naming alternatives for 8/16-bit reads and big-endian/unligned reads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (32-bit fields like timestamps, pointers, RGBA colours) and when not (use mgba_read8/read16 for smaller, mgba_read_range for complex). Also provides practical examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Read an unsigned 8-bit byte from emulated memory at the given system bus address. USAGE: Use for single-byte status flags, counters, and 8-bit fields. For 16- or 32-bit values use mgba_read16/read32 (one call instead of multi-byte assembly); for spans of more than ~4 bytes use mgba_read_range (one round-trip instead of N frame-latency hops). Reads work the same way whether emulation is paused or running, so pause is optional but recommended when you need a coherent snapshot across multiple reads. BEHAVIOR: No side effects — pure read. Returns an error if the address is outside the platform's mapped regions or the bridge method is missing on this mGBA build. RETURNS: Single line 'ADDR_HEX: VAL_DEC (0xVAL_HEX)', e.g. '0x2000000: 99 (0x63)'.
GBA address space: 0x02000000 EWRAM (256 KiB, general-purpose) 0x03000000 IWRAM (32 KiB, fast stack/variables) 0x04000000 IO registers 0x05000000 Palette RAM (1 KiB) 0x06000000 VRAM (96 KiB) 0x07000000 OAM (1 KiB) 0x08000000 ROM (up to 32 MiB, read-only)
Game Boy / GBC address space (when running a GB/GBC ROM): 0x0000 ROM bank 0 (16 KiB, read-only on bus; writes here trigger MBC commands but mgba_write* bypasses the bus) 0x4000 ROM banked (switchable) 0x8000 VRAM (8 KiB) 0xA000 Cartridge SRAM (8 KiB) — disabled by default on MBC1/3/5 carts 0xC000 WRAM (8 KiB; CGB has banked extension to 0xD000) 0xFE00 OAM (160 B) 0xFF00 I/O registers 0xFF80 HRAM (127 B)
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | System bus address. On GBA pass full 32-bit addresses (e.g. 0x02000000 for EWRAM start, 0x03000000 for IWRAM, 0x08000000 for ROM); on GB/GBC pass 16-bit addresses (e.g. 0xC000 for WRAM, 0xA000 for cartridge SRAM). Reads 1 consecutive byte starting here. Returns an error if the address is outside the platform's mapped regions or if the named bridge method is missing on this mGBA build (check mgba_get_info → capabilities). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses no side effects (pure read), error conditions (address out of range, missing bridge method), and includes full address space maps for both GBA and GB/GBC, compensating for absent annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with labeled sections (PURPOSE, USAGE, BEHAVIOR, RETURNS) and address maps, but slightly verbose for a simple read8. However, the comprehensiveness justifies the length given dual-platform support.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects: purpose, usage, behavior, return format, error conditions, and platform-specific address spaces. No gaps for agent invocation despite no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant value beyond the input schema by explaining address format differences between GBA (32-bit) and GB/GBC (16-bit) and listing valid address ranges from memory maps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Read an unsigned 8-bit byte from emulated memory' and distinguishes from siblings like mgba_read16, mgba_read32, and mgba_read_range by specifying use cases for different data sizes and spans.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear when-to-use guidance (single-byte flags, counters, 8-bit fields) and when-not-to-use (prefer read16/32 for larger values, read_range for spans >4 bytes). Also advises pausing for coherent multi-read snapshots.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Read a contiguous range of bytes from emulated memory and return them as a hex-formatted dump. USAGE: Use whenever you need more than ~4 bytes — one round-trip vs N frame-latency hops compared to looping mgba_read8. Maximum 4096 bytes per call (bridge serialization limit); for larger reads, batch in 4 KiB chunks. The classic two-snapshot RAM-hunt workflow uses this: snapshot before a known change, snapshot after, diff for matching deltas. Also useful for inspecting unknown structures and for 'capture, modify, restore' write_range workflows. This is the same primitive that mgba_read32 routes through internally. BEHAVIOR: No side effects — pure read. Reads length consecutive bytes starting at address. Returns an error if length > 4096, length < 1, the start address is unmapped, or the read crosses an unmapped region. RETURNS: Header line 'ADDR_HEX [N bytes]:' followed by space-separated 2-digit uppercase hex bytes.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | Starting system bus address. Same address-space conventions as the single-width read tools: full 32-bit for GBA (EWRAM 0x02000000, IWRAM 0x03000000, ROM 0x08000000), 16-bit for GB/GBC (WRAM 0xC000, SRAM 0xA000). The N bytes [address, address+length) are read. | |
| length | Yes | Number of consecutive bytes to read (1-4096). Hard cap is the bridge's per-call serialization limit; chunk larger reads yourself. A length that pushes the read across an unmapped region boundary will fail rather than silently zero-fill. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully covers behavior: no side effects, error conditions (length limits, unmapped memory), and return format. Thorough disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Structured with clear headers (PURPOSE, USAGE, BEHAVIOR, RETURNS), front-loaded, every sentence adds unique value. Perfect length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fully describes return format despite no output schema, provides bridge limitations and workflow examples. No gaps for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, yet description adds significant context: address conventions, chunking rationale, and error semantics for length and unmapped regions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a contiguous range of bytes and returns a hex dump. It distinguishes from sibling tools like mgba_read8 by emphasizing efficiency for large reads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use when needing more than ~4 bytes, mentions maximum 4096 bytes and chunking strategy, and provides workflow examples. No explicit when-not, but sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Reset the loaded ROM — equivalent to pressing the reset button on the GBA / Game Boy. USAGE: Use to start fresh from boot. To return to a specific known-good point instead of boot, use mgba_load_state with a previously saved slot or .ss0/.ss1/etc state file. BEHAVIOR: DESTRUCTIVE: RAM contents become indeterminate (typically the BIOS-zeroed state), CPU returns to the reset vector, frame count resets to 0, input queue clears, and any in-progress audio/video state is discarded. The loaded ROM stays loaded — only volatile state is cleared. UNSAVED IN-GAME PROGRESS IS LOST (anything not committed to cartridge SRAM via the game's save menu, and anything not snapshotted via mgba_save_state). This method is build-dependent on mGBA; check capabilities.reset in mgba_get_info first. Returns an error if the capability is missing on this build. RETURNS: Single line 'ROM reset'.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses destructive behavior: RAM indeterminate, CPU reset, frame count reset, input queue clear, audio/video discard, unsaved progress loss, build-dependency, and error handling. This exceeds the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled 'PURPOSE', 'USAGE', 'BEHAVIOR', 'RETURNS' sections, front-loads the purpose, and every sentence provides necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature and lack of annotations or output schema, the description covers all critical aspects: purpose, usage guidance, behavioral details, return value, error conditions, and prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters with 100% coverage, so baseline is 4. The description adds no parameter details but explains the operation's effects, which is valuable context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Reset the loaded ROM — equivalent to pressing the reset button on the GBA / Game Boy.', providing a specific verb and resource. It distinguishes from sibling mgba_load_state by contrasting with returning to a saved state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description directly advises when to use ('start fresh from boot') and when to use an alternative ('use mgba_load_state for a saved point'), naming the sibling tool explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Save the entire emulator state (RAM, CPU/PPU/APU registers, mapper state, sound chip state, timing, in-flight DMA) to either an mGBA-managed numbered slot OR an arbitrary file path. USAGE: Use as a rollback point before risky writes, to bookmark interesting game states, to share repro states, or — on Game Boy — to seed cartridge SRAM cleanly without fighting MBC bus semantics that mgba_write* would bypass. EXACTLY ONE of slot or path must be supplied (passing both, or neither, returns an error). Slots 0-9 are managed by mGBA in its data directory and are ideal for ad-hoc rollback during a session; explicit paths are better for long-term storage and sharing across sessions/machines. The companion mgba_load_state restores from either form. BEHAVIOR: When path is supplied, DESTRUCTIVE TO TARGET FILE: overwrites the file at path if it exists, with no prompt or backup. When slot is supplied, DESTRUCTIVE TO THE NAMED SLOT: overwrites whatever was previously stored in that slot. The state is bound to the EXACT ROM and a compatible mGBA version that produced it — loading it on a different ROM or an incompatible mGBA version typically produces a corrupt run or a hard error. Returns an error if neither slot nor path is supplied, the path's parent directory doesn't exist, the path isn't writable, the slot is out of range, or the relevant bridge save-state method (saveStateSlot vs saveStateFile) is missing on this build (check capabilities in mgba_get_info). RETURNS: Single line 'Saved state to PATH' or 'Saved state to slot N' depending on which form you used.
| Name | Required | Description | Default |
|---|---|---|---|
| slot | No | Save state slot number (0-9). Slot files are managed by mGBA in its data directory. Mutually exclusive with `path` — supply exactly one. Out-of-range slot numbers return an error. | |
| path | No | Absolute filesystem path to write the state to (e.g. C:/temp/checkpoint.ss0 on Windows, /tmp/checkpoint.ss0 on Linux/macOS). Mutually exclusive with `slot` — supply exactly one. Parent directory must exist; file is overwritten without prompt if present. Only works on mGBA builds that expose the saveStateFile capability. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses destructive behavior (overwrites without prompt), state version binding to ROM and mGBA version, and error conditions. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat lengthy but well-structured with clear labeled sections. Every sentence adds value, though minor trimming could improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains return values and all relevant error scenarios. It covers the tool's full context, including limitations and prerequisites, making it self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with descriptions for both parameters. The description adds meaningful context: slot management by mGBA, path requirements (absolute, parent directory must exist), and capability dependency.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Save the entire emulator state' and enumerates exactly what is saved (RAM, CPU/PPU/APU registers, etc.). It clearly distinguishes between the two invocation modes (slot vs path) and contrasts with sibling tools like mgba_load_state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage scenarios: rollback point, bookmarking, sharing, seeding SRAM. Clearly states the mutual exclusivity of arguments and advises when to use slots vs paths. References the companion tool mgba_load_state.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Save a PNG screenshot of the current emulator display to a file. USAGE: Use to capture visible game state for inspection, comparison across savestates, or sequence documentation. The image captures whatever the emulator is currently rendering — to capture a specific game state, pause / advance frames / load state first to get the frame you want, then call this. Path is optional; omit it to let mGBA write to its default screenshot directory and report back the chosen filename. BEHAVIOR: DESTRUCTIVE TO TARGET FILE if path is supplied: overwrites the file at path if it exists, with no prompt or backup. Returns an error if path is supplied but the parent directory doesn't exist or isn't writable, or if the bridge's screenshot method is missing on this build. RETURNS: Single line 'Screenshot saved: PATH', where PATH is the file actually written (the value you passed, or mGBA's default-directory file name if path was omitted).
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Optional absolute filesystem path to write the PNG to (e.g. C:/temp/snap.png on Windows, /tmp/snap.png on Linux/macOS). Parent directory must exist. File is overwritten without prompt if present. Omit to let mGBA pick a filename in its default screenshot directory and return that path. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits: 'DESTRUCTIVE TO TARGET FILE if `path` is supplied: overwrites the file at `path` if it exists, with no prompt or backup.' It also covers error conditions (missing parent directory, missing method), meeting the full burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (PURPOSE, USAGE, BEHAVIOR, RETURNS). Every sentence provides essential information without redundancy. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, the description covers all needed context: purpose, when to use, behavior including side effects, error conditions, and return format. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter. The description adds value by explaining the behavior when omitted ('omit to let mGBA pick a filename in its default screenshot directory and return that path'), which is not inferred from the schema alone. This goes beyond the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Save a PNG screenshot of the current emulator display to a file.' It clearly identifies the verb 'save' and resource 'screenshot', distinguishing it from sibling tools that perform other operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage section provides clear context: 'capture visible game state for inspection, comparison across savestates, or sequence documentation.' It also gives explicit prerequisite steps like 'pause / advance frames / load state first.' However, it does not explicitly state when not to use this tool or list alternative tools, missing a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Resume emulation after a pause, returning to normal real-time playback. USAGE: Counterpart to mgba_pause. Use after a paused inspection sequence is complete. To advance only a few frames without resuming full speed, use mgba_advance_frames instead. BEHAVIOR: Modifies emulator run state. This method is build-dependent on mGBA; check capabilities.unpause in mgba_get_info first. Returns an error if the capability is missing on this build. Calling unpause when not paused is a no-op. RETURNS: Single line 'Emulation resumed'.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses: modifies run state, build-dependency, need to check capabilities, error handling, and no-op behavior when not paused. No annotations present, so description fully covers behavioral aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Structured into clear sections (PURPOSE, USAGE, BEHAVIOR, RETURNS) with no redundant sentences. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, description covers all necessary context: behavior, usage constraints, return value, and sibling differentiation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters in input schema; description adds no param info as none exist. Rule sets baseline 4 for zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states 'Resume emulation after a pause', clearly identifying verb and resource. Distinguishes from counterparts mgba_pause and mgba_advance_frames.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when to use: 'after a paused inspection sequence is complete', and when not: 'To advance only a few frames...use mgba_advance_frames instead'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Write an unsigned 16-bit little-endian value to emulated memory at the given system bus address. USAGE: Use for 16-bit cheats and pokes (HP, score, coordinates). For single bytes use mgba_write8; for 32-bit use mgba_write32; for big-endian fields, byteswap and use mgba_write_range; for cart save RAM seeding with proper MBC semantics, use mgba_save_state / mgba_load_state. BEHAVIOR: DESTRUCTIVE: overwrites two bytes (low byte at address, high byte at address+1) with no undo. Debug-direct memory write — no MBC/mapper/DMA mediation, see mgba_write8 notes for the cartridge-bus bypass details. Returns an error if the address is unmapped, address+2 crosses an unmapped boundary, value < 0 or > 65535, or the bridge method is missing. RETURNS: Single line 'Wrote VAL_DEC (0xVAL_HEX) → ADDR_HEX'.
NOTE: writes use mGBA's debug-direct memory access, which bypasses the cartridge bus model. On Game Boy with an MBC cartridge, this means writes to ROM region (0x0000-0x7FFF) won't trigger MBC bank-switch / RAM-enable commands, and writes to SRAM (0xA000-0xBFFF) hit the underlying buffer regardless of MBC enable state. To seed cartridge SRAM cleanly, use mgba_save_state / mgba_load_state with a pre-prepared state file.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | System bus address to overwrite. Same address-space conventions as the read tools — full 32-bit for GBA (EWRAM 0x02000000, IWRAM 0x03000000, ROM 0x08000000), 16-bit for GB/GBC (WRAM 0xC000, SRAM 0xA000). Should be 2-byte aligned (multiple of 2); misaligned writes on ARM-class regions may corrupt adjacent bytes or be silently dropped. Writes go through mGBA's debug-direct memory access, so they ignore MBC enable state and bus protections — to seed cartridge SRAM with proper hardware semantics, use mgba_save_state / mgba_load_state instead. | |
| value | Yes | 16-bit value to write. Must be 0-65535 (0x0000-0xFFFF). LSB is written to `address`, MSB to `address+1`. Values outside this range return an error before the write is attempted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses destructive behavior (overwrites two bytes, no undo), debug-direct memory access bypassing MBC, error conditions, and return format. No ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (PURPOSE, USAGE, BEHAVIOR, RETURNS, NOTE). Every sentence provides essential information; no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (alignment, endianness, MBC interactions, error cases) and lack of output schema, the description is remarkably complete, covering all critical aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds significant value: alignment requirement (2-byte aligned), endianness details (LSB/MSB), and MBC bypass implications for the address parameter. The value parameter's range is reinforced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool writes a 16-bit little-endian value to emulated memory, specifies the verb ('write') and resource ('emulated memory'), and differentiates from siblings by naming alternative tools for different sizes and endianness.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (for 16-bit cheats/pokes) and when not (use mgba_write8 for single bytes, mgba_write32 for 32-bit, mgba_write_range for big-endian, mgba_save_state/mgba_load_state for proper MBC semantics). Provides clear alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Write an unsigned 32-bit little-endian value to emulated memory at the given system bus address. USAGE: Use for 32-bit cheats and pokes (timestamps, large counters, pointers on GBA). For 8/16-bit values use mgba_write8/write16; for big-endian layouts byteswap and use mgba_write_range. BEHAVIOR: DESTRUCTIVE: overwrites four bytes starting at address with no undo (snapshot via mgba_save_state first if you need rollback). Debug-direct memory write — bypasses MBC/mapper/DMA, see mgba_write8 notes. Returns an error if the address is unmapped, address+4 crosses an unmapped boundary, value < 0, or the bridge method is missing. RETURNS: Single line 'Wrote VAL_DEC (0xVAL_HEX) → ADDR_HEX'.
NOTE: writes use mGBA's debug-direct memory access, which bypasses the cartridge bus model. On Game Boy with an MBC cartridge, this means writes to ROM region (0x0000-0x7FFF) won't trigger MBC bank-switch / RAM-enable commands, and writes to SRAM (0xA000-0xBFFF) hit the underlying buffer regardless of MBC enable state. To seed cartridge SRAM cleanly, use mgba_save_state / mgba_load_state with a pre-prepared state file.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | System bus address to overwrite. Same address-space conventions as the read tools — full 32-bit for GBA (EWRAM 0x02000000, IWRAM 0x03000000, ROM 0x08000000), 16-bit for GB/GBC (WRAM 0xC000, SRAM 0xA000). Should be 4-byte aligned (multiple of 4); misaligned writes on ARM-class regions may corrupt adjacent bytes or be silently dropped. Writes go through mGBA's debug-direct memory access, so they ignore MBC enable state and bus protections — to seed cartridge SRAM with proper hardware semantics, use mgba_save_state / mgba_load_state instead. | |
| value | Yes | 32-bit value to write. Must fit in unsigned 32 bits (0-4294967295, 0x00000000-0xFFFFFFFF). LSB lands at `address`, MSB at `address+3`. Negative values return an error. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses destructive behavior ('overwrites four bytes with no undo'), bypassing MBC/mapper/DMA, and error conditions (unmapped address, boundary crossing, negative value, missing bridge method). The NOTE adds context about debug-direct access and hardware semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with clear labeled sections (PURPOSE, USAGE, BEHAVIOR, RETURNS, NOTE). Every sentence is informative with no redundancy. Length is appropriate for the complexity of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description documents the return format and error conditions. It covers edge cases (alignment, MBC bypass, boundary crossing). The NOTE provides important hardware context. All critical behavioral aspects are addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds significant value beyond the schema: address alignment instructions, endianness mapping, and specific error cases for negative values. It also clarifies the note about SRAM seeding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines the action ('write 32-bit little-endian value') and the target resource ('emulated memory at given system bus address'). It explicitly distinguishes from siblings (mgba_write8, mgba_write16, mgba_write_range) by specifying bit-width and byte-order use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The USAGE section explicitly states when to use this tool (32-bit cheats, timestamps, counters, pointers) and provides alternatives ('for 8/16-bit use mgba_write8/write16', 'for big-endian byteswap and use mgba_write_range'). It also advises snapshotting before writes for rollback.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Write a single unsigned byte (0-255) to emulated memory at the given system bus address. USAGE: Use for single-byte cheats, debug pokes, and game-state mutations (give a player N lives, unlock a flag, set a counter). For 16/32-bit values prefer mgba_write16/write32 (single call instead of byte-at-a-time); for spans use mgba_write_range. To seed cart save RAM realistically (with proper MBC bank/enable behavior on Game Boy, or to install a known-good progression state on GBA), prefer mgba_save_state / mgba_load_state with a pre-prepared state file rather than poking SRAM bytes here. BEHAVIOR: DESTRUCTIVE: overwrites whatever was at address with no undo (snapshot via mgba_save_state first if you need rollback). The write is debug-direct memory access — bypasses MBC bank switches, cartridge mapper side-effects, RAM-enable gates, and bus protections — so it cannot be used to emulate cartridge hardware. Writes to ROM region addresses succeed at the memory level but produce no MBC effect on GB/GBC. Returns an error if the address is unmapped, value < 0 or > 255, or the bridge method is missing. Works whether emulation is paused or running. RETURNS: Single line 'Wrote VAL_DEC (0xVAL_HEX) → ADDR_HEX'.
NOTE: writes use mGBA's debug-direct memory access, which bypasses the cartridge bus model. On Game Boy with an MBC cartridge, this means writes to ROM region (0x0000-0x7FFF) won't trigger MBC bank-switch / RAM-enable commands, and writes to SRAM (0xA000-0xBFFF) hit the underlying buffer regardless of MBC enable state. To seed cartridge SRAM cleanly, use mgba_save_state / mgba_load_state with a pre-prepared state file.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | System bus address to overwrite. Same address-space conventions as the read tools — full 32-bit for GBA (EWRAM 0x02000000, IWRAM 0x03000000, ROM 0x08000000), 16-bit for GB/GBC (WRAM 0xC000, SRAM 0xA000). Writes go through mGBA's debug-direct memory access, so they ignore MBC enable state and bus protections — to seed cartridge SRAM with proper hardware semantics, use mgba_save_state / mgba_load_state instead. | |
| value | Yes | Byte value to write. Must be 0-255 (0x00-0xFF). Values outside this range return an error before the write is attempted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It discloses destructive nature (no undo), debug-direct memory access bypassing MBC and bus protections, behavior for writes to ROM/SRAM regions, and error conditions (unmapped address, out-of-range value). This provides comprehensive behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with clear sections (PURPOSE, USAGE, BEHAVIOR, RETURNS). While somewhat lengthy, every sentence provides necessary guidance. Minor redundancy with schema descriptions, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers return format and error conditions. It also notes the tool works even when emulation is paused. For a mutation tool with detailed side effects, the description is fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage, so baseline is 3. The description adds extra context beyond schema: address conventions for GBA/GB, MBC bypass implications, and that value errors return before write attempt. This enriches parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool writes a single unsigned byte to emulated memory, specifies value range and address domain. It distinguishes from sibling tools (mgba_write16, mgba_write32, mgba_write_range) by stating when to prefer them, and from save/load state for cartridge SRAM seeding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists appropriate uses (single-byte cheats, debug pokes, mutations) and explicitly says when not to use this tool (prefer write16/write32 for larger values, write_range for spans, save/load state for cartridge SRAM). Also suggests snapshotting via save_state as a precaution.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Write a contiguous byte sequence to emulated memory starting at the given system bus address. USAGE: Use whenever you're seeding more than ~4 bytes — one round-trip vs N frame-latency hops compared to looping mgba_write8. Maximum 4096 bytes per call (bridge serialization limit); for larger writes, batch in 4 KiB chunks. Useful for installing cheat tables, patching code blocks, restoring a captured byte window after experiments, and writing big-endian multi-byte values (byteswap them yourself first). For cart save RAM seeding with proper MBC semantics on Game Boy, use mgba_save_state / mgba_load_state instead — those go through the cartridge bus model. BEHAVIOR: DESTRUCTIVE: overwrites N bytes starting at address with no undo. Debug-direct memory write — bypasses MBC/mapper/DMA, see mgba_write8 notes for the cartridge-bus bypass details. Bytes are written sequentially address, address+1, ..., address+N-1. Returns an error if the address is unmapped, address+N crosses an unmapped boundary, the array contains a value outside 0-255, the array length is < 1 or > 4096, or the bridge method is missing. RETURNS: Single line 'Wrote N bytes → ADDR_HEX'.
NOTE: writes use mGBA's debug-direct memory access, which bypasses the cartridge bus model. On Game Boy with an MBC cartridge, this means writes to ROM region (0x0000-0x7FFF) won't trigger MBC bank-switch / RAM-enable commands, and writes to SRAM (0xA000-0xBFFF) hit the underlying buffer regardless of MBC enable state. To seed cartridge SRAM cleanly, use mgba_save_state / mgba_load_state with a pre-prepared state file.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | Starting system bus address. Same address-space conventions as the single-width write tools: full 32-bit for GBA (EWRAM 0x02000000, IWRAM 0x03000000), 16-bit for GB/GBC (WRAM 0xC000, SRAM 0xA000). The N bytes [address, address+len) are written. Writes use debug-direct memory access — bypasses MBC; for cart save RAM seeding use mgba_save_state / mgba_load_state instead. | |
| bytes | Yes | Byte values to write, one per element (each 0-255). Length 1-4096 (hard cap from the bridge's serialization limit). Written sequentially from `address` in declaration order. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Extremely detailed: describes destructive nature (overwrites with no undo), bypasses MBC/mapper/DMA, specifics on Game Boy MBC cartridge behavior (writes to ROM don't trigger bank-switch, SRAM writes hit buffer regardless of enable state). Lists all error conditions. Since no annotations provided, description fully carries the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with labeled sections (PURPOSE, USAGE, BEHAVIOR, RETURNS, NOTE). Every sentence adds value. Slightly verbose but still efficient given the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects: purpose, when to use, behavior, parameters, error handling, return value, and important behavioral notes (MBC bypass). No output schema, but description explains the return string format. Complete for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions. The tool description adds extra context (address conventions for GBA vs GB, debug-direct access, sequential writing, bytes 0-255). Adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states it writes a contiguous byte sequence to emulated memory. Distinguishes from sibling mgba_write8 by noting it's for seeding more than ~4 bytes to avoid multiple round-trips. Lists concrete use cases like installing cheat tables, patching code blocks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear guidance on when to use (seeding >4 bytes) and when not (for cart save RAM with MBC semantics, use mgba_save_state/mgba_load_state instead). Mentions batch size limitation (4096 bytes) and alternative approach for larger writes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.3.1mgba_advance_frames1 field changedInput schema / properties / count / descriptionPrevious value: -"Number of frames to advance (default 1)"New value: +"Number of frames to advance (≥1, default 1). Latency scales linearly: ~16ms per frame at 60Hz. New frame count = previous frame count + count."mgba_load_state2 fields changedInput schema / properties / path / descriptionPrevious value: -"Absolute file path (alternative to slot)"New value: +"Absolute filesystem path to an existing .ss state file produced by mgba_save_state (or mGBA's UI) on this same ROM and a compatible mGBA version. Mutually exclusive with `slot` — supply exactly one. Loading mismatched files typically produces a corrupt run or a hard error. Only works on mGBA builds that expose the loadStateFile capability."Input schema / properties / slot / descriptionPrevious value: -"Save state slot (0-9)"New value: +"Save state slot number (0-9) to load. Mutually exclusive with `path` — supply exactly one. Loading an empty slot returns an error. Out-of-range slot numbers return an error."mgba_press_buttons3 fields changedInput schema / properties / buttons / descriptionPrevious value: -"List of button names to hold simultaneously for this press"New value: +"List of button names to hold simultaneously for this press (e.g. [\"A\"], [\"Down\", \"B\"] for a Konami-code-style combo). Names are case-sensitive. An unknown name returns an error rather than being silently ignored."Input schema / properties / frames / descriptionPrevious value: -"Frames to hold the buttons (at 60 fps; default 1)"New value: +"Number of frames to hold the buttons down (at 60 fps; default 1). For a normal menu-confirm tap, 2-4 is usually plenty; for held-direction movement on slower games, increase as needed."Input schema / properties / release_frames / descriptionPrevious value: -"Frames to release keys after the hold, before the next queued press fires (default 1). Increase if a ROM debounces input."New value: +"Number of frames to release ALL keys after the hold, before the next queued press fires (default 1). Increase to 2-4 if a ROM debounces input and misses back-to-back presses; this gap is what lets the ROM see two distinct edge events instead of one long hold."mgba_read_range2 fields changedInput schema / properties / address / descriptionPrevious value: -"Start address"New value: +"Starting system bus address. Same address-space conventions as the single-width read tools: full 32-bit for GBA (EWRAM 0x02000000, IWRAM 0x03000000, ROM 0x08000000), 16-bit for GB/GBC (WRAM 0xC000, SRAM 0xA000). The N bytes [address, address+length) are read."Input schema / properties / length / descriptionPrevious value: -"Number of bytes to read"New value: +"Number of consecutive bytes to read (1-4096). Hard cap is the bridge's per-call serialization limit; chunk larger reads yourself. A length that pushes the read across an unmapped region boundary will fail rather than silently zero-fill."mgba_read161 field changedInput schema / properties / address / descriptionPrevious value: -"GBA memory address (must be 2-byte aligned)"New value: +"System bus address. On GBA pass full 32-bit addresses (e.g. 0x02000000 for EWRAM start, 0x03000000 for IWRAM, 0x08000000 for ROM); on GB/GBC pass 16-bit addresses (e.g. 0xC000 for WRAM, 0xA000 for cartridge SRAM). Reads 2 consecutive bytes starting here. Should be 2-byte aligned (multiple of 2); misaligned reads on ARM-class regions can return zero or stale bus values without raising an error. Returns an error if the address is outside the platform's mapped regions or if the named bridge method is missing on this mGBA build (check mgba_get_info → capabilities)."mgba_read321 field changedInput schema / properties / address / descriptionPrevious value: -"GBA memory address (must be 4-byte aligned)"New value: +"System bus address. On GBA pass full 32-bit addresses (e.g. 0x02000000 for EWRAM start, 0x03000000 for IWRAM, 0x08000000 for ROM); on GB/GBC pass 16-bit addresses (e.g. 0xC000 for WRAM, 0xA000 for cartridge SRAM). Reads 4 consecutive bytes starting here. Should be 4-byte aligned (multiple of 4); misaligned reads on ARM-class regions can return zero or stale bus values without raising an error. Returns an error if the address is outside the platform's mapped regions or if the named bridge method is missing on this mGBA build (check mgba_get_info → capabilities)."mgba_read81 field changedInput schema / properties / address / descriptionPrevious value: -"GBA memory address (decimal or hex — use 0x prefix in JSON strings, or pass as decimal integer)"New value: +"System bus address. On GBA pass full 32-bit addresses (e.g. 0x02000000 for EWRAM start, 0x03000000 for IWRAM, 0x08000000 for ROM); on GB/GBC pass 16-bit addresses (e.g. 0xC000 for WRAM, 0xA000 for cartridge SRAM). Reads 1 consecutive byte starting here. Returns an error if the address is outside the platform's mapped regions or if the named bridge method is missing on this mGBA build (check mgba_get_info → capabilities)."mgba_save_state2 fields changedInput schema / properties / path / descriptionPrevious value: -"Absolute file path (alternative to slot)"New value: +"Absolute filesystem path to write the state to (e.g. C:/temp/checkpoint.ss0 on Windows, /tmp/checkpoint.ss0 on Linux/macOS). Mutually exclusive with `slot` — supply exactly one. Parent directory must exist; file is overwritten without prompt if present. Only works on mGBA builds that expose the saveStateFile capability."Input schema / properties / slot / descriptionPrevious value: -"Save state slot (0-9)"New value: +"Save state slot number (0-9). Slot files are managed by mGBA in its data directory. Mutually exclusive with `path` — supply exactly one. Out-of-range slot numbers return an error."mgba_screenshot1 field changedInput schema / properties / path / descriptionPrevious value: -"Absolute file path to save the PNG (optional — defaults to a temp file)"New value: +"Optional absolute filesystem path to write the PNG to (e.g. C:/temp/snap.png on Windows, /tmp/snap.png on Linux/macOS). Parent directory must exist. File is overwritten without prompt if present. Omit to let mGBA pick a filename in its default screenshot directory and return that path."mgba_write_range2 fields changedInput schema / properties / address / descriptionPrevious value: -"Start address"New value: +"Starting system bus address. Same address-space conventions as the single-width write tools: full 32-bit for GBA (EWRAM 0x02000000, IWRAM 0x03000000), 16-bit for GB/GBC (WRAM 0xC000, SRAM 0xA000). The N bytes [address, address+len) are written. Writes use debug-direct memory access — bypasses MBC; for cart save RAM seeding use mgba_save_state / mgba_load_state instead."Input schema / properties / bytes / descriptionPrevious value: -"Array of byte values (0-255). Length cannot exceed 4096."New value: +"Byte values to write, one per element (each 0-255). Length 1-4096 (hard cap from the bridge's serialization limit). Written sequentially from `address` in declaration order."mgba_write162 fields changedInput schema / properties / address / descriptionPrevious value: -"RAM address (2-byte aligned)"New value: +"System bus address to overwrite. Same address-space conventions as the read tools — full 32-bit for GBA (EWRAM 0x02000000, IWRAM 0x03000000, ROM 0x08000000), 16-bit for GB/GBC (WRAM 0xC000, SRAM 0xA000). Should be 2-byte aligned (multiple of 2); misaligned writes on ARM-class regions may corrupt adjacent bytes or be silently dropped. Writes go through mGBA's debug-direct memory access, so they ignore MBC enable state and bus protections — to seed cartridge SRAM with proper hardware semantics, use mgba_save_state / mgba_load_state instead."Input schema / properties / value / descriptionPrevious value: -"16-bit value (0-65535)"New value: +"16-bit value to write. Must be 0-65535 (0x0000-0xFFFF). LSB is written to `address`, MSB to `address+1`. Values outside this range return an error before the write is attempted."mgba_write322 fields changedInput schema / properties / address / descriptionPrevious value: -"RAM address (4-byte aligned)"New value: +"System bus address to overwrite. Same address-space conventions as the read tools — full 32-bit for GBA (EWRAM 0x02000000, IWRAM 0x03000000, ROM 0x08000000), 16-bit for GB/GBC (WRAM 0xC000, SRAM 0xA000). Should be 4-byte aligned (multiple of 4); misaligned writes on ARM-class regions may corrupt adjacent bytes or be silently dropped. Writes go through mGBA's debug-direct memory access, so they ignore MBC enable state and bus protections — to seed cartridge SRAM with proper hardware semantics, use mgba_save_state / mgba_load_state instead."Input schema / properties / value / descriptionPrevious value: -"32-bit value"New value: +"32-bit value to write. Must fit in unsigned 32 bits (0-4294967295, 0x00000000-0xFFFFFFFF). LSB lands at `address`, MSB at `address+3`. Negative values return an error."mgba_write82 fields changedInput schema / properties / address / descriptionPrevious value: -"RAM address"New value: +"System bus address to overwrite. Same address-space conventions as the read tools — full 32-bit for GBA (EWRAM 0x02000000, IWRAM 0x03000000, ROM 0x08000000), 16-bit for GB/GBC (WRAM 0xC000, SRAM 0xA000). Writes go through mGBA's debug-direct memory access, so they ignore MBC enable state and bus protections — to seed cartridge SRAM with proper hardware semantics, use mgba_save_state / mgba_load_state instead."Input schema / properties / value / descriptionPrevious value: -"Byte value (0-255)"New value: +"Byte value to write. Must be 0-255 (0x00-0xFF). Values outside this range return an error before the write is attempted."v0.3.0mgba_advance_framesmgba_get_infomgba_load_statemgba_pausemgba_pingmgba_press_buttonsmgba_read_rangemgba_read16mgba_read32mgba_read8mgba_resetmgba_save_statemgba_screenshotmgba_unpausemgba_write_rangemgba_write16mgba_write32mgba_write8Every tool has a clearly distinct purpose: emulation control (pause/unpause/reset), stepping (advance_frames), memory access at different widths (read8/16/32/range and write counterparts), state management (save/load), input (press_buttons), info retrieval (get_info), and screenshot. There is no functional overlap.
All tools follow the pattern 'mgba_' followed by a descriptive verb or verb_noun in snake_case (e.g., advance_frames, read16, save_state). The naming is uniform and predictable, with clear size suffixes for read/write tools.
18 tools is a well-scoped count for an emulator control server. Each tool addresses a specific need without redundancy, covering emulation flow, memory manipulation, state persistence, input, and diagnostics.
The tool set provides full lifecycle coverage: start/reset, pause/resume, single-step, memory read/write at all common widths, state save/load (slot or file), screenshot, input queuing, and info. No obvious gaps exist for typical emulation debugging or automation tasks.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Official remote MCP server bridge for Muumuu Domain.
The official MCP Server for the Mux API
A simple MCP server built with FastMCP and python
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/dmang-dev/mcp-mgba'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
