Summary
Surfaced during work on #498. Agents calling other agents have no in-band guidance on which delegation pattern to use, leading to predictable misuse (e.g., chat_with_agent parallel=true async=false for fan-out, which doesn't queue and produces terminal capacity rejections).
The platform offers three distinct patterns but documents only one of them in the agent's system prompt and undersells the trade-offs in the MCP tool descriptions.
Component
Backend / Platform Prompt Service / MCP Server (chat tool)
Priority
P2 — improves observable agent behavior platform-wide; complements the platform fix in #498.
What agents see today
src/backend/services/platform_prompt_service.py:38 mentions only:
- mcp__trinity__chat_with_agent(agent_name, message) - Delegate tasks to other agents
No mention of parallel, async, fan_out, or capacity behavior.
src/mcp-server/src/tools/chat.ts — the chat_with_agent description hints at the modes but doesn't tell agents that sync parallel mode does NOT queue at capacity. The fan_out tool exists right next to it but the chat_with_agent description doesn't pointer to it.
Proposed Changes
1. platform_prompt_service.py — Replace the Agent Collaboration subsection
Replace the single-bullet chat_with_agent mention with three named patterns:
- Conversational handoff —
chat_with_agent(name, message). Sequential, queue-backed, maintains context.
- Single parallel task —
chat_with_agent(name, message, parallel=true, async=true). Stateless, returns execution_id; poll for result. Capacity overflow IS absorbed.
- Fan-out workload —
fan_out(name, [tasks]). Designed for N independent tasks with built-in concurrency control. Use whenever there are ≥3 independent tasks for the same agent.
Plus a short capacity note explaining when each mode queues vs fails.
2. src/mcp-server/src/tools/chat.ts — Tighten chat_with_agent description
Add a 'Capacity behavior' subsection that names the three (parallel, async) combinations and what each does at capacity. Add explicit pointer: 'For fan-out (≥3 tasks to same agent), use fan_out instead.'
3. Optional — surface fan_out in list_agents response
When an agent lists its collaborators, hint at the recommended delegation pattern based on permissions.
Acceptance Criteria
Out of Scope
Related
Summary
Surfaced during work on #498. Agents calling other agents have no in-band guidance on which delegation pattern to use, leading to predictable misuse (e.g.,
chat_with_agent parallel=true async=falsefor fan-out, which doesn't queue and produces terminal capacity rejections).The platform offers three distinct patterns but documents only one of them in the agent's system prompt and undersells the trade-offs in the MCP tool descriptions.
Component
Backend / Platform Prompt Service / MCP Server (chat tool)
Priority
P2 — improves observable agent behavior platform-wide; complements the platform fix in #498.
What agents see today
src/backend/services/platform_prompt_service.py:38mentions only:No mention of
parallel,async,fan_out, or capacity behavior.src/mcp-server/src/tools/chat.ts— thechat_with_agentdescription hints at the modes but doesn't tell agents that sync parallel mode does NOT queue at capacity. Thefan_outtool exists right next to it but thechat_with_agentdescription doesn't pointer to it.Proposed Changes
1.
platform_prompt_service.py— Replace the Agent Collaboration subsectionReplace the single-bullet
chat_with_agentmention with three named patterns:chat_with_agent(name, message). Sequential, queue-backed, maintains context.chat_with_agent(name, message, parallel=true, async=true). Stateless, returns execution_id; poll for result. Capacity overflow IS absorbed.fan_out(name, [tasks]). Designed for N independent tasks with built-in concurrency control. Use whenever there are ≥3 independent tasks for the same agent.Plus a short capacity note explaining when each mode queues vs fails.
2.
src/mcp-server/src/tools/chat.ts— Tightenchat_with_agentdescriptionAdd a 'Capacity behavior' subsection that names the three (parallel, async) combinations and what each does at capacity. Add explicit pointer: 'For fan-out (≥3 tasks to same agent), use fan_out instead.'
3. Optional — surface fan_out in
list_agentsresponseWhen an agent lists its collaborators, hint at the recommended delegation pattern based on permissions.
Acceptance Criteria
chat_with_agentMCP tool description states the at-capacity behavior of each mode and pointers tofan_out.fan_outor async-parallel, not sync-parallel.Out of Scope
Related