getsentry · cameroncooke · May 17, 2026 · May 16, 2026 · May 16, 2026 · May 16, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -47,6 +47,7 @@ ESM TypeScript project (`type: module`). Key layers:
 - **NEVER use inline imports** - no `await import("./foo.js")`, no `import("pkg").Type` in type positions, no dynamic imports for types. Always use standard top-level imports.
 - NEVER remove or downgrade code to fix type errors from outdated dependencies; upgrade the dependency instead
 - Always ask before removing functionality or code that appears to be intentional
+- Do not add fallback behavior by default. If required context, configuration, runtime state, or dependencies are missing, fail loudly and fix the caller/setup instead of silently switching to an alternate path. Add a fallback only when explicitly requested or when it is a documented product requirement.
 - Follow TypeScript best practices
 
 ## Import Conventions

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## [Unreleased]
+
+### Added
+
+- Added `nextSteps` hint lines to MCP `structuredContent` and CLI `--output json` envelopes so agents can consume follow-up actions without scraping text. CLI JSON renders shell command lines; MCP structured content renders MCP tool-call hints. Structured result schemas that include `nextSteps` now use schema version 2; existing version 1 schema files remain available for current validators.
+
 ## [2.5.2]
 
 ### Changed

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -6,6 +6,7 @@
 - **NEVER use inline imports** - no `await import("./foo.js")`, no `import("pkg").Type` in type positions, no dynamic imports for types. Always use standard top-level imports.
 - NEVER remove or downgrade code to fix type errors from outdated dependencies; upgrade the dependency instead
 - Always ask before removing functionality or code that appears to be intentional
+- Do not add fallback behavior by default. If required context, configuration, runtime state, or dependencies are missing, fail loudly and fix the caller/setup instead of silently switching to an alternate path. Add a fallback only when explicitly requested or when it is a documented product requirement.
 - Follow TypeScript best practices
 
 ## Commands

diff --git a/manifests/tools/boot_sim.yaml b/manifests/tools/boot_sim.yaml
@@ -6,7 +6,7 @@ names:
 description: Boot iOS simulator for manual/non-build flows. Not required before simulator build-and-run (build_run_sim).
 outputSchema:
   schema: xcodebuildmcp.output.simulator-action-result
-  version: "1"
+  version: "2"
 annotations:
   title: Boot Simulator
   readOnlyHint: false

diff --git a/manifests/tools/build_device.yaml b/manifests/tools/build_device.yaml
@@ -6,7 +6,7 @@ names:
 description: Build for device.
 outputSchema:
   schema: xcodebuildmcp.output.build-result
-  version: "1"
+  version: "2"
 predicates:
   - hideWhenXcodeAgentMode
 annotations:

diff --git a/manifests/tools/build_macos.yaml b/manifests/tools/build_macos.yaml
@@ -6,7 +6,7 @@ names:
 description: Build macOS app.
 outputSchema:
   schema: xcodebuildmcp.output.build-result
-  version: "1"
+  version: "2"
 predicates:
   - hideWhenXcodeAgentMode
 annotations:

diff --git a/manifests/tools/build_run_device.yaml b/manifests/tools/build_run_device.yaml
@@ -6,7 +6,7 @@ names:
 description: Build, install, and launch on physical device. Preferred single-step run tool when defaults are set.
 outputSchema:
   schema: xcodebuildmcp.output.build-run-result
-  version: '1'
+  version: "2"
 predicates:
   - hideWhenXcodeAgentMode
 annotations:

diff --git a/manifests/tools/build_run_macos.yaml b/manifests/tools/build_run_macos.yaml
@@ -6,7 +6,7 @@ names:
 description: Build and run macOS app.
 outputSchema:
   schema: xcodebuildmcp.output.build-run-result
-  version: "1"
+  version: "2"
 predicates:
   - hideWhenXcodeAgentMode
 annotations:

diff --git a/manifests/tools/build_run_sim.yaml b/manifests/tools/build_run_sim.yaml
@@ -6,7 +6,7 @@ names:
 description: Build, install, and launch on iOS Simulator; boots simulator and attempts to open Simulator.app as needed. Runtime logs are captured automatically and the log file path is included in the response. Preferred single-step run tool when defaults are set.
 outputSchema:
   schema: xcodebuildmcp.output.build-run-result
-  version: "1"
+  version: "2"
 predicates:
   - hideWhenXcodeAgentMode
 annotations:

