[DOCS] Swarm as a Tool can incorrectly hint at magically creating dynamic agents #322
Description
Documentation Section
Current State
The example shown there feels "magical" — it looks like you can just write:
agent = Agent(tools=[swarm], system_prompt="Create a swarm of agents to solve the user's query.")
agent("Research, analyze, and summarize the latest advancements in quantum computing")
... but when you actually try it, nothing happens because there’s no swarm configuration.
This can be a real “wait… where did the agents come from?!” moment for new users, so it can be misleading.
Suggested Improvement
Might be worth updating the example to show a minimal swarm_spec (or explain how it’s generated dynamically) so people understand that the SDK doesn’t auto-spawn sub-agents by itself.
Rationale
This will help readers to connect how the dynamic agent creation actually works, otherwise it can seem confusing and misleading.
Additional Context
No response