Clarify that debug_wait_for_stop and debug_capture_at_breakpoint block

Make it explicit in tool descriptions and docs that these tools block
until a breakpoint is hit or timeout expires, and that the caller must
trigger a request externally while waiting.

Author: clavery

docs/mcp/tools/diagnostics.md

@@ -73,7 +73,7 @@ Each breakpoint object:
 
 ### debug_wait_for_stop
 
-Wait for a thread to halt at a breakpoint or step. Returns immediately if a thread is already halted.
+Wait for a thread to halt at a breakpoint or step. Returns immediately if a thread is already halted. Otherwise **blocks** until a halt occurs or the timeout expires — the user or an external process must trigger a request on the instance while this tool is waiting.
 
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
@@ -164,6 +164,8 @@ Evaluate an expression in the context of a halted thread and stack frame.
 
 Set a breakpoint, wait for it to be hit, and capture a diagnostic snapshot — stack, variables, and optional expression results in a single call. Optionally resumes the thread after capture.
 
+> **Important:** This tool **blocks** until the breakpoint is hit or the timeout expires. The user or an external process must trigger a request on the instance while this tool is waiting.
+
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
 | `session_id` | string | Yes | | Session ID |

packages/b2c-dx-mcp/src/tools/diagnostics/debug-capture-at-breakpoint.ts

@@ -69,8 +69,9 @@ export function createDebugCaptureAtBreakpointTool(
       name: 'debug_capture_at_breakpoint',
       description:
         'Set a breakpoint, wait for it to be hit, and capture a diagnostic snapshot (stack, variables, expression results). ' +
+        'IMPORTANT: This tool BLOCKS until the breakpoint is hit or the timeout expires — the user or an external process must trigger a request on the instance while this tool is waiting. ' +
         'Optionally resumes the thread after capture. ' +
-        'This is a higher-level tool that combines debug_set_breakpoints, debug_wait_for_stop, debug_get_stack, debug_get_variables, and debug_evaluate.',
+        'Combines debug_set_breakpoints, debug_wait_for_stop, debug_get_stack, debug_get_variables, and debug_evaluate in a single call.',
       toolsets: ['CARTRIDGES', 'SCAPI', 'STOREFRONTNEXT'],
       inputSchema: {
         session_id: z.string().describe('Session ID returned by debug_start_session.'),

packages/b2c-dx-mcp/src/tools/diagnostics/debug-wait-for-stop.ts

@@ -41,7 +41,7 @@ export function createDebugWaitForStopTool(
       description:
         'Wait for a thread to halt at a breakpoint or step. ' +
         'Returns immediately if a thread is already halted. ' +
-        'Otherwise blocks until a halt occurs or the timeout expires.',
+        'Otherwise BLOCKS until a halt occurs or the timeout expires — the user or an external process must trigger a request on the instance while this tool is waiting.',
       toolsets: ['CARTRIDGES', 'SCAPI', 'STOREFRONTNEXT'],
       inputSchema: {
         session_id: z.string().describe('Session ID returned by debug_start_session.'),