oss(deepagents-cli): document /model switcher filtering criteria (#2978)

Document exactly why models do or don't appear in the Deep Agents CLI
`/model` switcher. The existing docs described the switcher list as
"hardcoded" and didn't explain the filtering logic — users had no way to
understand why a model was missing.

Author: mdrxy

src/oss/deepagents/cli/configuration.mdx

@@ -50,6 +50,8 @@ temperature = 0.7
 <ResponseField name="models" type="string[]">
     A list of model names to show in the interactive `/model` switcher for this provider. For providers that already ship with model profiles, any names you add here appear alongside the bundled ones — useful for newly released models that haven't been added to the package yet. For [arbitrary providers](#arbitrary-providers), this list is the only source of models in the switcher.
 
+    Models listed here **bypass** the profile-based [filtering criteria](/oss/deepagents/cli/providers#which-models-appear-in-the-switcher) and always appear in the switcher. This makes it the recommended way to surface models that are excluded because their profile lacks `tool_calling` support or doesn't exist yet.
+
     This key is optional. You can always pass any model name directly to `/model` or `--model` regardless of whether it appears in the switcher; the provider validates the name at request time.
 </ResponseField>
 

src/oss/deepagents/cli/providers.mdx

@@ -81,17 +81,17 @@ Using a provider not listed here? See [Arbitrary providers](#arbitrary-providers
 :::
 
 <Tip>
-    A **[model profile](/oss/langchain/models#model-profiles)** is a bundle of metadata (model name, default parameters, capabilities, etc.) that ships with a provider package, largely powered by the [models.dev](https://models.dev/) project. Providers that include model profiles have their models listed automatically in the interactive `/model` switcher. Providers without model profiles require you to specify the model name directly.
+    A **[model profile](/oss/langchain/models#model-profiles)** is a bundle of metadata (model name, default parameters, capabilities, etc.) that ships with a provider package, largely powered by the [models.dev](https://models.dev/) project. Providers that include model profiles have their models listed automatically in the interactive `/model` switcher, subject to the [filtering criteria](#which-models-appear-in-the-switcher) (notably, `tool_calling` must be enabled). Providers without model profiles require you to specify the model name directly or add models via `config.toml`.
 </Tip>
 
 ### Switching models
 
 To switch models in the CLI, either:
 
-1. **Use the interactive model switcher** with the `/model` command. This displays a hardcoded list of known model profiles sourced from each LangChain provider package.
+1. **Use the interactive model switcher** with the `/model` command. This displays available models sourced from each installed LangChain provider package's [model profiles](/oss/langchain/models#model-profiles).
 
     <Note>
-        Note that these profiles are not an exhaustive list of available models. If the model you want isn't shown, use option 2 instead (useful for newly released models that haven't been added to the profiles yet).
+        These profiles are not an exhaustive list of available models. If the model you want isn't shown, use option 2 instead (useful for newly released models that haven't been added to the profiles yet). See [Which models appear in the switcher](#which-models-appear-in-the-switcher) for the full set of criteria.
     </Note>
 2. **Specify a model name directly** as an argument, e.g. `/model openai:gpt-4o`. You can use any model supported by the chosen provider, regardless of whether it appears in the list from option 1. The model name will be passed to the API request.
 3. **Specify the model at launch** via `--model`, e.g.
@@ -100,6 +100,29 @@ To switch models in the CLI, either:
     deepagents --model openai:gpt-4o
     ```
 
+### Which models appear in the switcher
+
+The interactive `/model` selector builds its list dynamically — it is not a hardcoded list baked into the CLI. A model appears in the switcher when **all** of the following are true:
+
+1. **The provider package is installed.** Each provider (e.g. `langchain-anthropic`, `langchain-openai`) must be installed alongside `deepagents-cli` — either as an [install extra](/oss/deepagents/cli/providers#quick-start) (e.g. `uv tool install 'deepagents-cli[anthropic]'`) or added later with `uv tool upgrade deepagents-cli --with <package>`. If a package is missing, its entire provider section is absent from the switcher.
+2. **The model has a profile with `tool_calling` enabled.** The CLI is a tool-calling agent, so it filters out models that don't support tool calling, as indicated in their profile data. This is the most common reason a model is missing from the list.
+3. **The model accepts and produces text.** Models whose profile explicitly sets `text_inputs` or `text_outputs` to `false` (e.g. embedding or image-generation models) are excluded.
+
+Models defined in `config.toml` under [`[models.providers.<name>].models`](/oss/deepagents/cli/configuration#adding-models-to-the-interactive-switcher) bypass the profile filter — they always appear in the switcher regardless of profile metadata. This is the recommended way to add models that are missing from the list.
+
+<Tip>
+    Credential status does **not** affect whether a model is listed. The switcher shows all qualifying models and displays a credential indicator next to each provider header: a checkmark for confirmed credentials, a warning for missing credentials, or a question mark when credential status is unknown. You can still select a model with missing credentials — the provider will report an authentication error at request time.
+</Tip>
+
+#### Troubleshooting missing models
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| Entire provider missing from switcher | Provider package not installed | Install the package (e.g. `uv tool upgrade deepagents-cli --with langchain-groq`) |
+| Provider shown but specific model missing | Model profile has `tool_calling: false` or no profile exists | Add the model to `[models.providers.<name>].models` in `config.toml`, or use `/model <provider>:<model>` directly |
+| Provider shows ⚠ "missing credentials" | API key env var not set | Set the credential env var from the [Provider reference](#provider-reference) table |
+| Provider shows ? "credentials unknown" | Provider uses non-standard auth that the CLI can't verify | Credentials may still work — try switching to the model. If auth fails, check the provider's docs |
+
 ### Setting a default model
 
 You can set a persistent default model that will be used for all future CLI launches: