feat: Add MCP tool annotations for LLM guidance (#279)

Add title and hint annotations to all 11 internal tools to help LLMs
understand tool behavior and make safer decisions about tool usage.

Tool Annotations Added:

**Read-Only Tools (7 tools):**
- az_monitoring - Azure Monitor metrics/health/logs
- az_network_resources - VNet/NSG/subnet info
- get_aks_vmss_info - VMSS configuration
- list_detectors - List AKS diagnostic detectors
- run_detector - Execute AKS detector analysis
- run_detectors_by_category - Run detector categories
- az_advisor_recommendation - Azure Advisor recommendations

**Destructive Tools (4 tools):**
- az_aks_operations - Create/delete/scale AKS clusters
- az_fleet - Multi-cluster fleet management
- az_compute_operations - VM/VMSS operations
- inspektor_gadget_observability - Deploy/undeploy eBPF monitoring

Uses mark3labs/mcp-go annotation functions:
- WithTitleAnnotation() - Human-readable tool names
- WithReadOnlyHintAnnotation(true) - Safe read operations
- WithDestructiveHintAnnotation(true) - State-modifying operations

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

Co-authored-by: triepod-ai <noreply@github.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: 3 people

internal/components/advisor/registry.go

@@ -11,6 +11,8 @@ func RegisterAdvisorRecommendationTool() mcp.Tool {
 	return mcp.NewTool(
 		"az_advisor_recommendation",
 		mcp.WithDescription("Retrieve and manage Azure Advisor recommendations for AKS clusters"),
+		mcp.WithTitleAnnotation("Azure Advisor Recommendations"),
+		mcp.WithReadOnlyHintAnnotation(true),
 		mcp.WithString("operation",
 			mcp.Description("Operation to perform: list or report"),
 			mcp.Required(),

internal/components/azaks/registry.go

@@ -102,6 +102,8 @@ func RegisterAzAksOperations(cfg *config.ConfigData) mcp.Tool {
 
 	return mcp.NewTool("az_aks_operations",
 		mcp.WithDescription(description),
+		mcp.WithTitleAnnotation("AKS Operations"),
+		mcp.WithDestructiveHintAnnotation(true),
 		mcp.WithString("operation",
 			mcp.Required(),
 			mcp.Description("The operation to perform"),

internal/components/compute/azcommands.go

@@ -84,6 +84,8 @@ func RegisterAzComputeOperations(cfg *config.ConfigData) mcp.Tool {
 
 	return mcp.NewTool("az_compute_operations",
 		mcp.WithDescription(description),
+		mcp.WithTitleAnnotation("Azure Compute Operations"),
+		mcp.WithDestructiveHintAnnotation(true),
 		mcp.WithString("operation",
 			mcp.Required(),
 			mcp.Description("Operation to perform. Common operations: list, show, start, stop, restart, deallocate, scale, etc."),

internal/components/compute/registry.go

@@ -11,6 +11,8 @@ func RegisterAKSVMSSInfoTool() mcp.Tool {
 	return mcp.NewTool(
 		"get_aks_vmss_info",
 		mcp.WithDescription("Get detailed VMSS configuration for a specific node pool or all node pools in the AKS cluster (provides low-level VMSS settings not available in az aks nodepool show). Leave node_pool_name empty to get info for all node pools."),
+		mcp.WithTitleAnnotation("Get AKS VMSS Info"),
+		mcp.WithReadOnlyHintAnnotation(true),
 		mcp.WithString("subscription_id",
 			mcp.Description("Azure Subscription ID"),
 			mcp.Required(),

internal/components/detectors/registry.go

@@ -11,6 +11,8 @@ func RegisterListDetectorsTool() mcp.Tool {
 	return mcp.NewTool(
 		"list_detectors",
 		mcp.WithDescription("List all available AKS cluster detectors"),
+		mcp.WithTitleAnnotation("List Detectors"),
+		mcp.WithReadOnlyHintAnnotation(true),
 		mcp.WithString("cluster_resource_id",
 			mcp.Description("AKS cluster resource ID"),
 			mcp.Required(),
@@ -23,6 +25,8 @@ func RegisterRunDetectorTool() mcp.Tool {
 	return mcp.NewTool(
 		"run_detector",
 		mcp.WithDescription("Run a specific AKS detector"),
+		mcp.WithTitleAnnotation("Run Detector"),
+		mcp.WithReadOnlyHintAnnotation(true),
 		mcp.WithString("cluster_resource_id",
 			mcp.Description("AKS cluster resource ID"),
 			mcp.Required(),
@@ -47,6 +51,8 @@ func RegisterRunDetectorsByCategoryTool() mcp.Tool {
 	return mcp.NewTool(
 		"run_detectors_by_category",
 		mcp.WithDescription("Run all detectors in a specific category"),
+		mcp.WithTitleAnnotation("Run Detectors By Category"),
+		mcp.WithReadOnlyHintAnnotation(true),
 		mcp.WithString("cluster_resource_id",
 			mcp.Description("AKS cluster resource ID"),
 			mcp.Required(),

internal/components/fleet/registry.go

@@ -33,6 +33,8 @@ Examples:
 
 	return mcp.NewTool("az_fleet",
 		mcp.WithDescription(description),
+		mcp.WithTitleAnnotation("Azure Fleet"),
+		mcp.WithDestructiveHintAnnotation(true),
 		mcp.WithString("operation",
 			mcp.Required(),
 			mcp.Description("The operation to perform. Valid values: list, show, create, update, delete, start, stop, get-credentials"),

internal/components/inspektorgadget/registry.go

@@ -28,6 +28,8 @@ func RegisterInspektorGadgetTool() mcp.Tool {
 			"namespace, pod, container, selector,"+strings.Join(getGadgetParamsKeys(), ", ")+". "+
 			"Example: "+
 			"{'action': 'run', 'filter_params': {'namespace': 'default', 'selector': 'app=myapp', 'observe_dns.unsuccessful_only': true}}"),
+		mcp.WithTitleAnnotation("Inspektor Gadget Observability"),
+		mcp.WithDestructiveHintAnnotation(true),
 		mcp.WithString("action",
 			mcp.Required(),
 			mcp.Description("Action to perform on the gadget: "+

internal/components/monitor/registry.go

@@ -100,6 +100,8 @@ control_plane_logs:
 
 	return mcp.NewTool("az_monitoring",
 		mcp.WithDescription(description),
+		mcp.WithTitleAnnotation("Azure Monitoring"),
+		mcp.WithReadOnlyHintAnnotation(true),
 		mcp.WithString("operation",
 			mcp.Required(),
 			mcp.Description("The monitoring operation to perform: 'metrics' (CPU/memory/network), 'resource_health' (cluster availability), 'app_insights' (telemetry analysis), 'diagnostics' (logging config), 'control_plane_logs' (Kubernetes logs like kube-apiserver, kube-audit, guard, etc.)"),

internal/components/network/registry.go

@@ -39,6 +39,8 @@ Examples:
 
 	return mcp.NewTool("az_network_resources",
 		mcp.WithDescription(description),
+		mcp.WithTitleAnnotation("Azure Network Resources"),
+		mcp.WithReadOnlyHintAnnotation(true),
 		mcp.WithString("resource_type",
 			mcp.Required(),
 			mcp.Description("The type of network resource to query"),