Skip to main content
Glama

gc_instance_start

Starts a new Dolphin emulator instance and boots a specified GameCube ROM, DOL, or ELF file with configurable controller, video, BBA, and resolution settings.

Instructions

Start a new Dolphin instance booting the given ROM/DOL/ELF.

Args: instance_id: Unique id for the instance. rom_path: Path to a .iso/.gcm/.dol/.elf file. controller_ports: Which GameCube ports (0-3) get a controller (default [0]). bba_mode: Broadband Adapter mode: ipc, hle, xlink, tap, tapserver, modem, or None/empty to disable. bba_mac: MAC address for the BBA (must start with 00:09:bf or 00:17:ab). video_backend: OGL, Vulkan, Null, or Software Renderer. capture_backend: auto, xvfb, or framedump. memory_backend: process_vm or dolphin_engine. internal_resolution: 1x/2x/... internal resolution. native_resolution: GameCube native framebuffer "WxH" (default 640x480). gpu_accel: auto/none/software/vgl/vgl-egl/vgl-glx (default auto). extra_core: Extra Dolphin.ini [Core] overrides. boot_ipl: Boot the original GameCube IPL (disable "Skip System Menu"), so the boot logo/menu runs before the disc. Only meaningful for a GameCube disc ('.iso'/'.gcm'); requires the server to be configured with a GC_MCP_IPL_DIR folder containing /IPL.bin files (see gc_server_info). Errors if IPL boot is requested but no IPL folder/files are configured. info: Free-form description/annotation shown in list and status output.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "instance_id": "<instance_id>",
      "rom_path": "<rom_path>"
    },
    "name": "gc_instance_start"
  }
}

Input Schema

NameRequiredDescriptionDefault
infoNo
bba_macNo
bba_modeNo
boot_iplNo
rom_pathYes
gpu_accelNo
extra_coreNo
instance_idYes
video_backendNo
memory_backendNo
capture_backendNo
controller_portsNo
native_resolutionNo
internal_resolutionNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.6/5.0
Behavior3/5

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

No annotations are supplied, so the description carries the full burden. It does disclose one real behavioral constraint — boot_ipl errors if the server has no GC_MCP_IPL_DIR with <REGION>/IPL.bin, and points to gc_server_info — but omits whether start blocks until boot completes, what happens on a duplicate instance_id, resource limits on concurrent instances, or that a started instance must later be stopped/removed.

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

Conciseness5/5

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

A single front-loaded purpose sentence followed by one tight line per parameter; nothing is repeated from the schema title. Length is justified by 14 parameters with zero schema documentation, and the boot_ipl entry is the only multi-line one, appropriately so.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The definition is complete on the input side but thin for a process-spawning mutation with no annotations and no output schema: return value (instance handle/handle shape), failure modes beyond boot_ipl, and lifecycle expectations after start are unstated. An agent knows how to call it but not fully what to expect back.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% across 14 parameters, so the description must compensate, and it largely does: every parameter gets a meaning, sensible allowed values (bba modes, video backends, gpu_accel options, capture/memory backends), and defaults for controller_ports, native_resolution and gpu_accel. Gaps remain on internal_resolution's integer units, extra_core's key format, and the bba_mode/bba_mac dependency, which prevents a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Start a new Dolphin instance booting the given ROM/DOL/ELF" gives a specific verb (start) plus resource (Dolphin instance) and states the input artifact type. It naturally separates from gc_instance_stop/remove/gc_instance_list in the sibling set, though it does not name those alternatives explicitly.

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

Usage Guidelines3/5

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

Usage is implied by the name and the args list — you call it to create and boot an instance — but there is no explicit when-to-use vs. when-not guidance, no mention of what to do for an already-running instance_id, and no routing to siblings like gc_instance_status after start. The boot_ipl prerequisite note is the only conditional guidance.

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