KubeSearch MCP Server demonstrates solid definition quality with consistent naming conventions, detailed descriptions, and well-structured schemas across all 6 tools. All tools follow verb_noun patterns (search_*, get_*, list_*) and include comprehensive descriptions (194 - 280 chars average, well within the 10 - 1024 baseline). Input schemas are explicit and properly typed with Zod validation. However, output schemas are not formally documented in the source code (only inferred from JSON stringification), and error handling, while present, lacks recovery guidance. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) are declared. Tool composition is excellent, the tools form a coherent workflow (search → list_sources → get_details/get_index/get_stats) with proper ID chaining via 'key' fields. Security is appropriate (read-only operations, no credentials exposed). Missing output schema documentation and tool annotations prevent a higher score.

• Export TypeScript interfaces for each tool's output schema (e.g., SearchDeploymentsResult, GetChartDetailsResult) and include them in the tool registration. This enables clients to validate responses and LLMs to infer expected fields.
• Add tool annotations to all tool definitions: set readOnlyHint=true for all six tools (all are read-only queries). Update tool registration in src/index.ts to include { readOnlyHint: true } in each tool object.
• Enhance error messages with recovery guidance. Example: instead of 'Chart with key "invalid" not found', return 'Chart with key "invalid" not found. Try calling search_deployments(query="[chart name]") to find available charts, then use list_chart_sources() to get valid keys.'
• Add offset/cursor-based pagination to search_deployments, list_chart_sources, and search_container_images. Return { results: [...], total_count: N, next_cursor?: string } so agents can iterate through large result sets without context explosion.
• Document output schemas in a schema file (e.g., src/schemas/output-schemas.ts) with Zod definitions or TypeScript interfaces, then reference them in tool descriptions: 'Returns { deployments: Deployment[], totalCount: number }' with field definitions.
• Add examples to parameter descriptions to help LLMs understand intent without treating examples as the only valid options. E.g., for query param: 'Search term like "plex", "nginx", or "traefik", supports partial matching and fuzzy search.'
• Consider adding a get_deployment_details tool to retrieve full YAML/values for a specific deployment, complementing the current search/list/stats tools. This would enable complete workflow coverage for chart discovery → analysis → deployment.