K8s MCP server exposes 2 read-only tools for Kubernetes cluster interaction. Tool definitions are present with proper schema registration via mark3labs/mcp-go framework. Both tools have descriptions and parameter schemas with type information. However, output schemas are completely undocumented, critical for LLM planning downstream calls. Descriptions are adequate but minimal (50-70 chars). Parameters lack format constraints, validation guidance, and dependency documentation. Error handling strategy is not visible in provided code. No tool annotations (readOnlyHint/destructiveHint) despite tools being demonstrably read-only. Resource composition is weak, both tools operate on arbitrary Kubernetes resources but lack return schema documentation needed for chaining tool calls.

• Add complete output schema documentation for both tools. Example: 'Returns a Kubernetes resource object with apiVersion, kind, metadata (name, namespace, uid, labels, annotations), and spec fields. For listResources, returns {items: [Resource], total: number, remaining: number}.'
• Implement readOnlyHint tool annotation in mcp-go calls: mcp.WithReadOnlyHint(true) for both tools to signal safety to agents.
• Extend listResources to accept limit (default 20, max 100) and offset/continue parameters. Return pagination metadata: {items: [...], total: number, hasMore: boolean, continue: string}.
• Add enum-like guidance for 'kind' parameter. Either list common kinds in description or document how to discover valid kinds via a separate tool/resource.
• Enhance parameter descriptions with format and constraint guidance. Example: 'namespace: The Kubernetes namespace (e.g. default, kube-system). Omit to search all namespaces.' Document default behavior explicitly.
• Add error recovery guidance in tool descriptions. Example: 'If kind is unrecognized, call listResources with kind=* to discover available resource types. If namespace not found, check accessible namespaces via the namespace resource.'
• Document RBAC behavior: clarify that results are filtered by the calling agent/user's Kubernetes permissions. Unauthorized resources are silently omitted.
• Implement per-item error handling in listResources. If some resources fail to fetch due to RBAC or other errors, return successful items with a 'errors' array indicating which items failed and why, rather than failing the entire call.

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry