Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
OpenShift MCP server exhibits significant gaps in definition quality. While tool names follow verb_noun convention appropriately (connect_cluster, list_namespaces, delete_pod), most descriptions are generic and many lack critical context. Parameter schemas are present but descriptions for individual parameters are sparse or missing entirely. Output schemas are not documented. Error handling guidance is absent. The server conflates infrastructure operations with LLM integration in the same tool set, creating composition issues. Most tools are READ_ONLY with only 4 WRITE/DESTRUCTIVE operations, but destructive tools (delete_pod, delete_namespace) lack confirmation patterns and recoverable error guidance.
Destructive operations (delete_pod, delete_namespace) lack confirmation/dry-run pattern and recovery guidance. Descriptions are minimal (35 chars), providing no context on consequences or recovery steps.
Output schemas are not documented. Tools return results, but the response structure and field types are not formally specified. LLMs cannot plan downstream operations or extract specific fields without this documentation.
List tools (*_namespace, *_pods, etc.) lack pagination parameters (limit, offset, next_cursor) and do not document result cardinality limits. Large clusters returning hundreds of items will exhaust context windows.
Recommendations
Add confirmation/dry-run pattern to delete_pod and delete_namespace. Example: add a 'dry_run' boolean parameter (defaults to false) and a 'confirm' tool that accepts the operation ID to confirm deletion after preview.
Document output schemas for all tools. For list_* tools, specify: 'Returns an object {items: [{name: string, uid: string, status: string, created_at: ISO8601}], total_count: integer, page_info: {has_more: boolean}}'. For get_pod_logs, specify: 'Returns {pod_name: string, namespace: string, container_name: string, logs: string, timestamp_start: ISO8601}'.
Add pagination to list_* tools: 'limit' parameter (default 20, max 100) and 'offset' parameter (default 0). Return total_count and has_next_cursor in response so agents can iterate without fetching all items.
Expand tool descriptions to 100-200 characters. Examples: 'List all namespaces in the cluster. Call this first to discover available namespaces before operating on pods, services, or deployments.' 'Delete a pod, this is destructive and cannot be undone. The pod will be immediately terminated and recreated by its controller if configured.'
Add parameter-level descriptions with constraints. Example for 'namespace': 'Kubernetes namespace name (lowercase alphanumeric and hyphens, 1-63 characters). Call list_namespaces() to discover valid namespaces.'
Refactor LLM integration tools (ask_llm, get_llm_providers, test_llm_connection, intelligent_cluster_analysis, get_troubleshooting_help) into a separate MCP server or clearly mark them as optional add-ons. Cluster management is a distinct domain; conflating them forces agents to reason about when to use LLM tools vs cluster tools.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Generic and minimal descriptions throughout. 'List all namespaces in the cluster' (39 chars) and 'List pods in a namespace' (24 chars) lack context on when to use them vs similar tools, what structure is returned, or when to call them in a multi-step workflow.
Parameter descriptions are missing or trivial for many tools. 'namespace_name' is described only as 'Namespace name' (14 chars), providing no context on format, constraints, or how to obtain a valid namespace name. LLMs lack guidance on valid input.
Tool composition issue: ask_llm, get_llm_providers, test_llm_connection, intelligent_cluster_analysis, and get_troubleshooting_help mix LLM integration with cluster management. This conflates two separate domains and forces the agent to reason about when to use LLM tools vs cluster tools. Split into separate tool namespaces or servers.
No error handling guidance. Error responses likely contain stack traces or generic error codes with no recovery instructions. 'Namespace not found' does not tell the LLM to call list_namespaces() first or what namespaces are available.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) visible in the source. Even though schema declares 'Risk' metadata, the MCP tool definitions should include proper annotations so clients and agents can apply safety policies.
Parameter naming inconsistency: 'cluster_url' vs 'cluster' vs typical 'url' patterns. Some tools use 'pod_name' and others use 'deployment_name', but there is no consistent suffix pattern for ID vs name parameters. LLMs struggle to disambiguate.
No idempotency guarantees documented. Agents retry on transient failures. If scale_deployment is not idempotent (calling it twice with replicas=3 might scale to 6), agents risk unintended side effects. All write operations should document retry safety.
scale_deploymentcreate_namespace
Implement structured error responses. Example: Instead of 'Pod not found', return: {error: 'not_found', message: 'Pod my-pod in namespace default not found', suggestion: 'Call list_pods(namespace=default) to see available pods', retryable: false}.
Add tool annotations to tool definitions. Ensure delete_* tools have destructiveHint=true, list_* tools have readOnlyHint=true. If scale_deployment is idempotent (which it should be), set idempotentHint=true.
Standardize parameter naming: use '_id' suffix for opaque IDs and '_name' suffix for human-readable names. Example: pod_name (accept 'nginx-pod'), not pod (ambiguous). Accept display names internally and resolve to UIDs server-side.
Document idempotency for all write/mutating operations. Example: 'Calling scale_deployment twice with the same replicas=3 is safe, the second call succeeds with no additional changes. Deployment replicas will be exactly 3.'
Add rate limit guidance and timeout values to descriptions. Example: 'Retrieve up to 100 lines of logs; large requests may time out. For high-volume logging, consider external log aggregation.'
Provide examples of valid parameter values in descriptions (not as defaults). Example: 'Namespace name, e.g. default, kube-system, openshift-operators. Call list_namespaces() to see all available namespaces.'