fix(simulator): Prefer build_run_sim for run intent

Align agent guidance and simulator discovery hints so run or launch intent\ndefaults to build_run_sim while keeping build_sim as compile-only.\n\nThis avoids the common redundant sequence of running build_sim and then\nbuild_run_sim, which double-builds without adding value.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: cameroncooke

docs/TOOLS-CLI.md

@@ -37,8 +37,8 @@ XcodeBuildMCP provides 73 canonical tools organized into 13 workflow groups.
 **Purpose**: Complete iOS development workflow for both .xcodeproj and .xcworkspace files targeting simulators. (21 tools)
 
 - `boot` - Defined in Simulator Management workflow.
-- `build` - Build for iOS sim.
-- `build-and-run` - Build and run iOS sim.
+- `build` - Build for iOS sim (compile-only, no launch).
+- `build-and-run` - Build and run iOS sim (preferred for run/launch intent).
 - `clean` - Defined in iOS Device Development workflow.
 - `discover-projects` - Defined in iOS Device Development workflow.
 - `get-app-bundle-id` - Defined in iOS Device Development workflow.
@@ -189,4 +189,4 @@ XcodeBuildMCP provides 73 canonical tools organized into 13 workflow groups.
 
 ---
 
-*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-16T21:51:58.527Z UTC*
+*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-16T21:53:02.251Z UTC*

docs/TOOLS.md

@@ -35,8 +35,8 @@ This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP prov
 **Purpose**: Complete iOS development workflow for both .xcodeproj and .xcworkspace files targeting simulators. (21 tools)
 
 - `boot_sim` - Defined in Simulator Management workflow.
-- `build_run_sim` - Build and run iOS sim.
-- `build_sim` - Build for iOS sim.
+- `build_run_sim` - Build and run iOS sim (preferred for run/launch intent).
+- `build_sim` - Build for iOS sim (compile-only, no launch).
 - `clean` - Defined in iOS Device Development workflow.
 - `discover_projs` - Defined in iOS Device Development workflow.
 - `get_app_bundle_id` - Defined in iOS Device Development workflow.
@@ -204,4 +204,4 @@ This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP prov
 
 ---
 
-*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-16T21:51:58.527Z UTC*
+*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-16T21:53:02.251Z UTC*

manifests/tools/build_run_sim.yaml

@@ -3,7 +3,7 @@ module: mcp/tools/simulator/build_run_sim
 names:
   mcp: build_run_sim
   cli: build-and-run
-description: Build and run iOS sim.
+description: Build and run iOS sim (preferred for run/launch intent).
 predicates:
   - hideWhenXcodeAgentMode
 annotations:

manifests/tools/build_sim.yaml

@@ -3,7 +3,7 @@ module: mcp/tools/simulator/build_sim
 names:
   mcp: build_sim
   cli: build
-description: Build for iOS sim.
+description: Build for iOS sim (compile-only, no launch).
 predicates:
   - hideWhenXcodeAgentMode
 annotations:

skills/xcodebuildmcp-cli/SKILL.md

@@ -33,6 +33,9 @@ Notes:
 
 ### Build And Run On Simulator
 
+If your intent is to run the app in Simulator, use `build-and-run` directly. It already performs the build step.
+Do not run `build` first unless the user explicitly requests both commands.
+
 1. List simulators and pick a device name or UDID.
 2. Build and run.
 
@@ -50,7 +53,8 @@ xcodebuildmcp simulator build-and-run --scheme MyApp --project-path ./MyApp.xcod
 
 ### Build only
 
-When you only need to check that there are no build errors, you can build without running the app.
+Use this only when you want compile feedback and do not want to launch the app.
+For run/launch intent, use `build-and-run` instead of chaining `build` and `build-and-run`.
 
 ```bash
 xcodebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj --simulator-name "iPhone 17 Pro"

skills/xcodebuildmcp/SKILL.md

@@ -9,6 +9,13 @@ Prefer XcodeBuildMCP over raw `xcodebuild`, `xcrun`, or `simctl`.
 
 If a capability is missing, assume your tool list may be hiding tools (search/progressive disclosure) or not loading tool schemas yet. Use your tool-search or “load tools” mechanism. If you still can’t find the tools, ask the user to enable them in the MCP client's configuration.
 
+## Default Tool Choice (Simulator)
+
+- If intent includes run/launch/open in Simulator, use `build_run_sim` as the default.
+- If intent is compile-only feedback (no launch), use `build_sim`.
+- Do not call `build_sim` and then `build_run_sim` in sequence unless the user explicitly asks for both.
+- If the app is already built and you need launch only without rebuilding, use `install_app_sim` + `launch_app_sim` (or `launch_app_logs_sim`).
+
 ## Tools (exact names + official descriptions)
 
 ### Session defaults

src/mcp/tools/project-discovery/__tests__/list_schemes.test.ts

@@ -79,20 +79,30 @@ describe('list_schemes plugin', () => {
             priority: 1,
           },
           {
-            tool: 'build_sim',
-            label: 'Build for iOS Simulator',
+            tool: 'build_run_sim',
+            label: 'Build and run on iOS Simulator (default for run intent)',
             params: {
               projectPath: '/path/to/MyProject.xcodeproj',
               scheme: 'MyProject',
               simulatorName: 'iPhone 16',
             },
             priority: 2,
           },
+          {
+            tool: 'build_sim',
+            label: 'Build for iOS Simulator (compile-only)',
+            params: {
+              projectPath: '/path/to/MyProject.xcodeproj',
+              scheme: 'MyProject',
+              simulatorName: 'iPhone 16',
+            },
+            priority: 3,
+          },
           {
             tool: 'show_build_settings',
             label: 'Show build settings',
             params: { projectPath: '/path/to/MyProject.xcodeproj', scheme: 'MyProject' },
-            priority: 3,
+            priority: 4,
           },
         ],
         isError: false,
@@ -317,20 +327,30 @@ describe('list_schemes plugin', () => {
             priority: 1,
           },
           {
-            tool: 'build_sim',
-            label: 'Build for iOS Simulator',
+            tool: 'build_run_sim',
+            label: 'Build and run on iOS Simulator (default for run intent)',
             params: {
               workspacePath: '/path/to/MyProject.xcworkspace',
               scheme: 'MyApp',
               simulatorName: 'iPhone 16',
             },
             priority: 2,
           },
+          {
+            tool: 'build_sim',
+            label: 'Build for iOS Simulator (compile-only)',
+            params: {
+              workspacePath: '/path/to/MyProject.xcworkspace',
+              scheme: 'MyApp',
+              simulatorName: 'iPhone 16',
+            },
+            priority: 3,
+          },
           {
             tool: 'show_build_settings',
             label: 'Show build settings',
             params: { workspacePath: '/path/to/MyProject.xcworkspace', scheme: 'MyApp' },
-            priority: 3,
+            priority: 4,
           },
         ],
         isError: false,

src/mcp/tools/project-discovery/list_schemes.ts

@@ -99,20 +99,30 @@ export async function listSchemesLogic(
           priority: 1,
         },
         {
-          tool: 'build_sim',
-          label: 'Build for iOS Simulator',
+          tool: 'build_run_sim',
+          label: 'Build and run on iOS Simulator (default for run intent)',
           params: {
             [`${projectOrWorkspace}Path`]: path!,
             scheme: firstScheme,
             simulatorName: 'iPhone 16',
           },
           priority: 2,
         },
+        {
+          tool: 'build_sim',
+          label: 'Build for iOS Simulator (compile-only)',
+          params: {
+            [`${projectOrWorkspace}Path`]: path!,
+            scheme: firstScheme,
+            simulatorName: 'iPhone 16',
+          },
+          priority: 3,
+        },
         {
           tool: 'show_build_settings',
           label: 'Show build settings',
           params: { [`${projectOrWorkspace}Path`]: path!, scheme: firstScheme },
-          priority: 3,
+          priority: 4,
         },
       );