diff --git a/manifests/tools/build_sim.yaml b/manifests/tools/build_sim.yaml
@@ -6,7 +6,7 @@ names:
 description: Build for iOS sim (compile-only, no launch).
 outputSchema:
   schema: xcodebuildmcp.output.build-result
-  version: "1"
+  version: "2"
 predicates:
   - hideWhenXcodeAgentMode
 annotations:

diff --git a/manifests/tools/button.yaml b/manifests/tools/button.yaml
@@ -6,7 +6,7 @@ names:
 description: Press simulator hardware button.
 outputSchema:
   schema: xcodebuildmcp.output.ui-action-result
-  version: "1"
+  version: "2"
 annotations:
   title: Hardware Button
   readOnlyHint: true

diff --git a/manifests/tools/clean.yaml b/manifests/tools/clean.yaml
@@ -6,7 +6,7 @@ names:
 description: Clean build products.
 outputSchema:
   schema: xcodebuildmcp.output.build-result
-  version: "1"
+  version: "2"
 predicates:
   - hideWhenXcodeAgentMode
 annotations:

diff --git a/manifests/tools/debug_attach_sim.yaml b/manifests/tools/debug_attach_sim.yaml
@@ -6,7 +6,7 @@ names:
 description: Attach LLDB to sim app.
 outputSchema:
   schema: xcodebuildmcp.output.debug-session-action
-  version: "1"
+  version: "2"
 routing:
   stateful: true
 annotations:

diff --git a/manifests/tools/debug_breakpoint_add.yaml b/manifests/tools/debug_breakpoint_add.yaml
@@ -6,7 +6,7 @@ names:
 description: Add breakpoint.
 outputSchema:
   schema: xcodebuildmcp.output.debug-breakpoint-result
-  version: "1"
+  version: "2"
 routing:
   stateful: true
 annotations:

diff --git a/manifests/tools/debug_breakpoint_remove.yaml b/manifests/tools/debug_breakpoint_remove.yaml
@@ -6,7 +6,7 @@ names:
 description: Remove breakpoint.
 outputSchema:
   schema: xcodebuildmcp.output.debug-breakpoint-result
-  version: "1"
+  version: "2"
 routing:
   stateful: true
 annotations:

diff --git a/manifests/tools/debug_continue.yaml b/manifests/tools/debug_continue.yaml
@@ -6,7 +6,7 @@ names:
 description: Continue debug session.
 outputSchema:
   schema: xcodebuildmcp.output.debug-session-action
-  version: "1"
+  version: "2"
 routing:
   stateful: true
 annotations:

diff --git a/manifests/tools/debug_detach.yaml b/manifests/tools/debug_detach.yaml
@@ -6,7 +6,7 @@ names:
 description: Detach debugger.
 outputSchema:
   schema: xcodebuildmcp.output.debug-session-action
-  version: "1"
+  version: "2"
 routing:
   stateful: true
 annotations:

diff --git a/manifests/tools/debug_lldb_command.yaml b/manifests/tools/debug_lldb_command.yaml
@@ -6,7 +6,7 @@ names:
 description: Run LLDB command.
 outputSchema:
   schema: xcodebuildmcp.output.debug-command-result
-  version: "1"
+  version: "2"
 routing:
   stateful: true
 annotations:

diff --git a/manifests/tools/debug_stack.yaml b/manifests/tools/debug_stack.yaml
@@ -6,7 +6,7 @@ names:
 description: Get backtrace.
 outputSchema:
   schema: xcodebuildmcp.output.debug-stack-result
-  version: "1"
+  version: "2"
 routing:
   stateful: true
 annotations:

diff --git a/manifests/tools/debug_variables.yaml b/manifests/tools/debug_variables.yaml
@@ -6,7 +6,7 @@ names:
 description: Get frame variables.
 outputSchema:
   schema: xcodebuildmcp.output.debug-variables-result
-  version: "1"
+  version: "2"
 routing:
   stateful: true
 annotations:

diff --git a/manifests/tools/discover_projs.yaml b/manifests/tools/discover_projs.yaml
@@ -6,7 +6,7 @@ names:
 description: Scans a directory (defaults to workspace root) to find Xcode project (.xcodeproj) and workspace (.xcworkspace) files. Use when project/workspace path is unknown.
 outputSchema:
   schema: xcodebuildmcp.output.project-list
-  version: "1"
+  version: "2"
 annotations:
   title: Discover Projects
   readOnlyHint: true

diff --git a/manifests/tools/doctor.yaml b/manifests/tools/doctor.yaml
@@ -6,7 +6,7 @@ names:
 description: MCP environment info.
 outputSchema:
   schema: xcodebuildmcp.output.doctor-report
-  version: "1"
+  version: "2"
 annotations:
   title: Doctor
   readOnlyHint: true

diff --git a/manifests/tools/erase_sims.yaml b/manifests/tools/erase_sims.yaml
@@ -6,7 +6,7 @@ names:
 description: Erase simulator.
 outputSchema:
   schema: xcodebuildmcp.output.simulator-action-result
-  version: "1"
+  version: "2"
 annotations:
   title: Erase Simulators
   readOnlyHint: false

diff --git a/manifests/tools/gesture.yaml b/manifests/tools/gesture.yaml
@@ -6,7 +6,7 @@ names:
 description: Simulator gesture preset.
 outputSchema:
   schema: xcodebuildmcp.output.ui-action-result
-  version: "1"
+  version: "2"
 annotations:
   title: Gesture
   readOnlyHint: true

diff --git a/manifests/tools/get_app_bundle_id.yaml b/manifests/tools/get_app_bundle_id.yaml
@@ -6,7 +6,7 @@ names:
 description: Extract bundle id from .app.
 outputSchema:
   schema: xcodebuildmcp.output.bundle-id
-  version: "1"
+  version: "2"
 annotations:
   title: Get App Bundle ID
   readOnlyHint: true

diff --git a/manifests/tools/get_coverage_report.yaml b/manifests/tools/get_coverage_report.yaml
@@ -6,7 +6,7 @@ names:
 description: Show per-target code coverage from an xcresult bundle.
 outputSchema:
   schema: xcodebuildmcp.output.coverage-result
-  version: "1"
+  version: "2"
 annotations:
   title: Get Coverage Report
   readOnlyHint: true

diff --git a/manifests/tools/get_device_app_path.yaml b/manifests/tools/get_device_app_path.yaml
@@ -6,7 +6,7 @@ names:
 description: Get device built app path.
 outputSchema:
   schema: xcodebuildmcp.output.app-path
-  version: "1"
+  version: "2"
 annotations:
   title: Get Device App Path
   readOnlyHint: true

diff --git a/manifests/tools/get_file_coverage.yaml b/manifests/tools/get_file_coverage.yaml
@@ -6,7 +6,7 @@ names:
 description: Show function-level coverage and uncovered line ranges for a specific file.
 outputSchema:
   schema: xcodebuildmcp.output.coverage-result
-  version: "1"
+  version: "2"
 annotations:
   title: Get File Coverage
   readOnlyHint: true

diff --git a/manifests/tools/get_mac_app_path.yaml b/manifests/tools/get_mac_app_path.yaml
@@ -6,7 +6,7 @@ names:
 description: Get macOS built app path.
 outputSchema:
   schema: xcodebuildmcp.output.app-path
-  version: "1"
+  version: "2"
 annotations:
   title: Get macOS App Path
   readOnlyHint: true

diff --git a/manifests/tools/get_mac_bundle_id.yaml b/manifests/tools/get_mac_bundle_id.yaml
@@ -6,7 +6,7 @@ names:
 description: Extract bundle id from macOS .app.
 outputSchema:
   schema: xcodebuildmcp.output.bundle-id
-  version: "1"
+  version: "2"
 annotations:
   title: Get Mac Bundle ID
   readOnlyHint: true

diff --git a/manifests/tools/get_sim_app_path.yaml b/manifests/tools/get_sim_app_path.yaml
@@ -6,7 +6,7 @@ names:
 description: Get sim built app path.
 outputSchema:
   schema: xcodebuildmcp.output.app-path
-  version: "1"
+  version: "2"
 annotations:
   title: Get Simulator App Path
   readOnlyHint: true

diff --git a/manifests/tools/install_app_device.yaml b/manifests/tools/install_app_device.yaml
@@ -6,7 +6,7 @@ names:
 description: Install app on device.
 outputSchema:
   schema: xcodebuildmcp.output.install-result
-  version: "1"
+  version: "2"
 annotations:
   title: Install App Device
   readOnlyHint: false

diff --git a/manifests/tools/install_app_sim.yaml b/manifests/tools/install_app_sim.yaml
@@ -6,7 +6,7 @@ names:
 description: Install app on sim.
 outputSchema:
   schema: xcodebuildmcp.output.install-result
