feat: Add MCP tool annotations to all tools

src/core/plugin-types.ts

@@ -1,10 +1,12 @@
 import { z } from 'zod';
+import { ToolAnnotations } from '@camsoft/mcp-sdk/types.js';
 import { ToolResponse } from '../types/common.ts';
 
 export interface PluginMeta {
   readonly name: string; // Verb used by MCP
   readonly schema: Record<string, z.ZodTypeAny>; // Zod validation schema (object schema)
   readonly description?: string; // One-liner shown in help
+  readonly annotations?: ToolAnnotations; // MCP tool annotations for LLM behavior hints
   handler(params: Record<string, unknown>): Promise<ToolResponse>;
 }
 

src/mcp/tools/device/build_device.ts

@@ -78,6 +78,10 @@ export default {
     sessionAware: publicSchemaObject,
     legacy: baseSchemaObject,
   }),
+  annotations: {
+    title: 'Build Device',
+    destructiveHint: true,
+  },
   handler: createSessionAwareTool<BuildDeviceParams>({
     internalSchema: buildDeviceSchema as unknown as z.ZodType<BuildDeviceParams>,
     logicFunction: buildDeviceLogic,

src/mcp/tools/device/get_device_app_path.ts

@@ -161,6 +161,10 @@ export default {
     sessionAware: publicSchemaObject,
     legacy: baseSchemaObject,
   }),
+  annotations: {
+    title: 'Get Device App Path',
+    readOnlyHint: true,
+  },
   handler: createSessionAwareTool<GetDeviceAppPathParams>({
     internalSchema: getDeviceAppPathSchema as unknown as z.ZodType<GetDeviceAppPathParams>,
     logicFunction: get_device_app_pathLogic,

src/mcp/tools/device/install_app_device.ts

@@ -92,6 +92,10 @@ export default {
     sessionAware: publicSchemaObject,
     legacy: installAppDeviceSchema,
   }),
+  annotations: {
+    title: 'Install App Device',
+    destructiveHint: true,
+  },
   handler: createSessionAwareTool<InstallAppDeviceParams>({
     internalSchema: installAppDeviceSchema as unknown as z.ZodType<InstallAppDeviceParams>,
     logicFunction: install_app_deviceLogic,

src/mcp/tools/device/launch_app_device.ts

@@ -151,6 +151,10 @@ export default {
     sessionAware: publicSchemaObject,
     legacy: launchAppDeviceSchema,
   }),
+  annotations: {
+    title: 'Launch App Device',
+    destructiveHint: true,
+  },
   handler: createSessionAwareTool<LaunchAppDeviceParams>({
     internalSchema: launchAppDeviceSchema as unknown as z.ZodType<LaunchAppDeviceParams>,
     logicFunction: launch_app_deviceLogic,

src/mcp/tools/device/list_devices.ts

@@ -431,5 +431,9 @@ export default {
   description:
     '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.',
   schema: listDevicesSchema.shape, // MCP SDK compatibility
+  annotations: {
+    title: 'List Devices',
+    readOnlyHint: true,
+  },
   handler: createTypedTool(listDevicesSchema, list_devicesLogic, getDefaultCommandExecutor),
 };

src/mcp/tools/device/stop_app_device.ts

@@ -94,6 +94,10 @@ export default {
     sessionAware: publicSchemaObject,
     legacy: stopAppDeviceSchema,
   }),
+  annotations: {
+    title: 'Stop App Device',
+    destructiveHint: true,
+  },
   handler: createSessionAwareTool<StopAppDeviceParams>({
     internalSchema: stopAppDeviceSchema as unknown as z.ZodType<StopAppDeviceParams>,
     logicFunction: stop_app_deviceLogic,

src/mcp/tools/device/test_device.ts

@@ -291,6 +291,10 @@ export default {
     sessionAware: publicSchemaObject,
     legacy: baseSchemaObject,
   }),
+  annotations: {
+    title: 'Test Device',
+    destructiveHint: true,
+  },
   handler: createSessionAwareTool<TestDeviceParams>({
     internalSchema: testDeviceSchema as unknown as z.ZodType<TestDeviceParams>,
     logicFunction: (params: TestDeviceParams, executor: CommandExecutor) =>

src/mcp/tools/discovery/discover_tools.ts

@@ -384,6 +384,10 @@ export default {
   description:
     'Analyzes a natural language task description and enables the most relevant development workflow. Prioritizes project/workspace workflows (simulator/device/macOS) and also supports task-based workflows (simulator-management, logging) and Swift packages.',
   schema: discoverToolsSchema.shape, // MCP SDK compatibility
+  annotations: {
+    title: 'Discover Tools',
+    readOnlyHint: true,
+  },
   handler: createTypedTool(
     discoverToolsSchema,
     (params: DiscoverToolsParams, executor) => {

src/mcp/tools/doctor/doctor.ts

@@ -273,6 +273,10 @@ export default {
   description:
     'Provides comprehensive information about the MCP server environment, available dependencies, and configuration status.',
   schema: doctorSchema.shape, // MCP SDK compatibility
+  annotations: {
+    title: 'Doctor',
+    readOnlyHint: true,
+  },
   handler: createTypedTool(doctorSchema, doctorMcpHandler, getDefaultCommandExecutor),
 };
 

src/mcp/tools/logging/start_device_log_cap.ts

@@ -688,6 +688,10 @@ export default {
     sessionAware: publicSchemaObject,
     legacy: startDeviceLogCapSchema,
   }),
+  annotations: {
+    title: 'Start Device Log Capture',
+    destructiveHint: true,
+  },
   handler: createSessionAwareTool<StartDeviceLogCapParams>({
     internalSchema: startDeviceLogCapSchema as unknown as z.ZodType<StartDeviceLogCapParams>,
     logicFunction: start_device_log_capLogic,

src/mcp/tools/logging/start_sim_log_cap.ts

@@ -68,6 +68,10 @@ export default {
     sessionAware: publicSchemaObject,
     legacy: startSimLogCapSchema,
   }),
+  annotations: {
+    title: 'Start Simulator Log Capture',
+    destructiveHint: true,
+  },
   handler: createSessionAwareTool<StartSimLogCapParams>({
     internalSchema: startSimLogCapSchema as unknown as z.ZodType<StartSimLogCapParams>,
     logicFunction: start_sim_log_capLogic,

src/mcp/tools/logging/stop_device_log_cap.ts

@@ -312,6 +312,10 @@ export default {
   name: 'stop_device_log_cap',
   description: 'Stops an active Apple device log capture session and returns the captured logs.',
   schema: stopDeviceLogCapSchema.shape, // MCP SDK compatibility
+  annotations: {
+    title: 'Stop Device Log Capture',
+    destructiveHint: true,
+  },
   handler: createTypedTool(
     stopDeviceLogCapSchema,
     (params: StopDeviceLogCapParams) => {

src/mcp/tools/logging/stop_sim_log_cap.ts

@@ -44,5 +44,9 @@ export default {
   name: 'stop_sim_log_cap',
   description: 'Stops an active simulator log capture session and returns the captured logs.',
   schema: stopSimLogCapSchema.shape, // MCP SDK compatibility
+  annotations: {
+    title: 'Stop Simulator Log Capture',
+    destructiveHint: true,
+  },
   handler: createTypedTool(stopSimLogCapSchema, stop_sim_log_capLogic, getDefaultCommandExecutor),
 };

src/mcp/tools/macos/build_macos.ts

@@ -105,6 +105,10 @@ export default {
     sessionAware: publicSchemaObject,
     legacy: baseSchemaObject,
   }),
+  annotations: {
+    title: 'Build macOS',
+    destructiveHint: true,
+  },
   handler: createSessionAwareTool<BuildMacOSParams>({
     internalSchema: buildMacOSSchema as unknown as z.ZodType<BuildMacOSParams>,
     logicFunction: buildMacOSLogic,

src/mcp/tools/macos/build_run_macos.ts

@@ -223,6 +223,10 @@ export default {
     sessionAware: publicSchemaObject,
     legacy: baseSchemaObject,
   }),
+  annotations: {
+    title: 'Build Run macOS',
+    destructiveHint: true,
+  },
   handler: createSessionAwareTool<BuildRunMacOSParams>({
     internalSchema: buildRunMacOSSchema as unknown as z.ZodType<BuildRunMacOSParams>,
     logicFunction: buildRunMacOSLogic,

src/mcp/tools/macos/get_mac_app_path.ts

@@ -195,6 +195,10 @@ export default {
     sessionAware: publicSchemaObject,
     legacy: baseSchemaObject,
   }),
+  annotations: {
+    title: 'Get macOS App Path',
+    readOnlyHint: true,
+  },
   handler: createSessionAwareTool<GetMacosAppPathParams>({
     internalSchema: getMacosAppPathSchema as unknown as z.ZodType<GetMacosAppPathParams>,
     logicFunction: get_mac_app_pathLogic,

src/mcp/tools/macos/launch_mac_app.ts

@@ -79,5 +79,9 @@ export default {
   description:
     "Launches a macOS application. IMPORTANT: You MUST provide the appPath parameter. Example: launch_mac_app({ appPath: '/path/to/your/app.app' }) Note: In some environments, this tool may be prefixed as mcp0_launch_macos_app.",
   schema: launchMacAppSchema.shape, // MCP SDK compatibility
+  annotations: {
+    title: 'Launch macOS App',
+    destructiveHint: true,
+  },
   handler: createTypedTool(launchMacAppSchema, launch_mac_appLogic, getDefaultCommandExecutor),
 };

src/mcp/tools/macos/stop_mac_app.ts

@@ -82,5 +82,9 @@ export default {
   name: 'stop_mac_app',
   description: 'Stops a running macOS application. Can stop by app name or process ID.',
   schema: stopMacAppSchema.shape, // MCP SDK compatibility
+  annotations: {
+    title: 'Stop macOS App',
+    destructiveHint: true,
+  },
   handler: createTypedTool(stopMacAppSchema, stop_mac_appLogic, getDefaultCommandExecutor),
 };

src/mcp/tools/macos/test_macos.ts

@@ -333,6 +333,10 @@ export default {
     sessionAware: publicSchemaObject,
     legacy: baseSchemaObject,
   }),
+  annotations: {
+    title: 'Test macOS',
+    destructiveHint: true,
+  },
   handler: createSessionAwareTool<TestMacosParams>({
     internalSchema: testMacosSchema as unknown as z.ZodType<TestMacosParams>,
     logicFunction: (params, executor) =>

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

@@ -274,6 +274,10 @@ export default {
   description:
     'Scans a directory (defaults to workspace root) to find Xcode project (.xcodeproj) and workspace (.xcworkspace) files.',
   schema: discoverProjsSchema.shape, // MCP SDK compatibility
+  annotations: {
+    title: 'Discover Projects',
+    readOnlyHint: true,
+  },
   handler: createTypedTool(
     discoverProjsSchema,
     (params: DiscoverProjsParams) => {

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

@@ -128,6 +128,10 @@ export default {
   description:
     "Extracts the bundle identifier from an app bundle (.app) for any Apple platform (iOS, iPadOS, watchOS, tvOS, visionOS). IMPORTANT: You MUST provide the appPath parameter. Example: get_app_bundle_id({ appPath: '/path/to/your/app.app' })",
   schema: getAppBundleIdSchema.shape, // MCP SDK compatibility
+  annotations: {
+    title: 'Get App Bundle ID',
+    readOnlyHint: true,
+  },
   handler: createTypedTool(
     getAppBundleIdSchema,
     (params: GetAppBundleIdParams) =>

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

@@ -125,6 +125,10 @@ export default {
   description:
     "Extracts the bundle identifier from a macOS app bundle (.app). IMPORTANT: You MUST provide the appPath parameter. Example: get_mac_bundle_id({ appPath: '/path/to/your/app.app' }) Note: In some environments, this tool may be prefixed as mcp0_get_macos_bundle_id.",
   schema: getMacBundleIdSchema.shape, // MCP SDK compatibility
+  annotations: {
+    title: 'Get Mac Bundle ID',
+    readOnlyHint: true,
+  },
   handler: createTypedTool(
     getMacBundleIdSchema,
     (params: GetMacBundleIdParams) =>

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

@@ -124,6 +124,10 @@ export default {
     sessionAware: publicSchemaObject,
     legacy: baseSchemaObject,
   }),
+  annotations: {
+    title: 'List Schemes',
+    readOnlyHint: true,
+  },
   handler: createSessionAwareTool<ListSchemesParams>({
     internalSchema: listSchemesSchema as unknown as z.ZodType<ListSchemesParams>,
     logicFunction: listSchemesLogic,

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

@@ -118,6 +118,10 @@ export default {
     sessionAware: publicSchemaObject,
     legacy: baseSchemaObject,
   }),
+  annotations: {
+    title: 'Show Build Settings',
+    readOnlyHint: true,
+  },
   handler: createSessionAwareTool<ShowBuildSettingsParams>({
     internalSchema: showBuildSettingsSchema as unknown as z.ZodType<ShowBuildSettingsParams>,
     logicFunction: showBuildSettingsLogic,

src/mcp/tools/project-scaffolding/scaffold_ios_project.ts

@@ -501,6 +501,10 @@ export default {
   description:
     'Scaffold a new iOS project from templates. Creates a modern Xcode project with workspace structure, SPM package for features, and proper iOS configuration.',
   schema: ScaffoldiOSProjectSchema.shape,
+  annotations: {
+    title: 'Scaffold iOS Project',
+    destructiveHint: true,
+  },
   async handler(args: Record<string, unknown>): Promise<ToolResponse> {
     const params = ScaffoldiOSProjectSchema.parse(args);
     return scaffold_ios_projectLogic(

src/mcp/tools/project-scaffolding/scaffold_macos_project.ts

@@ -407,6 +407,10 @@ export default {
   description:
     'Scaffold a new macOS project from templates. Creates a modern Xcode project with workspace structure, SPM package for features, and proper macOS configuration.',
   schema: ScaffoldmacOSProjectSchema.shape,
+  annotations: {
+    title: 'Scaffold macOS Project',
+    destructiveHint: true,
+  },
   async handler(args: Record<string, unknown>): Promise<ToolResponse> {
     // Validate the arguments against the schema before processing
     const validatedArgs = ScaffoldmacOSProjectSchema.parse(args);

src/mcp/tools/session-management/session_clear_defaults.ts

@@ -33,5 +33,9 @@ export default {
   name: 'session-clear-defaults',
   description: 'Clear selected or all session defaults.',
   schema: schemaObj.shape,
+  annotations: {
+    title: 'Clear Session Defaults',
+    destructiveHint: true,
+  },
   handler: createTypedTool(schemaObj, sessionClearDefaultsLogic, getDefaultCommandExecutor),
 };

src/mcp/tools/session-management/session_set_defaults.ts

@@ -57,5 +57,9 @@ export default {
   description:
     '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.',
   schema: baseSchema.shape,
+  annotations: {
+    title: 'Set Session Defaults',
+    destructiveHint: true,
+  },
   handler: createTypedTool(schemaObj, sessionSetDefaultsLogic, getDefaultCommandExecutor),
 };

src/mcp/tools/session-management/session_show_defaults.ts

@@ -5,6 +5,10 @@ export default {
   name: 'session-show-defaults',
   description: 'Show current session defaults.',
   schema: {},
+  annotations: {
+    title: 'Show Session Defaults',
+    readOnlyHint: true,
+  },
   handler: async (): Promise<ToolResponse> => {
     const current = sessionStore.getAll();
     return { content: [{ type: 'text', text: JSON.stringify(current, null, 2) }], isError: false };

src/mcp/tools/simulator-management/erase_sims.ts

@@ -90,6 +90,10 @@ export default {
     sessionAware: publicSchemaObject,
     legacy: eraseSimsSchema,
   }),
+  annotations: {
+    title: 'Erase Simulators',
+    destructiveHint: true,
+  },
   handler: createSessionAwareTool<EraseSimsParams>({
     internalSchema: eraseSimsSchema as unknown as z.ZodType<EraseSimsParams>,
     logicFunction: erase_simsLogic,

src/mcp/tools/simulator-management/reset_sim_location.ts

@@ -99,6 +99,10 @@ export default {
     sessionAware: publicSchemaObject,
     legacy: resetSimulatorLocationSchema,
   }),
+  annotations: {
+    title: 'Reset Simulator Location',
+    destructiveHint: true,
+  },
   handler: createSessionAwareTool<ResetSimulatorLocationParams>({
     internalSchema:
       resetSimulatorLocationSchema as unknown as z.ZodType<ResetSimulatorLocationParams>,

src/mcp/tools/simulator-management/set_sim_appearance.ts

@@ -99,6 +99,10 @@ export default {
     sessionAware: publicSchemaObject,
     legacy: setSimAppearanceSchema,
   }),
+  annotations: {
+    title: 'Set Simulator Appearance',
+    destructiveHint: true,
+  },
   handler: createSessionAwareTool<SetSimAppearanceParams>({
     internalSchema: setSimAppearanceSchema as unknown as z.ZodType<SetSimAppearanceParams>,
     logicFunction: set_sim_appearanceLogic,

src/mcp/tools/simulator-management/set_sim_location.ts

@@ -127,6 +127,10 @@ export default {
     sessionAware: publicSchemaObject,
     legacy: setSimulatorLocationSchema,
   }),
+  annotations: {
+    title: 'Set Simulator Location',
+    destructiveHint: true,
+  },
   handler: createSessionAwareTool<SetSimulatorLocationParams>({
     internalSchema: setSimulatorLocationSchema as unknown as z.ZodType<SetSimulatorLocationParams>,
     logicFunction: set_sim_locationLogic,

src/mcp/tools/simulator-management/sim_statusbar.ts

@@ -101,6 +101,10 @@ export default {
     sessionAware: publicSchemaObject,
     legacy: simStatusbarSchema,
   }), // MCP SDK compatibility
+  annotations: {
+    title: 'Simulator Statusbar',
+    destructiveHint: true,
+  },
   handler: createSessionAwareTool<SimStatusbarParams>({
     internalSchema: simStatusbarSchema as unknown as z.ZodType<SimStatusbarParams>,
     logicFunction: sim_statusbarLogic,

src/mcp/tools/simulator/boot_sim.ts

@@ -75,6 +75,10 @@ export default {
     sessionAware: publicSchemaObject,
     legacy: bootSimSchemaObject,
   }),
+  annotations: {
+    title: 'Boot Simulator',
+    destructiveHint: true,
+  },
   handler: createSessionAwareTool<BootSimParams>({
     internalSchema: bootSimSchemaObject,
     logicFunction: boot_simLogic,