Skip to main content
Glama

Debug This Crash

debug_this_crash
Destructive

Inspect stopped debugger sessions or core dumps and launch DAP debuggers to gather stack, variables, and exception evidence, returning a root-cause diagnosis with verification status.

Instructions

Preferred high-level native crash workflow. Use mode=current for an already stopped session, dump for read-only postmortem analysis, codelldb to discover CodeLLDB, lldb-dap to discover upstream LLVM lldb-dap, gdb to discover GNU GDB built-in DAP interpreter, or live with an already initialized generic DAP adapter. Do not use codelldb/lldb-dap/gdb/live when executing or attaching to the target is not authorized: those modes can run application code and cause its normal side effects, while current/dump only inspect stopped evidence. workflow.stage selects initial diagnosis, verification against a prior baseline, or the bounded autonomous cycle. Returns runtime evidence, diagnosis, verification/autonomous metadata, and debugger status with deterministic fixed/blocked/budget-exhausted outcomes where applicable.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
cwdNoWorking directory for the selected debugger/target launch and a project-root hint for diagnosis.
envNoEnvironment variables supplied to the launched program in codelldb/lldb-dap/gdb modes.
argsNoCommand-line arguments passed to the launched program in codelldb/lldb-dap/gdb modes.
modeNocurrent inspects an existing stop; live uses an initialized generic DAP session; codelldb starts CodeLLDB; lldb-dap starts upstream LLVM lldb-dap; gdb starts GNU GDB with --interpreter=dap; dump opens a frozen core/minidump.current
programNoRequired for codelldb/lldb-dap/gdb launch modes; optional for CodeLLDB/GDB dumps but required when dumpAdapter=lldb-dap. Local path to the native executable.
requestNoFor mode=live, choose whether the initialized DAP adapter launches a target or attaches to an existing authorized target.launch
analysisNoHints used to distinguish project code from runtime, system, or third-party frames.
dumpPathNoRequired for mode=dump: local path to the native core/minidump file.
snapshotNoBounds and optional evidence categories for a runtime crash snapshot.
workflowNoControls one-shot diagnosis, explicit verification, or the bounded autonomous crash workflow.
sessionIdNoOptional DAP session ID. Omit to use the backward-compatible default session.
sourceMapNoFor mode=dump, map source paths stored in debug symbols to local source paths.
timeoutMsNoMaximum milliseconds to wait for the reproduction to stop, exit, or terminate.
adapterPathNoOptional explicit debugger executable/adapter path for codelldb/lldb-dap/gdb/dump modes; omit to auto-discover the selected adapter.
breakpointsNoOptional source breakpoints configured before a live/codelldb reproduction completes setup.
dumpAdapterNoFor mode=dump, choose CodeLLDB, upstream LLVM lldb-dap coreFile loading, or GNU GDB coreFile attach semantics.codelldb
stopOnEntryNoWhen true in codelldb/lldb-dap/gdb modes, request an initial debugger stop at program entry before normal execution.
configurationNoRequired for mode=live: adapter-specific DAP launch/attach configuration.
requestTimeoutMsNoPer-request DAP timeout in milliseconds for the selected debugger adapter.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
modeYes
statusYes
workflowNo
diagnosisNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed12 schema fields changedv0.17.0
    • changedInput schema / properties / adapterPath / description
      Previous value: -"Optional explicit debugger-adapter executable path for codelldb/lldb-dap/dump modes; omit to auto-discover the selected adapter."New value: +"Optional explicit debugger executable/adapter path for codelldb/lldb-dap/gdb/dump modes; omit to auto-discover the selected adapter."
    • changedInput schema / properties / args / description
      Previous value: -"Command-line arguments passed to the launched program in mode=codelldb or mode=lldb-dap."New value: +"Command-line arguments passed to the launched program in codelldb/lldb-dap/gdb modes."
    • changedInput schema / properties / dumpAdapter / description
      Previous value: -"For mode=dump, choose CodeLLDB compatibility behavior or upstream LLVM lldb-dap coreFile loading."New value: +"For mode=dump, choose CodeLLDB, upstream LLVM lldb-dap coreFile loading, or GNU GDB coreFile attach semantics."
    • changedInput schema / properties / dumpAdapter / enum
      Previous value: -[
      -  "codelldb",
      -  "lldb-dap"
      -]New value: +[
      +  "codelldb",
      +  "lldb-dap",
      +  "gdb"
      +]
    • changedInput schema / properties / env / description
      Previous value: -"Environment variables supplied to the launched program in mode=codelldb or mode=lldb-dap."New value: +"Environment variables supplied to the launched program in codelldb/lldb-dap/gdb modes."
    • changedInput schema / properties / mode / description
      Previous value: -"current inspects an existing stop; live runs launch/attach through an initialized DAP session; codelldb starts CodeLLDB; lldb-dap starts upstream LLVM lldb-dap; dump opens a frozen core/minidump."New value: +"current inspects an existing stop; live uses an initialized generic DAP session; codelldb starts CodeLLDB; lldb-dap starts upstream LLVM lldb-dap; gdb starts GNU GDB with --interpreter=dap; dump opens a frozen core/minidump."
    • changedInput schema / properties / mode / enum
      Previous value: -[
      -  "current",
      -  "live",
      -  "codelldb",
      -  "lldb-dap",
      -  "dump"
      -]New value: +[
      +  "current",
      +  "live",
      +  "codelldb",
      +  "lldb-dap",
      +  "gdb",
      +  "dump"
      +]
    • changedInput schema / properties / program / description
      Previous value: -"Required for mode=codelldb and mode=lldb-dap; optional for CodeLLDB dumps but required when dumpAdapter=lldb-dap. Local path to the native executable."New value: +"Required for codelldb/lldb-dap/gdb launch modes; optional for CodeLLDB/GDB dumps but required when dumpAdapter=lldb-dap. Local path to the native executable."
    • changedInput schema / properties / requestTimeoutMs / description
      Previous value: -"Per-request DAP timeout in milliseconds for CodeLLDB operations."New value: +"Per-request DAP timeout in milliseconds for the selected debugger adapter."
    • addedInput schema / properties / sessionId
      Added value: +{
      +  "description": "Optional DAP session ID. Omit to use the backward-compatible default session.",
      +  "maxLength": 64,
      +  "minLength": 1,
      +  "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$",
      +  "type": "string"
      +}
    • changedInput schema / properties / stopOnEntry / description
      Previous value: -"When true in mode=codelldb or mode=lldb-dap, request an initial debugger stop at program entry before normal execution."New value: +"When true in codelldb/lldb-dap/gdb modes, request an initial debugger stop at program entry before normal execution."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "https://json-schema.org/draft/2020-12/schema",
      +  "additionalProperties": {},
      +  "properties": {
      +    "diagnosis": {},
      +    "mode": {
      +      "enum": [
      +        "current",
      +        "live",
      +        "codelldb",
      +        "lldb-dap",
      +        "gdb",
      +        "dump"
      +      ],
      +      "type": "string"
      +    },
      +    "status": {
      +      "additionalProperties": {},
      +      "properties": {
      +        "activeRequest": {
      +          "enum": [
      +            "launch",
      +            "attach"
      +          ],
      +          "type": "string"
      +        },
      +        "adapterId": {
      +          "type": "string"
      +        },
      +        "adapterPid": {
      +          "exclusiveMinimum": 0,
      +          "maximum": 9007199254740991,
      +          "type": "integer"
      +        },
      +        "adapterRunning": {
      +          "type": "boolean"
      +        },
      +        "capabilities": {
      +          "additionalProperties": {},
      +          "properties": {},
      +          "type": "object"
      +        },
      +        "configured": {
      +          "type": "boolean"
      +        },
      +        "initialized": {
      +          "type": "boolean"
      +        },
      +        "recentAdapterStderr": {
      +          "items": {
      +            "type": "string"
      +          },
      +          "type": "array"
      +        },
      +        "recentEvents": {
      +          "items": {},
      +          "type": "array"
      +        }
      +      },
      +      "required": [
      +        "adapterRunning",
      +        "initialized",
      +        "configured",
      +        "recentEvents",
      +        "recentAdapterStderr"
      +      ],
      +      "type": "object"
      +    },
      +    "workflow": {}
      +  },
      +  "required": [
      +    "mode",
      +    "status"
      +  ],
      +  "type": "object"
      +}
  2. Changed9 schema fields changedv0.13.0
    • changedInput schema / properties / adapterPath / description
      Previous value: -"Optional explicit CodeLLDB executable path for codelldb/dump modes; omit to auto-discover it."New value: +"Optional explicit debugger-adapter executable path for codelldb/lldb-dap/dump modes; omit to auto-discover the selected adapter."
    • changedInput schema / properties / args / description
      Previous value: -"Command-line arguments passed to the launched program in mode=codelldb."New value: +"Command-line arguments passed to the launched program in mode=codelldb or mode=lldb-dap."
    • changedInput schema / properties / cwd / description
      Previous value: -"Working directory for CodeLLDB/target launch and a project-root hint for diagnosis."New value: +"Working directory for the selected debugger/target launch and a project-root hint for diagnosis."
    • addedInput schema / properties / dumpAdapter
      Added value: +{
      +  "default": "codelldb",
      +  "description": "For mode=dump, choose CodeLLDB compatibility behavior or upstream LLVM lldb-dap coreFile loading.",
      +  "enum": [
      +    "codelldb",
      +    "lldb-dap"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / properties / env / description
      Previous value: -"Environment variables supplied to the launched program in mode=codelldb."New value: +"Environment variables supplied to the launched program in mode=codelldb or mode=lldb-dap."
    • changedInput schema / properties / mode / description
      Previous value: -"current inspects an existing stop; live runs launch/attach through an initialized DAP session; codelldb starts CodeLLDB and launches program; dump opens a frozen core/minidump."New value: +"current inspects an existing stop; live runs launch/attach through an initialized DAP session; codelldb starts CodeLLDB; lldb-dap starts upstream LLVM lldb-dap; dump opens a frozen core/minidump."
    • changedInput schema / properties / mode / enum
      Previous value: -[
      -  "current",
      -  "live",
      -  "codelldb",
      -  "dump"
      -]New value: +[
      +  "current",
      +  "live",
      +  "codelldb",
      +  "lldb-dap",
      +  "dump"
      +]
    • changedInput schema / properties / program / description
      Previous value: -"Required for mode=codelldb; optional for dump symbol resolution. Local path to the native executable."New value: +"Required for mode=codelldb and mode=lldb-dap; optional for CodeLLDB dumps but required when dumpAdapter=lldb-dap. Local path to the native executable."
    • changedInput schema / properties / stopOnEntry / description
      Previous value: -"When true in mode=codelldb, request an initial debugger stop at program entry before normal execution."New value: +"When true in mode=codelldb or mode=lldb-dap, request an initial debugger stop at program entry before normal execution."
  3. Changed36 schema fields changedv0.12.1
    • addedInput schema / properties / adapterPath / description
      Added value: +"Optional explicit CodeLLDB executable path for codelldb/dump modes; omit to auto-discover it."
    • addedInput schema / properties / analysis / description
      Added value: +"Hints used to distinguish project code from runtime, system, or third-party frames."
    • addedInput schema / properties / analysis / properties / callerDepth / description
      Added value: +"How many project-controlled caller frames beyond the selected frame to inspect for provenance and root cause."
    • addedInput schema / properties / analysis / properties / projectModules / description
      Added value: +"Optional executable or library names treated as project-controlled modules during frame selection."
    • addedInput schema / properties / analysis / properties / projectRoots / description
      Added value: +"Optional local source-root paths used to recognize project-controlled stack frames."
    • addedInput schema / properties / args / description
      Added value: +"Command-line arguments passed to the launched program in mode=codelldb."
    • addedInput schema / properties / breakpoints / description
      Added value: +"Optional source breakpoints configured before a live/codelldb reproduction completes setup."
    • addedInput schema / properties / breakpoints / items / description
      Added value: +"Source file and line breakpoints configured before a live reproduction runs."
    • addedInput schema / properties / breakpoints / items / properties / lines / description
      Added value: +"One or more 1-based source line numbers to replace as breakpoints for this source file."
    • changedInput schema / properties / breakpoints / items / properties / source / description
      Previous value: -"Absolute or adapter-resolvable source file path"New value: +"Absolute or adapter-resolvable source file path."
    • addedInput schema / properties / configuration / description
      Added value: +"Required for mode=live: adapter-specific DAP launch/attach configuration."
    • addedInput schema / properties / cwd / description
      Added value: +"Working directory for CodeLLDB/target launch and a project-root hint for diagnosis."
    • addedInput schema / properties / dumpPath / description
      Added value: +"Required for mode=dump: local path to the native core/minidump file."
    • addedInput schema / properties / env / description
      Added value: +"Environment variables supplied to the launched program in mode=codelldb."
    • addedInput schema / properties / mode / description
      Added value: +"current inspects an existing stop; live runs launch/attach through an initialized DAP session; codelldb starts CodeLLDB and launches program; dump opens a frozen core/minidump."
    • addedInput schema / properties / program / description
      Added value: +"Required for mode=codelldb; optional for dump symbol resolution. Local path to the native executable."
    • addedInput schema / properties / request / description
      Added value: +"For mode=live, choose whether the initialized DAP adapter launches a target or attaches to an existing authorized target."
    • addedInput schema / properties / requestTimeoutMs / description
      Added value: +"Per-request DAP timeout in milliseconds for CodeLLDB operations."
    • addedInput schema / properties / snapshot / description
      Added value: +"Bounds and optional evidence categories for a runtime crash snapshot."
    • addedInput schema / properties / snapshot / properties / disassembleAfter / description
      Added value: +"Number of instructions after the selected instruction to request."
    • addedInput schema / properties / snapshot / properties / disassembleBefore / description
      Added value: +"Number of instructions before the selected instruction to request."
    • addedInput schema / properties / snapshot / properties / includeDisassembly / description
      Added value: +"Include best-effort disassembly around the selected instruction pointer when supported."
    • addedInput schema / properties / snapshot / properties / includeExceptionInfo / description
      Added value: +"Request structured exception information for the stopped thread when supported."
    • addedInput schema / properties / snapshot / properties / includeModules / description
      Added value: +"Include a bounded list of loaded executable images and libraries."
    • addedInput schema / properties / snapshot / properties / maxVariablesPerScope / description
      Added value: +"Maximum variables returned per inspected scope, bounding evidence size."
    • addedInput schema / properties / snapshot / properties / moduleCount / description
      Added value: +"Maximum loaded modules to include when module collection is enabled."
    • addedInput schema / properties / snapshot / properties / stackLevels / description
      Added value: +"Maximum number of stack frames to inspect when collecting crash evidence."
    • addedInput schema / properties / snapshot / properties / threadId / description
      Added value: +"Stopped DAP thread to inspect; omit to use the session-selected stopped thread."
    • addedInput schema / properties / sourceMap / description
      Added value: +"For mode=dump, map source paths stored in debug symbols to local source paths."
    • addedInput schema / properties / stopOnEntry / description
      Added value: +"When true in mode=codelldb, request an initial debugger stop at program entry before normal execution."
    • addedInput schema / properties / timeoutMs / description
      Added value: +"Maximum milliseconds to wait for the reproduction to stop, exit, or terminate."
    • addedInput schema / properties / workflow / description
      Added value: +"Controls one-shot diagnosis, explicit verification, or the bounded autonomous crash workflow."
    • addedInput schema / properties / workflow / properties / agentState / description
      Added value: +"Opaque autonomous state returned by the previous autonomous call; pass it back unchanged to continue the bounded cycle."
    • addedInput schema / properties / workflow / properties / baseline / description
      Added value: +"Verification baseline returned by an earlier diagnosis; required when stage=verify."
    • addedInput schema / properties / workflow / properties / maxIterations / description
      Added value: +"Maximum autonomous fix/reproduce iterations allowed when starting stage=autonomous."
    • addedInput schema / properties / workflow / properties / stage / description
      Added value: +"diagnose creates initial evidence; verify compares against a prior verification baseline; autonomous advances the bounded agent state machine."
  4. Addedv0.12.0

TDQS

A4.5/5.0
Behavior5/5

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

Beyond the destructiveHint=true annotation, the description discloses mode-specific side effects: codelldb/lldb-dap/gdb/live 'can run application code and cause its normal side effects, while current/dump only inspect stopped evidence.' It also states the deterministic outcomes (fixed/blocked/budget-exhausted), which is valuable behavioral context an agent cannot infer from the schema alone.

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?

The description is about five dense sentences, each carrying a distinct job: purpose, mode routing, safety exclusion, workflow stage selection, and return content. It is front-loaded with the core purpose and avoids restating schema details, making it very efficient for a tool with 19 parameters and nested objects.

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

Completeness5/5

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

For a highly complex tool, the description covers the key decisions an agent must make: which mode to select, when execution is unsafe, which workflow stage to use, and what the tool returns. The remaining parameter details and return shape are handled by the rich input and output schemas, so nothing essential is missing.

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

Parameters3/5

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

Schema description coverage is 100% and the parameter descriptions in the schema are already rich, so the baseline is 3. The tool description adds high-level grouping around mode safety and workflow stages but does not add meaningful per-parameter semantics beyond what the schema already provides.

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?

The description clearly identifies the tool as a 'preferred high-level native crash workflow' and enumerates the concrete modes (current, dump, codelldb, lldb-dap, gdb, live), so an agent knows what operation it performs. It does not explicitly differentiate itself from sibling tools like debug_open_dump or debug_diagnose_stop by name, which keeps it from a 5.

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

Usage Guidelines5/5

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

The description gives explicit routing guidance for every mode, including an explicit exclusion: 'Do not use codelldb/lldb-dap/gdb/live when executing or attaching to the target is not authorized.' It also explains why those modes are risky and why current/dump are safer, and maps workflow.stage to diagnose, verify, and autonomous behaviors.

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