Add agent_description for Analysis participants so Coordinator can route by capability

The Coordinator's valid_participants block was a bullet list of names only,
so the LLM had no per-agent capability signal. Combined with a Coordinator
prompt that names 'Chief Architect' frequently across phases 0/1/4/5/6,
the model latched onto Chief Architect repeatedly and the conversation
looped on the same agent.

This change populates agent_description on every Analysis participant
(Chief Architect, AKS Expert, and the platform experts in
platform_registry.json) and renders each description into the Coordinator's
valid_participants list. The descriptions are also passed through
AgentBuilder.create_agent_by_agentinfo's existing description= argument,
so the framework's Agent.description field is no longer always None.

Scope: Analysis step only. design/yaml/documentation orchestrators are
left for a follow-up after this change is validated in production.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Prachig-Microsoft

src/processor/src/steps/analysis/orchestration/analysis_orchestrator.py

@@ -157,8 +157,13 @@ async def prepare_agent_infos(self) -> list[AgentInfo]:
             prompt_path = agent_dir / "agents" / prompt_file
             instruction = self.read_prompt_file(str(prompt_path))
 
+            expert_description = expert.get("description")
+            if not isinstance(expert_description, str) or not expert_description.strip():
+                expert_description = None
+
             expert_info = AgentInfo(
                 agent_name=agent_name,
+                agent_description=expert_description,
                 agent_instruction=instruction,
                 tools=self.mcp_tools,
             )
@@ -172,6 +177,12 @@ async def prepare_agent_infos(self) -> list[AgentInfo]:
         aks_instruction = self.read_prompt_file(agent_dir / "agents/prompt_aks.txt")
         aks_agent_info = AgentInfo(
             agent_name="AKS Expert",
+            agent_description=(
+                "Tool-free reviewer for Azure AKS migration readiness. Reviews the "
+                "latest Evidence Pack and produces SIGN-OFF: PASS/FAIL on AKS-side "
+                "concerns. Select only after the Chief Architect has posted an Evidence "
+                "Pack; required reviewer when present."
+            ),
             agent_instruction=aks_instruction,
             tools=self.mcp_tools,
         )
@@ -188,6 +199,13 @@ async def prepare_agent_infos(self) -> list[AgentInfo]:
 
         chief_architect_agent_info = AgentInfo(
             agent_name="Chief Architect",
+            agent_description=(
+                "Lead orchestrator of the analysis and the ONLY participant with blob "
+                "tools. Performs all file I/O (listing, reading, writing "
+                "analysis_result.md) and authors / refreshes the Evidence Pack. Select "
+                "to run hard-termination triage, to do or redo any file work, or to "
+                "post a fresh Evidence Pack after reviewers ask for one."
+            ),
             agent_instruction=architect_instruction,
             tools=self.mcp_tools,
         )
@@ -208,10 +226,18 @@ async def prepare_agent_infos(self) -> list[AgentInfo]:
             tools=self.mcp_tools[2],  # Blob IO tool only
         )
 
-        # Render coordinator prompt with the current participant list.
+        # Render coordinator prompt with the current participant list. Include each
+        # participant's description so the Coordinator can route by capability rather
+        # than only by name (a name-only list biases the LLM toward whichever name
+        # appears most often elsewhere in the prompt, e.g. "Chief Architect").
         participant_names = [ai.agent_name for ai in agent_infos]
         valid_participants_block = "\n".join([
-            f'- "{name}"' for name in participant_names
+            (
+                f'- "{ai.agent_name}": {ai.agent_description}'
+                if ai.agent_description
+                else f'- "{ai.agent_name}"'
+            )
+            for ai in agent_infos
         ])
         coordinator_agent_info.render(
             **self.task_param.model_dump(),

src/processor/src/steps/analysis/orchestration/platform_registry.json

@@ -6,7 +6,8 @@
       "agent_name": "EKS Expert",
       "prompt_file": "prompt_eks.txt",
       "category": "managed_cloud",
-      "signals": ["eks.amazonaws.com", "aws", "arn:aws", "kops", "eksctl"]
+      "signals": ["eks.amazonaws.com", "aws", "arn:aws", "kops", "eksctl"],
+      "description": "Tool-free reviewer specialized in Amazon EKS (AWS) source-side concerns. Provides EKS-specific analysis of the Evidence Pack and produces SIGN-OFF: PASS/FAIL. Select only after the Chief Architect has posted an Evidence Pack; required only if the source platform is EKS."
     },
     {
       "id": "gke",
@@ -19,7 +20,8 @@
         "anthos",
         "gcr.io",
         "artifactregistry"
-      ]
+      ],
+      "description": "Tool-free reviewer specialized in Google GKE source-side concerns. Provides GKE-specific analysis of the Evidence Pack and produces SIGN-OFF: PASS/FAIL. Select only after the Chief Architect has posted an Evidence Pack; required only if the source platform is GKE."
     },
     {
       "id": "openshift",
@@ -32,21 +34,24 @@
         "ocp",
         "security.openshift.io",
         "config.openshift.io"
-      ]
+      ],
+      "description": "Tool-free reviewer for Red Hat OpenShift (OCP) source-side concerns. Reviews the Evidence Pack and produces SIGN-OFF: PASS/FAIL. Select only after the Chief Architect has posted an Evidence Pack; required only if the source platform is OpenShift."
     },
     {
       "id": "rancher",
       "agent_name": "Rancher Expert",
       "prompt_file": "prompt_rancher.txt",
       "category": "enterprise_distro",
-      "signals": ["cattle.io", "rancher", "rke", "rke2", "k3s"]
+      "signals": ["cattle.io", "rancher", "rke", "rke2", "k3s"],
+      "description": "Tool-free reviewer for Rancher / RKE / RKE2 / K3s source-side concerns. Reviews the Evidence Pack and produces SIGN-OFF: PASS/FAIL. Select only after the Chief Architect has posted an Evidence Pack; required only if the source platform is Rancher."
     },
     {
       "id": "tanzu",
       "agent_name": "Tanzu Expert",
       "prompt_file": "prompt_tanzu.txt",
       "category": "enterprise_distro",
-      "signals": ["tanzu", "vmware", "tkg", "tkgs", "pinniped", "antrea"]
+      "signals": ["tanzu", "vmware", "tkg", "tkgs", "pinniped", "antrea"],
+      "description": "Tool-free reviewer for VMware Tanzu (TKG / TKGS) source-side concerns. Reviews the Evidence Pack and produces SIGN-OFF: PASS/FAIL. Select only after the Chief Architect has posted an Evidence Pack; required only if the source platform is Tanzu."
     },
     {
       "id": "onprem",
@@ -70,7 +75,8 @@
         "ceph",
         "nfs",
         "f5"
-      ]
+      ],
+      "description": "Tool-free reviewer for self-managed / on-premises Kubernetes (kubeadm, k3s, Talos, bare-metal, vSphere) source-side concerns. Reviews the Evidence Pack and produces SIGN-OFF: PASS/FAIL. Select only after the Chief Architect has posted an Evidence Pack; required only if the source platform is on-prem."
     }
   ]
 }