feedback of all-hands-bot

Author: VascoSch92

sdk/guides/agent-file-based.mdx

@@ -99,9 +99,9 @@ Place agent files in these directories, scanned in **priority order** (first mat
 Put agents shared across all your projects in `~/.agents/agents/`. Put project-specific agents in `{project}/.agents/agents/`.
 </Tip>
 
-## Built-in Sub-Agents
+## Built-in Agents
 
-The `tools` package ships with built-in sub-agents as Markdown files in `openhands/tools/preset/subagents/`.
+The `openhands-tools` package ships with built-in sub-agents as Markdown files in `openhands/tools/preset/subagents/`.
 They can be registered via `register_builtins_agents()` and become available for delegation tasks.
 
 By default, all agents include `finish` tool and the `think` tool.
@@ -121,7 +121,7 @@ In CLI mode, the `default` agent (with browser tools) is replaced by the `defaul
 
 Call `register_builtins_agents()` to register all built-in sub-agents. This is typically done once before creating a conversation:
 
-```python icon="python"
+```python icon="python" focus={3-4, 6-7}
 from openhands.tools.preset.default import register_builtins_agents
 
 # Register built-in sub-agents (default, explore, bash)
@@ -132,10 +132,9 @@ register_builtins_agents(cli_mode=True)
 ```
 
 <Warning>
-Registration order matters when you programmatically register agents with the same name as a built-in.
-    `register_builtins_agents()` uses `register_agent_if_absent()`, which silently skips names that are already taken,
-    so if you register your custom agents **before** calling `register_builtins_agents()`, your agents win.
-    If you call `register_builtins_agents()` first, a subsequent `register_agent()` with a conflicting name will raise a `ValueError`.
+Registration order is critical when programmatically registering agents that share a name with a built-in agent. The system is designed to skip registration if a name is already taken. Therefore, if you register your custom agents before the built-in agents are loaded, your custom versions will take precedence.
+
+Conversely, if the built-in agents are loaded first, they will take precedence, and any subsequent registration of a custom agent with the same name will be ignored.
 </Warning>