-  version: "1"
+  version: "2"
 annotations:
   title: Install App Simulator
   readOnlyHint: false

diff --git a/manifests/tools/key_press.yaml b/manifests/tools/key_press.yaml
@@ -6,7 +6,7 @@ names:
 description: Press key by keycode.
 outputSchema:
   schema: xcodebuildmcp.output.ui-action-result
-  version: "1"
+  version: "2"
 annotations:
   title: Key Press
   readOnlyHint: true

diff --git a/manifests/tools/key_sequence.yaml b/manifests/tools/key_sequence.yaml
@@ -6,7 +6,7 @@ names:
 description: Press a sequence of keys by their keycodes.
 outputSchema:
   schema: xcodebuildmcp.output.ui-action-result
-  version: "1"
+  version: "2"
 annotations:
   title: Key Sequence
   readOnlyHint: true

diff --git a/manifests/tools/launch_app_device.yaml b/manifests/tools/launch_app_device.yaml
@@ -6,7 +6,7 @@ names:
 description: Launch app on device.
 outputSchema:
   schema: xcodebuildmcp.output.launch-result
-  version: "1"
+  version: "2"
 annotations:
   title: Launch App Device
   readOnlyHint: false

diff --git a/manifests/tools/launch_app_sim.yaml b/manifests/tools/launch_app_sim.yaml
@@ -6,7 +6,7 @@ names:
 description: Launch app on simulator. Runtime logs are captured automatically and the log file path is included in the response.
 outputSchema:
   schema: xcodebuildmcp.output.launch-result
-  version: "1"
+  version: "2"
 annotations:
   title: Launch App Simulator
   readOnlyHint: false

diff --git a/manifests/tools/launch_mac_app.yaml b/manifests/tools/launch_mac_app.yaml
@@ -6,7 +6,7 @@ names:
 description: Launch macOS app.
 outputSchema:
   schema: xcodebuildmcp.output.launch-result
-  version: "1"
+  version: "2"
 annotations:
   title: Launch macOS App
   readOnlyHint: false

diff --git a/manifests/tools/list_devices.yaml b/manifests/tools/list_devices.yaml
@@ -6,7 +6,7 @@ names:
 description: List connected devices.
 outputSchema:
   schema: xcodebuildmcp.output.device-list
-  version: "1"
+  version: "2"
 annotations:
   title: List Devices
   readOnlyHint: true

diff --git a/manifests/tools/list_schemes.yaml b/manifests/tools/list_schemes.yaml
@@ -6,7 +6,7 @@ names:
 description: List Xcode schemes.
 outputSchema:
   schema: xcodebuildmcp.output.scheme-list
-  version: "1"
+  version: "2"
 annotations:
   title: List Schemes
   readOnlyHint: true

diff --git a/manifests/tools/list_sims.yaml b/manifests/tools/list_sims.yaml
@@ -6,7 +6,7 @@ names:
 description: List iOS simulators.
 outputSchema:
   schema: xcodebuildmcp.output.simulator-list
-  version: "1"
+  version: "2"
 annotations:
   title: List Simulators
   readOnlyHint: true

diff --git a/manifests/tools/long_press.yaml b/manifests/tools/long_press.yaml
@@ -6,7 +6,7 @@ names:
 description: Long press at coords.
 outputSchema:
   schema: xcodebuildmcp.output.ui-action-result
-  version: "1"
+  version: "2"
 annotations:
   title: Long Press
   readOnlyHint: true

diff --git a/manifests/tools/manage_workflows.yaml b/manifests/tools/manage_workflows.yaml
@@ -6,7 +6,7 @@ names:
 description: Workflows are groups of tools exposed by XcodeBuildMCP. By default, not all workflows (and therefore tools) are enabled; only simulator tools are enabled by default. Some workflows are mandatory and can't be disabled.
 outputSchema:
   schema: xcodebuildmcp.output.workflow-selection
-  version: "1"
+  version: "2"
 availability:
   cli: true
 annotations:

diff --git a/manifests/tools/open_sim.yaml b/manifests/tools/open_sim.yaml
@@ -6,7 +6,7 @@ names:
 description: Open Simulator.app for visibility/manual workflows. Not required before simulator build-and-run (build_run_sim).
 outputSchema:
   schema: xcodebuildmcp.output.simulator-action-result
-  version: "1"
+  version: "2"
 annotations:
   title: Open Simulator
   readOnlyHint: true