klaus-operator provides 14 well-defined tools with consistent naming, clear descriptions, and comprehensive input schemas. Naming is verb-first and action-focused (create_instance, delete_instance, get_logs). Descriptions are substantive and contextualize tool behavior. Input schemas use proper JSON Schema with type definitions and parameter descriptions. However, output schemas are not documented in the visible source, the tools define responses implicitly through their implementations rather than explicit response schemas in the tool definitions. Error handling patterns are present (tools perform validation internally) but recovery guidance is not visible in descriptions. Tool composition is strong: instance lifecycle tools chain well (create → prompt → get_result), and parameter sets align across similar operations (create_instance and run_instance share most configuration). Security posture is good: no credentials exposed as parameters, and permissions are enforced server-side. One structural weakness: the tool descriptions do not explicitly document return types or response fields, which forces LLMs to infer output structure.

• Add explicit return type documentation to each tool description. Format: 'Returns: {field_name: type, ...}'. Example: 'Returns: {instance_name: string, status: string, created_at: string, pod_name: string}'. This enables LLMs to chain tools correctly and extract the right fields.
• Add error recovery guidance to all tool descriptions. For each tool, append: 'If <failure condition>, try <alternative tool or action>'. Example for get_instance: 'If the instance is not found, call list_instances() to verify the name.'
• Expand discovery tool descriptions (list_plugins, list_personalities, list_toolchains) with usage context. Example: 'List available Klaus toolchain images. Call this first if you need to see version options before creating an instance.'
• Document pagination for list_* tools if result sets can be large. Add optional parameters: limit (default 100, max 1000) and offset (default 0). Update description: 'Returns up to <limit> items; use offset to paginate.'
• Add tool annotations to the schema registration. Use destructiveHint for delete_instance, idempotentHint for get_* tools, and readOnlyHint for list_* tools. Integrate with mark3labs/mcp-go's tool definition API if available.
• Document parameter relationships for create_instance and run_instance. Clarify that workspace_git_repo, workspace_git_ref, and workspace_git_secret are optional but interdependent. Example: 'If workspace_git_repo is provided, workspace_git_ref defaults to main.'
• Add confirmation or dry-run support for destructive operations (delete_instance). Consider a dry_run boolean parameter that validates the operation without executing, enabling safer agent usage.