k8s-mcp-server provides 6 Kubernetes management tools with explicit schema definitions and basic descriptions. However, multiple critical quality gaps prevent this from being a production-ready tool suite. All tools have descriptions and input schemas present in the source code (main.py), but descriptions are inconsistent in depth, parameter descriptions lack constraint details, output schemas are not documented, and error handling provides minimal recovery guidance. The tool suite lacks idempotency guarantees, confirmation steps for destructive operations, and proper input validation messaging. Most tools follow verb_noun naming (list_*, create_*, delete_*), but there are redundant tools (list_kubernetes_pods vs list_pods_default_namespace) that signal unclear decomposition.
Output schemas not documented. Tools return JSON strings without formally declared response structures. LLMs cannot reliably plan downstream tool calls or extract specific fields from responses.
Destructive operations (delete_kubernetes_pod) lack confirmation or dry-run. No tool annotation indicating risk level. Per pattern:confirmation-request, agents should be forced to confirm destructive actions.
Redundant tools: list_kubernetes_pods and list_pods_default_namespace overlap in functionality. Per pattern:tool, each tool should have one clear responsibility. list_pods_default_namespace is a special case of list_kubernetes_pods and forces the LLM to reason about which to call.
list_kubernetes_podslist_pods_default_namespace
Recommendations
Consolidate list_kubernetes_pods and list_pods_default_namespace into a single list_kubernetes_pods tool with namespace parameter defaulting to None (all namespaces) or 'default' as a reasonable common case. Remove the redundant tool.
Document output schemas for all tools. Specify return structures in tool descriptions: 'Returns: {"pods": [{"name": str, "namespace": str, "status": str, "ip": str}], "total": int}' (or actual structure used).
Add input parameter constraints in descriptions: For 'image' → 'Container image name (format: repository/image:tag, e.g., nginx:latest, gcr.io/my-project/app:v1.0)'. For 'replicas' → 'Number of pod replicas (1 - 100, default 1)'. For 'name' → 'Kubernetes-compliant name (lowercase letters, numbers, hyphens; 1 - 63 chars)'.
Add confirmation/dry-run for delete_kubernetes_pod. Either require an explicit 'confirmed=true' parameter, or change the tool description to: 'DESTRUCTIVE: Permanently deletes a Pod. This action cannot be undone. Returns success only if pod existed.' Consider a separate dry_run_delete_kubernetes_pod tool.
Annotate tools with risk levels in descriptions. Use markers like '[READ-ONLY]', '[WRITE]', '[DESTRUCTIVE]' at the start of descriptions, or implement tool annotations (readOnlyHint, destructiveHint) if the framework supports it.
Improve error responses with actionable recovery: Instead of generic exception messages, return: 'Pod "my-pod" creation failed: namespace "custom" not found. Valid namespaces: default, kube-system, kube-public. Call create_kubernetes_namespace("custom") first.' This guides the LLM to self-correct.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). Tools lack structured risk metadata that agents could use to reason about side effects and safety.
Input parameter descriptions lack constraint details. Parameters like 'image', 'name', 'replicas' have no format guidance, range limits, or validation rules. Per pattern:constrained-input, constraints should be explicit in descriptions.
Error handling provides minimal recovery guidance. Errors return raw ApiException details or generic messages. Per pattern:recovery-guide, error responses must tell the LLM what to do next.
No idempotency guarantees documented. Tools do not explicitly state whether repeated calls with identical inputs are safe or risk duplicate side effects. create_kubernetes_namespace handles 409 (duplicate), but this is not formally declared.
Document idempotency guarantees. State in tool descriptions: 'Idempotent: Multiple calls with same parameters are safe.' or 'Non-idempotent: Each call creates a new resource; duplicates are possible.' Add logic to detect duplicates and return the existing resource ID instead of failing.
Add batch variants for efficiency. E.g., create_kubernetes_pods (accepts array of pod specs) to reduce multi-turn round-trips when agents create many pods.
Add discovery tools: list_kubernetes_namespaces, describe_kubernetes_pod (for detailed status before operations), list_kubernetes_deployments. These enable agents to validate preconditions before destructive operations.
Validate and sanitize all inputs server-side. Enforce Kubernetes naming rules (DNS-1123), image name format, and numeric ranges. Return clear validation errors: 'Invalid pod name: "MyPod". Must be lowercase letters, numbers, and hyphens (1 - 63 chars).' instead of API exceptions.