The Kubeflow MCP server provides 33 tools with basic schemas and descriptions, but exhibits significant gaps in description quality, parameter documentation, and output schema clarity. Tool naming is generally clear and verb-driven, following conventions (get_, list_, create_, delete_). However, descriptions are often generic (e.g., 'Get information about the current Kubernetes cluster') and lack guidance on WHEN to use the tool or WHAT output to expect. Many parameters lack complete type information, some tools have parameters with descriptions but no explicit schema (e.g., 'config' in validate_training_config is typed as 'object' with no sub-schema). Output schemas are not documented, making it impossible for LLMs to plan multi-step workflows reliably. Error handling is absent from descriptions, and there is no guidance on which operations are destructive vs. safe to retry. The schema for tools like 'manage_checkpoints' is overly broad (action parameter accepts free-form strings instead of an enum: list|save|restore|delete). No tool annotations (readOnlyHint, destructiveHint, idempotentHint) are present despite 4 destructive operations (delete_training_job, delete_resource) and multiple reversible operations (suspend/resume). Security concerns: setup_hf_credentials accepts a 'token' parameter directly, which violates secret-injection patterns. Schema scores are capped at 30-40 for tools with incomplete parameter documentation (e.g., 'training_config' object with no schema definition).

• Add explicit output schema documentation for every tool. Document the structure of the response (fields, types, nested objects) so LLMs can plan downstream steps. Example: 'Returns {job_id: string, status: string ("running"|"succeeded"|"failed"), created_at: ISO 8601 timestamp, ...'
• Replace secret parameter (setup_hf_credentials 'token') with server-side environment variable or vault injection. Document in the tool description: 'HuggingFace credentials are injected from environment variable HF_TOKEN at startup.'
• Add tool annotations to all tools. Mark destructive tools (delete_training_job, delete_resource) with destructiveHint: true. Mark read-only tools with readOnlyHint: true. Mark idempotent operations with idempotentHint: true.
• Expand all descriptions to 100 - 250 characters. Include WHEN to use the tool, WHAT it returns, and any prerequisites. Example for get_training_job: 'Retrieve full details of a specific training job including status, resource usage, and recent events. Use this after submitting a job to monitor progress. Returns job_id, status (running|succeeded|failed), created_at, updated_at, pod_status.'
• Add enum constraints to all categorical parameters. Replace 'action' string in manage_checkpoints with enum: ["list", "save", "restore", "delete"]. Replace 'model_size' string in estimate_resources with enum: ["small", "medium", "large", "xlarge"].
• Define sub-schemas for all object parameters. For 'training_config' in train(), document the expected structure: {framework: enum, batch_size: integer (1-1024), learning_rate: number, ...}. Use JSON Schema $ref or inline properties.