Chore/refactor tools (#183)

* Add tool audit option

* More tool descriptions more concise

* Move redundent tool arguments to session-defaults

* Add manage-workflows tool to allow agents to add new workflows at run-time

Also renames describe-ui tool to snapshot-ui tool.

* Remnove redundent workflow name

Author: cameroncooke

.cursorrules

@@ -1,8 +1,6 @@
 {
   "recommendations": [
-    "dbaeumer.vscode-eslint"
-  ],
-  "unwantedRecommendations": [
+    "dbaeumer.vscode-eslint",
     "esbenp.prettier-vscode"
   ]
 }

.vscode/extensions.json

@@ -20,12 +20,12 @@
   "editor.codeActionsOnSave": {
     "source.fixAll.eslint": "explicit"
   },
-  "editor.defaultFormatter": "vscode.typescript-language-features",
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
   "[typescript]": {
-    "editor.defaultFormatter": "vscode.typescript-language-features"
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
   },
   "[javascript]": {
-    "editor.defaultFormatter": "vscode.typescript-language-features"
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
   },
   "terminal.integrated.shellIntegration.decorationsEnabled": "never",
   "[json]": {

.vscode/settings.json

@@ -6,10 +6,12 @@
 - Add DAP-based debugger backend and simulator debugging toolset (attach, breakpoints, stack, variables, LLDB command).
 - Add session-status MCP resource with session identifiers.
 - Add UI automation guard that blocks UI tools when the debugger is paused.
+- Add manage-workflows tool for live workflow selection updates.
 
 ### Changed
 - Migrate to Zod v4.
 - Improve session default handling (reconcile mutual exclusivity and ignore explicit undefined clears).
+- Auto-include workflow-discovery when workflow selection is configured.
 
 ### Fixed
 - Update UI automation guard guidance to point at `debug_continue` when paused.

CHANGELOG.md

@@ -17,7 +17,7 @@ XcodeBuildMCP is configured through environment variables provided by your MCP c
 
 ## Workflow selection
 
-By default, XcodeBuildMCP loads all tools at startup. If you want a smaller tool surface for a specific workflow, set `XCODEBUILDMCP_ENABLED_WORKFLOWS` to a comma-separated list of workflow directory names. The `session-management` workflow is always auto-included since other tools depend on it.
+By default, XcodeBuildMCP loads all tools at startup. If you want a smaller tool surface for a specific workflow, set `XCODEBUILDMCP_ENABLED_WORKFLOWS` to a comma-separated list of workflow directory names. The `session-management` workflow is always auto-included since other tools depend on it. When `XCODEBUILDMCP_DEBUG=true`, the `doctor` workflow is also auto-included.
 
 **Available workflows:**
 - `device` (14 tools) - iOS Device Development
@@ -28,6 +28,7 @@ By default, XcodeBuildMCP loads all tools at startup. If you want a smaller tool
 - `project-scaffolding` (2 tools) - Project Scaffolding
 - `utilities` (1 tool) - Project Utilities
 - `session-management` (3 tools) - session-management
+- `workflow-discovery` (1 tool) - Workflow Discovery
 - `debugging` (8 tools) - Simulator Debugging
 - `simulator-management` (8 tools) - Simulator Management
 - `swift-package` (6 tools) - Swift Package Manager
@@ -41,6 +42,12 @@ XcodeBuildMCP includes experimental support for incremental builds. This feature
 > [!IMPORTANT]
 > Incremental builds are highly experimental and your mileage may vary. Please report issues to the [issue tracker](https://github.com/cameroncooke/XcodeBuildMCP/issues).
 
+## Experimental workflow discovery
+
+Set `XCODEBUILDMCP_EXPERIMENTAL_WORKFLOW_DISCOVERY=true` to auto-include the `workflow-discovery` workflow at startup.
+
+The workflow discovery tool lets agents and clients enable or disable workflows at runtime. This can reduce upfront context by loading only what is needed as the session evolves. Note: most clients do not yet support the MCP notifications required for an agent harness to re-query the tool list after changes.
+
 ## Session-aware opt-out
 
 By default, XcodeBuildMCP uses a session-aware mode: the LLM (or client) sets shared defaults once (simulator, device, project/workspace, scheme, etc.), and all tools reuse them. This cuts context bloat not just in each call payload, but also in the tool schemas themselves.

docs/CONFIGURATION.md

@@ -1,125 +1,129 @@
 # XcodeBuildMCP Tools Reference
 
-XcodeBuildMCP provides 71 tools organized into 13 workflow groups for comprehensive Apple development workflows.
+XcodeBuildMCP provides 72 tools organized into 14 workflow groups for comprehensive Apple development workflows.
 
 ## Workflow Groups
 
 ### iOS Device Development (`device`)
 **Purpose**: Complete iOS development workflow for both .xcodeproj and .xcworkspace files targeting physical devices (iPhone, iPad, Apple Watch, Apple TV, Apple Vision Pro). Build, test, deploy, and debug apps on real hardware. (7 tools)
 
-- `build_device` - Builds an app for a connected device.
-- `get_device_app_path` - Retrieves the built app path for a connected device.
-- `install_app_device` - Installs an app on a connected device.
-- `launch_app_device` - Launches an app on a connected device.
-- `list_devices` - Lists connected physical Apple devices (iPhone, iPad, Apple Watch, Apple TV, Apple Vision Pro) with their UUIDs, names, and connection status. Use this to discover physical devices for testing.
-- `stop_app_device` - Stops a running app on a connected device.
-- `test_device` - Runs tests on a physical Apple device.
+- `build_device` - Build for device.
+- `get_device_app_path` - Get device built app path.
+- `install_app_device` - Install app on device.
+- `launch_app_device` - Launch app on device.
+- `list_devices` - List connected devices.
+- `stop_app_device` - Stop device app.
+- `test_device` - Test on device.
 ### iOS Simulator Development (`simulator`)
 **Purpose**: Complete iOS development workflow for both .xcodeproj and .xcworkspace files targeting simulators. Build, test, deploy, and interact with iOS apps on simulators. (12 tools)
 
-- `boot_sim` - Boots an iOS simulator.
-- `build_run_sim` - Builds and runs an app on an iOS simulator.
-- `build_sim` - Builds an app for an iOS simulator.
-- `get_sim_app_path` - Retrieves the built app path for an iOS simulator.
-- `install_app_sim` - Installs an app in an iOS simulator.
-- `launch_app_logs_sim` - Launches an app in an iOS simulator and captures its logs.
-- `launch_app_sim` - Launches an app in an iOS simulator.
-- `list_sims` - Lists available iOS simulators with their UUIDs.
-- `open_sim` - Opens the iOS Simulator app.
-- `record_sim_video` - Starts or stops video capture for an iOS simulator.
-- `stop_app_sim` - Stops an app running in an iOS simulator.
-- `test_sim` - Runs tests on an iOS simulator.
+- `boot_sim` - Boot iOS simulator.
+- `build_run_sim` - Build and run iOS sim.
+- `build_sim` - Build for iOS sim.
+- `get_sim_app_path` - Get sim built app path.
+- `install_app_sim` - Install app on sim.
+- `launch_app_logs_sim` - Launch sim app with logs.
+- `launch_app_sim` - Launch app on simulator.
+- `list_sims` - List iOS simulators.
+- `open_sim` - Open Simulator app.
+- `record_sim_video` - Record sim video.
+- `stop_app_sim` - Stop sim app.
+- `test_sim` - Test on iOS sim.
 ### Log Capture & Management (`logging`)
 **Purpose**: Log capture and management tools for iOS simulators and physical devices. Start, stop, and analyze application and system logs during development and testing. (4 tools)
 
-- `start_device_log_cap` - Starts log capture on a connected device.
-- `start_sim_log_cap` - Starts capturing logs from a specified simulator. Returns a session ID. By default, captures only structured logs.
-- `stop_device_log_cap` - Stops an active Apple device log capture session and returns the captured logs.
-- `stop_sim_log_cap` - Stops an active simulator log capture session and returns the captured logs.
+- `start_device_log_cap` - Start device log capture.
+- `start_sim_log_cap` - Start sim log capture.
+- `stop_device_log_cap` - Stop device log capture.
+- `stop_sim_log_cap` - Stop sim log capture.
 ### macOS Development (`macos`)
 **Purpose**: Complete macOS development workflow for both .xcodeproj and .xcworkspace files. Build, test, deploy, and manage macOS applications. (6 tools)
 
-- `build_macos` - Builds a macOS app.
-- `build_run_macos` - Builds and runs a macOS app.
-- `get_mac_app_path` - Retrieves the built macOS app bundle path.
-- `launch_mac_app` - Launches a macOS application. Note: In some environments, this tool may be prefixed as mcp0_launch_macos_app.
-- `stop_mac_app` - Stops a running macOS application. Can stop by app name or process ID.
-- `test_macos` - Runs tests for a macOS target.
+- `build_macos` - Build macOS app.
+- `build_run_macos` - Build and run macOS app.
+- `get_mac_app_path` - Get macOS built app path.
+- `launch_mac_app` - Launch macOS app.
+- `stop_mac_app` - Stop macOS app.
+- `test_macos` - Test macOS target.
 ### Project Discovery (`project-discovery`)
 **Purpose**: Discover and examine Xcode projects, workspaces, and Swift packages. Analyze project structure, schemes, build settings, and bundle information. (5 tools)
 
 - `discover_projs` - Scans a directory (defaults to workspace root) to find Xcode project (.xcodeproj) and workspace (.xcworkspace) files.
-- `get_app_bundle_id` - Extracts the bundle identifier from an app bundle (.app) for any Apple platform (iOS, iPadOS, watchOS, tvOS, visionOS).
-- `get_mac_bundle_id` - Extracts the bundle identifier from a macOS app bundle (.app). Note: In some environments, this tool may be prefixed as mcp0_get_macos_bundle_id.
-- `list_schemes` - Lists schemes for a project or workspace.
-- `show_build_settings` - Shows xcodebuild build settings.
+- `get_app_bundle_id` - Extract bundle id from .app.
+- `get_mac_bundle_id` - Extract bundle id from macOS .app.
+- `list_schemes` - List Xcode schemes.
+- `show_build_settings` - Show build settings.
 ### Project Scaffolding (`project-scaffolding`)
 **Purpose**: Tools for creating new iOS and macOS projects from templates. Bootstrap new applications with best practices, standard configurations, and modern project structures. (2 tools)
 
-- `scaffold_ios_project` - Scaffold a new iOS project from templates. Creates a modern Xcode project with workspace structure, SPM package for features, and proper iOS configuration.
-- `scaffold_macos_project` - Scaffold a new macOS project from templates. Creates a modern Xcode project with workspace structure, SPM package for features, and proper macOS configuration.
+- `scaffold_ios_project` - Scaffold iOS project.
+- `scaffold_macos_project` - Scaffold macOS project.
 ### Project Utilities (`utilities`)
 **Purpose**: Essential project maintenance utilities for cleaning and managing existing projects. Provides clean operations for both .xcodeproj and .xcworkspace files. (1 tools)
 
-- `clean` - Cleans build products with xcodebuild.
+- `clean` - Clean build products.
 ### session-management (`session-management`)
 **Purpose**: Manage session defaults for projectPath/workspacePath, scheme, configuration, simulatorName/simulatorId, deviceId, useLatestOS and arch. These defaults are required by many tools and must be set before attempting to call tools that would depend on these values. (3 tools)
 
-- `session_clear_defaults` - Clear selected or all session defaults.
-- `session_set_defaults` - Set the session defaults needed by many tools. Most tools require one or more session defaults to be set before they can be used. Agents should set all relevant defaults up front in a single call (e.g., project/workspace, scheme, simulator or device ID, useLatestOS) to avoid iterative prompts; only set the keys your workflow needs.
-- `session_show_defaults` - Show current session defaults.
+- `session_clear_defaults` - Clear session defaults.
+- `session_set_defaults` - Set the session defaults, should be called at least once to set tool defaults.
+- `session_show_defaults` - Show session defaults.
 ### Simulator Debugging (`debugging`)
 **Purpose**: Interactive iOS Simulator debugging tools: attach LLDB, manage breakpoints, inspect stack/variables, and run LLDB commands. (8 tools)
 
-- `debug_attach_sim` - Attach LLDB to a running iOS simulator app. Provide bundleId or pid, plus simulator defaults.
-- `debug_breakpoint_add` - Add a breakpoint by file/line or function name for the active debug session.
-- `debug_breakpoint_remove` - Remove a breakpoint by id for the active debug session.
-- `debug_continue` - Resume execution in the active debug session or a specific debugSessionId.
-- `debug_detach` - Detach the current debugger session or a specific debugSessionId.
-- `debug_lldb_command` - Run an arbitrary LLDB command within the active debug session.
-- `debug_stack` - Return a thread backtrace from the active debug session.
-- `debug_variables` - Return variables for a selected frame in the active debug session.
+- `debug_attach_sim` - Attach LLDB to sim app.
+- `debug_breakpoint_add` - Add breakpoint.
+- `debug_breakpoint_remove` - Remove breakpoint.
+- `debug_continue` - Continue debug session.
+- `debug_detach` - Detach debugger.
+- `debug_lldb_command` - Run LLDB command.
+- `debug_stack` - Get backtrace.
+- `debug_variables` - Get frame variables.
 ### Simulator Management (`simulator-management`)
 **Purpose**: Tools for managing simulators from booting, opening simulators, listing simulators, stopping simulators, erasing simulator content and settings, and setting simulator environment options like location, network, statusbar and appearance. (5 tools)
 
-- `erase_sims` - Erases a simulator by UDID.
-- `reset_sim_location` - Resets the simulator's location to default.
-- `set_sim_appearance` - Sets the appearance mode (dark/light) of an iOS simulator.
-- `set_sim_location` - Sets a custom GPS location for the simulator.
-- `sim_statusbar` - Sets the data network indicator in the iOS simulator status bar. Use "clear" to reset all overrides, or specify a network type (hide, wifi, 3g, 4g, lte, lte-a, lte+, 5g, 5g+, 5g-uwb, 5g-uc).
+- `erase_sims` - Erase simulator.
+- `reset_sim_location` - Reset sim location.
+- `set_sim_appearance` - Set sim appearance.
+- `set_sim_location` - Set sim location.
+- `sim_statusbar` - Set sim status bar network.
 ### Swift Package Manager (`swift-package`)
 **Purpose**: Swift Package Manager operations for building, testing, running, and managing Swift packages and dependencies. Complete SPM workflow support. (6 tools)
 
-- `swift_package_build` - Builds a Swift Package with swift build
-- `swift_package_clean` - Cleans Swift Package build artifacts and derived data
-- `swift_package_list` - Lists currently running Swift Package processes
-- `swift_package_run` - Runs an executable target from a Swift Package with swift run
-- `swift_package_stop` - Stops a running Swift Package executable started with swift_package_run
-- `swift_package_test` - Runs tests for a Swift Package with swift test
+- `swift_package_build` - swift package target build.
+- `swift_package_clean` - swift package clean.
+- `swift_package_list` - List SwiftPM processes.
+- `swift_package_run` - swift package target run.
+- `swift_package_stop` - Stop SwiftPM run.
+- `swift_package_test` - Run swift package target tests.
 ### System Doctor (`doctor`)
 **Purpose**: Debug tools and system doctor for troubleshooting XcodeBuildMCP server, development environment, and tool availability. (1 tools)
 
-- `doctor` - Provides comprehensive information about the MCP server environment, available dependencies, and configuration status.
-### UI Testing & Automation (`ui-testing`)
+- `doctor` - MCP environment info.
+### UI Automation (`ui-automation`)
 **Purpose**: UI automation and accessibility testing tools for iOS simulators. Perform gestures, interactions, screenshots, and UI analysis for automated testing workflows. (11 tools)
 
-- `button` - Press hardware button on iOS simulator. Supported buttons: apple-pay, home, lock, side-button, siri
-- `describe_ui` - Gets entire view hierarchy with precise frame coordinates (x, y, width, height) for all visible elements. Use this before UI interactions or after layout changes - do NOT guess coordinates from screenshots. Returns JSON tree with frame data for accurate automation. Requires the target process to be running; paused debugger/breakpoints can yield an empty tree.
-- `gesture` - Perform gesture on iOS simulator using preset gestures: scroll-up, scroll-down, scroll-left, scroll-right, swipe-from-left-edge, swipe-from-right-edge, swipe-from-top-edge, swipe-from-bottom-edge
-- `key_press` - Press a single key by keycode on the simulator. Common keycodes: 40=Return, 42=Backspace, 43=Tab, 44=Space, 58-67=F1-F10.
-- `key_sequence` - Press key sequence using HID keycodes on iOS simulator with configurable delay
-- `long_press` - Long press at specific coordinates for given duration (ms). Use describe_ui for precise coordinates (don't guess from screenshots).
-- `screenshot` - Captures screenshot for visual verification. For UI coordinates, use describe_ui instead (don't determine coordinates from screenshots).
-- `swipe` - Swipe from one point to another. Use describe_ui for precise coordinates (don't guess from screenshots). Supports configurable timing.
-- `tap` - Tap at specific coordinates or target elements by accessibility id or label. Use describe_ui to get precise element coordinates prior to using x/y parameters (don't guess from screenshots). Supports optional timing delays.
-- `touch` - Perform touch down/up events at specific coordinates. Use describe_ui for precise coordinates (don't guess from screenshots).
-- `type_text` - Type text (supports US keyboard characters). Use describe_ui to find text field, tap to focus, then type.
+- `button` - Press simulator hardware button.
+- `gesture` - Simulator gesture preset.
+- `key_press` - Press key by keycode.
+- `key_sequence` - Press a sequence of keys by their keycodes.
+- `long_press` - Long press at coords.
+- `screenshot` - Capture screenshot.
+- `snapshot_ui` - Print view hierarchy with precise view coordinates (x, y, width, height) for visible elements.
+- `swipe` - Swipe between points.
+- `tap` - Tap coordinate or element.
+- `touch` - Touch down/up at coords.
+- `type_text` - Type text.
+### workflow-discovery (`workflow-discovery`)
+**Purpose**: workflow-discovery related tools (1 tools)
+
+- `manage_workflows` - 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. Available workflows: ${availableWorkflows}
 
 ## Summary Statistics
 
-- **Total Tools**: 71 canonical tools + 22 re-exports = 93 total
-- **Workflow Groups**: 13
+- **Total Tools**: 72 canonical tools + 22 re-exports = 94 total
+- **Workflow Groups**: 14
 
 ---
 
-*This documentation is automatically generated by `scripts/update-tools-docs.ts` using static analysis. Last updated: 2026-01-08*
+*This documentation is automatically generated by `scripts/update-tools-docs.ts` using static analysis. Last updated: 2026-01-25*

docs/TOOLS.md

@@ -47,7 +47,7 @@ XcodeBuildMCP is a Model Context Protocol (MCP) server that exposes Xcode operat
 4. **Plugin & Resource Loading (Runtime)**
    - At runtime, `loadPlugins()` and `loadResources()` use the generated loaders from the previous step
    - All workflow loaders are executed at startup to register tools
-   - If `XCODEBUILDMCP_ENABLED_WORKFLOWS` is set, only those workflows (plus `session-management`) are registered
+- If `XCODEBUILDMCP_ENABLED_WORKFLOWS` is set, only those workflows (plus `session-management`) are registered; `workflow-discovery` is only auto-included when `XCODEBUILDMCP_EXPERIMENTAL_WORKFLOW_DISCOVERY=true`
 
 5. **Tool Registration**
    - Discovered tools automatically registered with server using pre-generated maps

docs/dev/ARCHITECTURE.md

@@ -260,7 +260,7 @@ fi
    - `test_*` tools - Run test suites
 
 6. **UI Automation Tools** (depend on running apps):
-   - `describe_ui`, `screenshot`, `tap`, etc.
+   - `snapshot_ui`, `screenshot`, `tap`, etc.
 
 **MANDATORY: Record Key Outputs**