chore: address few nits

Signed-off-by: Krishna Gupta <Krishnagupta.kg2k6@gmail.com>

Author: Krishna-kg732

docs/proposals/KEP#0001.md

@@ -8,6 +8,9 @@ creation-date: 2025-06-02
 
 # KEP: Katib (Optimizer) Client Support for kubeflow-mcp-server
 
+> **Terminology**: This document uses "Katib" when referring to the Kubeflow
+> product and "optimizer" when referring to the `kubeflow_mcp.optimizer` module.
+
 ## Summary
 
 The Kubeflow MCP Server exposes Kubeflow Training operations as
@@ -18,9 +21,9 @@ workflow -- remains inaccessible through MCP.
 
 This KEP proposes implementing the **Optimizer client module** for
 `kubeflow-mcp-server`, exposing Katib's Experiment, Trial, and Suggestion
-lifecycle as 16 MCP tools across 5 categories. This implements the
-"Optimizer (Planned: Phase 2)" node already identified in the architecture
-and stub module (`kubeflow_mcp.optimizer`).
+lifecycle as 17 MCP tools across 5 categories. This implements the
+Phase 2 optimizer node (module: `kubeflow_mcp.optimizer`) already identified
+in the architecture (see Architecture Context below).
 
 Katib is the natural second client after TrainerClient because hyperparameter
 tuning is the immediate next step after training infrastructure is in place,
@@ -47,7 +50,7 @@ The existing stub (`kubeflow_mcp.optimizer`) declares 8 planned tools with
 ```
 CLIENT_MODULES = {
     "trainer": "kubeflow_mcp.trainer",     # Phase 1: Implemented (23 tools)
-    "optimizer": "kubeflow_mcp.optimizer", # Phase 2: This KEP (16 tools)
+    "optimizer": "kubeflow_mcp.optimizer", # Phase 2: This KEP (17 tools)
     "hub": "kubeflow_mcp.hub",            # Phase 3: Planned
 }
 ```
@@ -69,7 +72,7 @@ and namespace enforcement infrastructure.
 
 ## Goals
 
-1. Implement 16 MCP tools across 5 categories for Katib experiment, trial,
+1. Implement 17 MCP tools across 5 categories for Katib experiment, trial,
    and suggestion lifecycle (see MCP Tools tables)
 2. Decompose experiment creation into agent-friendly tools, following the
    trainer's `fine_tune`/`run_custom_training`/`run_container_training` pattern
@@ -186,6 +189,7 @@ in `common/utils.py`. Lazy import -- `kubeflow.katib` is only imported when
 
 All read-only tools: `readOnlyHint=True`, `idempotentHint=True`.
 Mutating tools: `create_*` are not idempotent; `delete_experiment` is destructive; `update_experiment` is idempotent.
+`wait_for_experiment`: `readOnlyHint=True`, blocking. Default `polling_interval=15s`, `timeout_seconds` capped at 3600s. Agents should prefer `get_experiment_status()` for non-blocking polling.
 
 `list_suggestions`, `update_experiment`, `get_experiment_events`, and
 `katib_pre_flight` use `CustomObjectsApi`/`CoreV1Api` directly where the SDK
@@ -195,7 +199,7 @@ lacks coverage, following the trainer's pattern for suspend/resume.
 
 | Persona | Optimizer Tools |
 |---------|----------------|
-| `readonly` | All read-only tools (12 tools: planning + discovery + monitoring) |
+| `readonly` | All read-only tools (13 tools: planning + discovery + monitoring) |
 | `data-scientist` | readonly + `create_hpo_experiment`, `wait_for_experiment`, `delete_experiment` (MCP-owned only) |
 | `ml-engineer` | data-scientist + `create_experiment_from_spec`, `update_experiment` |
 | `platform-admin` | all (wildcard) |
@@ -211,10 +215,9 @@ TOOL_PHASES.update({
     ],
     "optimizer_optimization": [
         "create_hpo_experiment", "create_experiment_from_spec",
-        "get_best_trial",
     ],
     "optimizer_monitoring": [
-        "get_experiment_trials", "get_suggestion",
+        "get_experiment_trials", "get_best_trial", "get_suggestion",
         "wait_for_experiment", "get_experiment_trial_logs",
         "get_experiment_events",
     ],
@@ -226,7 +229,7 @@ PHASE_TO_SECTION = {
     "optimizer_discovery": None,
     "optimizer_optimization": "optimization",
     "optimizer_monitoring": "monitoring",
-    "optimizer_lifecycle": "monitoring",
+    "optimizer_lifecycle": "monitoring",  # lifecycle instructions folded into monitoring section
 }
 ```
 
@@ -372,8 +375,9 @@ client modules.
 
 Agent may assume trainer tools are available during optimizer workflows.
 
-**Mitigation**: `katib_pre_flight` checks trainer client availability.
-Cross-client hints only injected when both modules are active.
+**Mitigation**: `katib_pre_flight` reports whether the trainer client is
+loaded (see Cross-Client Integration). Cross-client hints only injected
+when both modules are active.
 
 ## Testing Plan
 
@@ -410,7 +414,7 @@ Cross-client hints only injected when both modules are active.
 
 ### MCP Inspector
 
-- All 16 tools in registry with correct descriptions and annotations
+- All 17 tools in registry with correct descriptions and annotations
 - Progressive mode discovery matches `TOOL_PHASES`
 
 ## References