Website: Documentation does not mention that `gemini-3.1-pro-preview-customtools` is restricted to Gemini API Key authentication

[eevmanu]

URL of the page with the issue

https://geminicli.com/docs/get-started/authentication/

Additional relevant pages:

• https://geminicli.com/docs/cli/model/
• https://geminicli.com/docs/get-started/gemini-3/
• https://geminicli.com/docs/cli/model-routing/

What is the problem?

The documentation does not mention that the gemini-3.1-pro-preview-customtools model variant is only available when authenticating via Gemini API Key (i.e., an API key created from Google AI Studio, corresponding to AuthType.USE_GEMINI in the codebase).

This auth-based model restriction is enforced across the entire codebase — in model resolution (resolveModel), model routing (classifier and numerical classifier strategies), policy chains, the /model dialog UI, and the ACP client — via a useCustomToolModel flag that evaluates to true only when useGemini3_1 === true && authType === AuthType.USE_GEMINI.

Key code evidence:

• packages/core/src/config/config.ts — getUseCustomToolModel() and getUseCustomToolModelSync() both gate on AuthType.USE_GEMINI
• packages/core/src/config/models.ts — resolveModel() conditionally returns customtools variant only when the flag is set
• packages/cli/src/ui/components/ModelDialog.tsx — UI only shows customtools model for API Key users
• packages/cli/src/acp/acpClient.ts — buildAvailableModels() applies same restriction
• Multiple routing strategy tests explicitly verify this behavior

Partially related issues and PRs:

• fix(core): use customtools model for gemini-3.1-pro-preview for api key users #20474 — attempted to fix customtools model resolution for API key users (closed, not merged)
• fix(core): ensure correct flash model steering in plan mode implementation phase #21871 — fixed flash model steering in plan mode implementation phase (merged), which touches the same routing and model resolution logic
• Model steering incorrectly reverts to Gemini 2.5 Flash after Plan Mode when using 'auto' alias #21868 — reported model steering incorrectly reverting to Gemini 2.5 Flash after Plan Mode, related to how auto aliases and model variants are resolved
• feat(core): add policy chain support for Gemini 3.1 and Custom Tools #19988 — added policy chain support for Gemini 3.1 and Custom Tools models, directly establishing the customtools fallback chain behavior

What did you expect to happen?

I expected the documentation to clearly state that authentication method affects which models are available. Specifically:

1. Authentication docs (docs/get-started/authentication.md): The auth methods comparison table should note model availability differences — e.g., that gemini-3.1-pro-preview-customtools is exclusive to Gemini API Key auth (AI Studio keys).
2. Model selection docs (docs/cli/model.md): Should mention the customtools variant and its auth requirement, since users choosing models via /model or --model may see different options depending on their auth method.
3. Gemini 3 docs (docs/get-started/gemini-3.md): Already mentions gemini-3.1-pro-preview but does not mention the customtools variant or that it's auth-gated.
4. Model routing docs (docs/cli/model-routing.md): Routing behavior (policy chains, classifier strategies) differs by auth type, but this is not documented.

Additional context

From code analysis, what can be confirmed is:

Auth Method	Model used for Gemini 3.1 Pro
Gemini API Key (from AI Studio)	gemini-3.1-pro-preview-customtools ✅
Other auth methods	gemini-3.1-pro-preview (the customtools suffix is not applied)

Note: The codebase gates the customtools variant strictly on AuthType.USE_GEMINI. It is unclear whether other API key-based flows (e.g., a Google Cloud API key used via Vertex AI auth) would or should also qualify. This issue focuses on the confirmed behavior: only AI Studio API keys trigger the customtools model selection.

This discoverability gap could cause confusion for users who see different models listed in the /model dialog depending on their auth method, or who encounter unexpected behavior when switching between auth methods. Documenting this restriction would improve transparency and help with troubleshooting.

[gemini-cli]

👋 @sarveshtiku, thanks for your interest in this issue! We're reserving self-assignment for issues that have been marked with the help wanted label. Feel free to check out our list of issues that need attention.

[NestroyMusoke]

Hi, I'd like to work on this documentation issue. I've reviewed the four affected pages and the code evidence provided. My plan is to add clear notes about the auth-based model restriction to authentication.md, model.md, gemini-3.md, and model-routing.md. Could a maintainer confirm this is open for community contribution and apply the help-wanted label if appropriate? Thank you.

[NestroyMusoke]

/assign

[gemini-cli]

👋 @NestroyMusoke, thanks for your interest in this issue! We're reserving self-assignment for issues that have been marked with the help wanted label. Feel free to check out our list of issues that need attention.

[gemini-cli]

Missing information in documentation regarding model authentication restrictions (P3).