Spring MCP Kubernetes server provides 3 tools with minimal definition quality. All tools have descriptions but they are extremely terse (17-56 chars, below the 34-char p10 baseline for tool descriptions). Input schemas are present with basic type declarations but critically lack depth: parameters have minimal descriptions (some are just 1-2 phrases), no enums where they should exist (e.g., 'namespace' could be constrained), no validation rules stated. Output schemas are not documented at all, critical for an agent to understand what these tools return. Error handling is absent, no guidance on what happens on permission denials, network failures, or Kubernetes API errors. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite two tools being mutually exclusive operations. Tool composition is poor: get_namespace_pods and the deployment tools operate on disjoint concepts (pods vs deployments) with no cross-linking information. Tool names are acceptable (verb_noun pattern) but descriptions do not explain WHEN to use each tool or WHAT to expect back.
Tools (3)
deploy_servicewriteauthsource verified39/100
Deploy or update a service in a specific namespace
Output schemas are completely undocumented. No tool specifies what fields are returned, their types, or their meaning. An LLM cannot reason about downstream tool chaining or data extraction.
Tool descriptions are far too brief (17-56 chars vs 194-char baseline mean). 'Get all pods in a specific namespace' does not explain: What if the namespace doesn't exist? What fields are in each pod object? Should this be called first before deploying? LLMs cannot infer these details.
Parameter descriptions are minimal or absent. 'The Kubernetes namespace to query' is the only description, repeated identically across tools. Parameters lack context: What format? What characters are allowed? Is 'default' a valid namespace? Are there restricted namespaces?
get_namespace_podsdeploy_serviceundeploy_service
Recommendations
Expand tool descriptions to 100-200 characters explaining: (1) What the tool does, (2) When to call it relative to other tools, (3) What it returns and its typical structure, (4) Any prerequisites or permission requirements. Example for get_namespace_pods: 'Retrieve all running pods in a Kubernetes namespace. Returns pod name, namespace, status (Running/Pending/Failed), and ready replicas. Call this to verify deployments are healthy or to troubleshoot pod issues. Requires read:pods permission.'
Document output schemas for all tools. Specify the JSON structure returned: for get_namespace_pods, return {pods: [{name, namespace, status, ready_replicas, created_at, image, restart_count}], total_count}. For deploy_service and undeploy_service, return {deployment_name, namespace, previous_replicas, current_replicas, status, message}.
Add parameter descriptions that specify format and constraints. For 'namespace': 'Kubernetes namespace name (1-63 chars, lowercase alphanumerics and hyphens). Common values: default, kube-system, kube-public. Use get_available_namespaces() to discover valid namespaces.' For 'deploymentName': 'Deployment resource name (1-253 chars, must exist in the target namespace).'
Add an enum or discovery tool for namespaces. Either: (1) Add a get_available_namespaces() tool that returns the list of valid namespaces, or (2) Store namespace enum in tool configuration and constrain the parameter. This prevents hallucinated namespace names.
Implement error recovery guidance. When deploy_service fails because a deployment doesn't exist, return: 'Deployment "my-app" not found in namespace "prod". Available deployments: [list]. Did you mean one of these?' This guides the agent to retry with a valid name.
No enums or constraints on 'namespace' parameter despite Kubernetes having a finite, discoverable set of valid namespaces. Free-form strings invite hallucinated namespace names.
No error handling or recovery guidance. If a deployment does not exist, if the namespace is invalid, or if the agent lacks RBAC permissions, what happens? The tool must return actionable error messages with next steps.
Tool annotations are absent. deploy_service and undeploy_service are mutually opposite operations, they should have destructiveHint or idempotentHint annotations to help the agent understand their side effects and retry semantics.
No confirmation or dry-run capability for destructive operations. undeploy_service scales a deployment to zero, an irreversible action. No confirmation_request pattern or dry-run option to prevent accidental undeployment.
Tool composition is weak. get_namespace_pods returns pod data but deploy_service/undeploy_service operate on Deployments, not Pods. No tools exist to list deployments or describe deployment status. The agent cannot verify deployment success without a describe_deployment tool.
get_namespace_podsdeploy_serviceundeploy_service
Add tool annotations to distinguish operation semantics. Mark deploy_service with idempotentHint if calling it twice with the same input is safe; mark undeploy_service with destructiveHint:true to signal to the agent that it should confirm before executing. Use readOnlyHint:true for get_namespace_pods.
Add a describe_deployment tool that returns deployment status, replica counts, image digest, and recent events. This enables the agent to verify that deploy_service succeeded before proceeding.
Implement a dry-run or preview mode for destructive operations. Allow undeploy_service to accept a 'dry_run' parameter that returns the effect without actually scaling down. This prevents accidental undeployments.
Add a parameter 'replicas' to deploy_service to specify desired replica count instead of using a hard-coded default. Describe its constraints: 'Number of replicas to deploy (1-100, default 1).'
Provide a list_deployments tool to discover deployments in a namespace before deploying or undeploying, enabling one-shot discovery instead of trial-and-error.