docs: add model choice guides

openhands/usage/settings/llm-settings.mdx

@@ -6,7 +6,7 @@
 ## Overview
 
 The LLM settings allows you to bring your own LLM and API key to use with OpenHands. This can be any model that is
 supported by litellm, but it requires a powerful model to work properly.
 [See our recommended models here](/openhands/usage/llms/llms#model-recommendations). You can also configure some
 additional LLM settings on this page.
 
@@ -92,6 +92,16 @@
 - Switch to a more powerful model when the task requires deeper reasoning
 - Use specialized models for specific types of tasks
 
+For example, you might create profiles like these:
+
+| Example Profile | Example Use | Example Cost Pattern |
+| --- | --- | --- |
+| `claude-opus-4-7` | Frontend design and visual polish | Higher cost |
+| `gpt-5.5` | Planning, instruction following, or review | Balanced for complex reasoning |
+| `minimax-m2.7` | Day-to-day implementation | Lower cost |
+
+The profile names above are examples. Use names that match the saved profiles in your OpenHands environment.
+
 To switch profiles during an active conversation:
 
 1. Look for the **profile selector button** in the chat input area. It displays the name of the currently active profile.
@@ -110,10 +120,64 @@
 
 You can also list and switch profiles directly from the chat input using the `/model` slash command:
 
-- `/model` — Lists your saved LLM profiles, including which one is active and whether each profile has an API key set.
-- `/model <name>` — Switches the conversation to the profile with the given name.
+- `/model` — Lists your saved LLM profiles.
+- `/model <profile-name>` — Switches the running conversation to that profile.
+
+This is equivalent to using the profile selector button and works without leaving the chat. Profile names must match the
+saved profile exactly. The switch applies to future agent steps; it does not rerun earlier messages.
+
+A common workflow is to use a stronger model for planning and then switch to a lower-cost model for implementation:
+
+1. Start the conversation with `gpt-5.5` selected.
+2. Ask OpenHands to plan the work before editing files:
+
+   ```text
+   Plan the OpenHands features page. Do not edit files yet.
+   ```
+
+3. Send `/model` to list available profiles.
+4. Send `/model minimax-m2.7` to switch profiles.
+5. Ask OpenHands to implement the plan:
+
+   ```text
+   Now implement the plan.
+   ```
+
+![Agent Canvas showing example /model command output that lists saved profiles and switches to another profile](/openhands/static/img/model-command-agent-canvas.png)
+
+<Note>
+Model switching requires saved LLM profiles. If `/model` is not suggested in the chat input, create profiles in
+`Settings > LLM` and confirm that your backend supports profile switching.
+</Note>
+
+### Letting the Agent Select Models Dynamically
+
+When the model selection tool is available, the agent can choose a saved profile for the next phase of work. For example,
+it can implement frontend changes with a design-focused model and then switch to an instruction-following model for review.
+
+In the Agent SDK, this capability is exposed as the built-in `SwitchLLMTool`, which produces `switch_llm` tool calls.
+Agent Canvas displays those tool calls as `Switch LLM profile` events in the conversation timeline so you can see when
+and why the model changed.
+
+Create the profiles you want the agent to choose from, then ask OpenHands to use specific profiles for different phases
+of the task. For example:
+
+```text
+Implement a simple web page on the features of OpenHands with Claude Opus 4.7, and then switch to GPT-5.5 and review the code.
+```
+
+![Agent Canvas showing example switch_llm tool calls that move a task between saved profiles](/openhands/static/img/model-selection-tool-agent-canvas.png)
+
+The model selection tool behaves as follows:
+
+- The current model decides to call the tool and provides a short reason.
+- The switch takes effect on the next LLM call after the tool succeeds.
+- Conversation history, files, and task state are preserved.
+- If a profile name is missing or misspelled, the tool returns an error and the agent should choose a valid profile or
+  ask for help.
 
-This is equivalent to using the profile selector button and works without leaving the chat.
+For custom SDK agents, include `SwitchLLMTool` when constructing the agent. See the SDK example:
+[examples/01_standalone_sdk/49_switch_llm_tool.py](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/49_switch_llm_tool.py).
 
 ### How Profile Switching Works