feat: Add tool annotations for improved LLM tool understanding

[triepod-ai]

Summary

Adds MCP tool annotations (readOnlyHint, destructiveHint, title) to all 10 tools across 4 registry files to help LLMs better understand tool behavior and make safer decisions about tool execution.

Changes

pkg/kubectl/registry.go (7 tools)

Tool	Annotation	Notes
kubectl_resources	Conditional	readOnlyHint when readOnly=true, destructiveHint when readOnly=false
kubectl_workloads	destructiveHint: true	run, scale, rollout operations
kubectl_metadata	destructiveHint: true	label, annotate, set operations
kubectl_diagnostics	destructiveHint: true	exec can run arbitrary commands
kubectl_cluster	readOnlyHint: true	cluster-info, explain only
kubectl_config	Conditional	readOnlyHint when readOnly=true, destructiveHint when readOnly=false
call_kubectl	Conditional	Based on accessLevel parameter

Other Registries (3 tools)

File	Tool	Annotation	Reason
pkg/helm/registry.go	call_helm	destructiveHint: true	install/upgrade/uninstall
pkg/cilium/registry.go	call_cilium	destructiveHint: true	can modify network policies
pkg/hubble/registry.go	call_hubble	readOnlyHint: true	observability only

Why This Matters

• Annotations provide semantic metadata that helps LLMs understand tool behavior
• LLMs can make better decisions about when to use tools and in what order
• Enables safer tool execution by distinguishing read-only from destructive operations
• MCP clients like Claude Code can auto-approve read-only tools while prompting for destructive ones

Testing

• Project builds successfully (go build ./...)
• All tests pass (go test ./pkg/...)
• Annotation values match actual tool behavior
• Conditional annotations correctly match readOnly/accessLevel parameters

🤖 Generated with Claude Code

[gossion]

thanks for contribution