capabilities

docs/features/ai-knowledge/models.md

@@ -147,13 +147,33 @@ These tools are specifically designed to help administrators quickly manage exte
 
 Administrators can set **global default metadata and parameters** that apply as a baseline to all models. This eliminates the need to manually configure capabilities and inference settings for every model individually.
 
-- **Default Model Metadata** (`DEFAULT_MODEL_METADATA`): Sets baseline capabilities (vision, web search, code interpreter, etc.) and other model metadata for all models. For capabilities, defaults and per-model values are merged — per-model overrides always win on conflicts. For other metadata fields, the global default is only applied when a model has no value set.
-- **Default Model Params** (`DEFAULT_MODEL_PARAMS`): Sets baseline inference parameters (temperature, top_p, max_tokens, seed, etc.) for all models. Per-model parameter overrides always take precedence.
+- **Default Model Metadata** (`DEFAULT_MODEL_METADATA`): Sets baseline capabilities (vision, web search, file context, code interpreter, builtin tools, etc.) and other model metadata for all models. For capabilities, defaults and per-model values are merged — per-model overrides always win on conflicts. For other metadata fields, the global default is only applied when a model has no value set.
+- **Default Model Params** (`DEFAULT_MODEL_PARAMS`): Sets baseline inference parameters (temperature, top_p, max_tokens, seed, function_calling, etc.) for all models. Per-model parameter overrides always take precedence — but only when a per-model value is explicitly set.
 
-These settings are accessible via **Admin Settings → Models** and are persisted via `PersistentConfig`. See [`DEFAULT_MODEL_METADATA`](/reference/env-configuration#default_model_metadata) and [`DEFAULT_MODEL_PARAMS`](/reference/env-configuration#default_model_params) for details.
+These settings are accessible via **Admin Settings → Models → ⚙️ (gear icon)** and are persisted via `PersistentConfig`. See [`DEFAULT_MODEL_METADATA`](/reference/env-configuration#default_model_metadata) and [`DEFAULT_MODEL_PARAMS`](/reference/env-configuration#default_model_params) for details.
+
+#### Merge Behavior
+
+Understanding how defaults combine with per-model settings is important:
+
+| Setting Type | Merge Strategy | Example |
+|---|---|---|
+| **Capabilities** (metadata) | Deep merge: `{...global, ...per_model}` | Global sets `file_context: false`, model sets `vision: true` → model gets both |
+| **Other metadata** (description, tags, etc.) | Fill-only: global applied when model value is `None` | Global sets `description: "Default"`, model has no description → model gets "Default" |
+| **Parameters** | Simple merge: `{...global, ...per_model}` | Global sets `temperature: 0.7`, model sets `temperature: 0.3` → model gets `0.3` |
+
+The key subtlety: **if a model doesn't explicitly set a parameter, the global default is the only value**. This is especially important for `function_calling` — see the warning below.
+
+:::warning Knowledge Base + Function Calling Interaction
+Setting `function_calling: native` in Global Model Params changes how **all** models handle attached Knowledge Bases. In native mode, model-attached KBs are **not** auto-injected via RAG — instead, the model must autonomously call builtin tools to retrieve knowledge. If a model doesn't explicitly override `function_calling` in its own Advanced Params, it inherits the global value silently.
+
+Additionally, if `file_context` is disabled in Global Model Capabilities, the RAG retrieval handler is skipped for all models that don't explicitly enable it — meaning attached files and KBs produce no results.
+
+If your models' attached Knowledge Bases are not working, check global defaults first. See [Knowledge Base Attached to Model Not Working](/troubleshooting/rag#13-knowledge-base-attached-to-model-not-working) for detailed troubleshooting steps.
+:::
 
 :::tip
-Global defaults are ideal for enforcing organizational policies — for example, disabling code interpreter by default across all models, or setting a consistent temperature for all models.
+Global defaults are ideal for enforcing organizational policies — for example, disabling code interpreter by default across all models, or setting a consistent temperature for all models. However, be cautious with `function_calling` and capability toggles, as they can have unexpected effects on Knowledge Base behavior.
 :::
 
 ## Model Switching in Chat

docs/troubleshooting/rag.mdx

@@ -436,19 +436,30 @@ If you want to prevent a model from accessing **any** knowledge base in native m
 
 ✅ **Solutions (check in order):**
 
-1. **Ensure Built-in Tools are enabled for the model**:
+1. **Check Global Model Settings first**:
+   - Go to **Admin Panel > Settings > Models > ⚙️ (gear icon)**
+   - Expand **Model Parameters** and check if **Function Calling** is set to `native`
+   - If it is, this **overrides all models** that don't explicitly set their own `function_calling` parameter — even if you never intended for a specific model to use native mode
+   - Either change the global setting to `default`, or explicitly set `function_calling` in the per-model **Advanced Params** to override the global value
+   - Also check the **Model Capabilities** section — if **File Context** is disabled globally, RAG won't process files for any model that doesn't explicitly enable it
+
+:::warning Global Settings Override
+The most common cause of this issue is a global `Function Calling: native` setting in **Admin Panel > Settings > Models > ⚙️ > Model Parameters**. This silently applies to **every model** that doesn't explicitly set its own `function_calling` parameter. Per-model settings in **Workspace > Models > Edit > Advanced Params** will override the global default, but only if explicitly set — a model that simply doesn't have `function_calling` configured will inherit the global value.
+:::
+
+2. **Ensure Built-in Tools are enabled for the model** (if using native mode):
    - Go to **Workspace > Models > Edit** for your model
    - Under **Builtin Tools**, make sure the **Knowledge Base** category is enabled (it is by default)
    - If this is disabled, the model has no way to query attached knowledge bases
 
-2. **Add a system prompt hint**:
+3. **Add a system prompt hint** (if using native mode):
    - Some models need explicit guidance to use their tools. Add something like:
      > "When users ask questions, first use list_knowledge_bases to see what knowledge is available, then use query_knowledge_bases to search for relevant information before answering."
 
-3. **Or disable Native Function Calling** for that model:
+4. **Or disable Native Function Calling** for that model:
    - In the model settings, disable Native Function Calling to restore the classic auto-injection RAG behavior from earlier versions
 
-4. **Or use Full Context mode**:
+5. **Or use Full Context mode**:
    - Click on the attached knowledge base and select **"Use Entire Document"**
    - This bypasses RAG entirely and always injects the full content, regardless of native function calling settings