feat: Add MCP tool annotations to all tools

Add readOnlyHint, destructiveHint, and title annotations to all 66 tools
across 13 workflows to help LLMs better understand tool behavior.

Changes:
- Update PluginMeta interface to include optional annotations field
- Modify tool-registry.ts to pass annotations to SDK registration
- Add annotations to all tool definition files:
  - device (7 tools): build, get_app_path, install, launch, list, stop, test
  - simulator (12 tools): boot, build, build_run, get_app_path, install, launch, launch_logs, list, open, record, stop, test
  - simulator-management (5 tools): erase, reset_location, set_appearance, set_location, statusbar
  - macos (6 tools): build, build_run, get_app_path, launch, stop, test
  - swift-package (6 tools): build, clean, list, run, stop, test
  - logging (4 tools): start_device, start_sim, stop_device, stop_sim
  - ui-testing (11 tools): button, describe_ui, gesture, key_press, key_sequence, long_press, screenshot, swipe, tap, touch, type_text
  - discovery (1 tool): discover_tools
  - doctor (1 tool): doctor
  - project-discovery (5 tools): discover_projs, get_app_bundle_id, get_mac_bundle_id, list_schemes, show_build_settings
  - project-scaffolding (2 tools): scaffold_ios, scaffold_macos
  - session-management (3 tools): clear_defaults, set_defaults, show_defaults
  - utilities (1 tool): clean

Annotation guidelines:
- readOnlyHint: true for tools that only read/query information
- destructiveHint: true for tools that modify state, create/delete files, or execute builds
- title: Human-readable name for the tool

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

Author: 2 people

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),
 };