diff --git a/docs/src/ai/external-agents.md b/docs/src/ai/external-agents.md
index 0467913b072ef296a5b187fbeb8dc6a406bf1bed..fb34a2731bce3de91b23e20ac9229a0f9db94a79 100644
--- a/docs/src/ai/external-agents.md
+++ b/docs/src/ai/external-agents.md
@@ -221,7 +221,7 @@ To assign a custom keybinding to start a new thread for agents that were added b
       {
         "agent": {
           "custom": {
-            "name": "My Agent", // The agent name as it appears in the UI (e.g., "OpenCode", "Auggie CLI", etc.)
+            "name": "My Agent", // The agent name as defined in the extension or in settings.json (e.g., "opencode", "Auggie CLI", etc.)
             "command": {
               "command": "my-agent", // The agent name in lowercase with no spaces
               "args": ["acp"]
@@ -234,6 +234,9 @@ To assign a custom keybinding to start a new thread for agents that were added b
 },
 ```
 
+> For most extensions, the `agent.custom.name` attribute matches the name of the agent that appears in the [Agent Panel](../ai/agent-panel.md) UI.
+> In some cases however, the name might need to be written differently (e.g. in lowercase).
+
 ## Debugging Agents
 
 When using external agents in Zed, you can access the debug view via with `dev: open acp logs` from the Command Palette. This lets you see the messages being sent and received between Zed and the agent.