From 393151df5401d123f71b21874cbd72ba94eb18f5 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Fri, 16 Jan 2026 15:31:48 +0100 Subject: [PATCH 1/3] accompanying docs for the PR --- .../chat-features/code-execution/python.md | 12 +++-- .../image-generation-and-editing/usage.md | 11 +++-- docs/features/plugin/tools/development.mdx | 49 +++++++++++++------ docs/features/plugin/tools/index.mdx | 27 +++++++--- docs/features/web-search/agentic-search.mdx | 18 ++++--- 5 files changed, 82 insertions(+), 35 deletions(-) diff --git a/docs/features/chat-features/code-execution/python.md b/docs/features/chat-features/code-execution/python.md index c2a2a05c4..dbb0ef818 100644 --- a/docs/features/chat-features/code-execution/python.md +++ b/docs/features/chat-features/code-execution/python.md @@ -58,9 +58,15 @@ When using **Native function calling mode** with a capable model (e.g., GPT-5, C - **Same image handling**: Base64 image URLs in output are replaced with file URLs; model embeds via markdown **Requirements:** -1. `ENABLE_CODE_INTERPRETER` must be enabled globally -2. Model must have `code_interpreter` capability enabled -3. Model must use **Native** function calling mode (set in model's advanced params) +1. Code Interpreter enabled globally at **Admin Panel > Settings > Code Execution** +2. **Builtin Tools** capability ON for the model (in **Admin Panel > Settings > Models > Capabilities**) +3. Model must have `code_interpreter` capability enabled (in **Admin Panel > Settings > Models > Capabilities**) +4. Model must use **Native** function calling mode (set in model's advanced params) +5. **Code Interpreter toggle** must be ON in the chat interface + +:::tip Enabling Code Interpreter by Default +Go to **Admin Panel > Settings > Models**, select a model, and scroll to **Default Features**. Toggle on **Code Interpreter** so it's pre-enabled for new chats with this model. +::: For more details on builtin tools and native mode, see the [Tool Development Guide](/features/plugin/tools/development#built-in-system-tools-nativeagentic-mode). diff --git a/docs/features/image-generation-and-editing/usage.md b/docs/features/image-generation-and-editing/usage.md index aea079cc5..461b61f55 100644 --- a/docs/features/image-generation-and-editing/usage.md +++ b/docs/features/image-generation-and-editing/usage.md @@ -20,13 +20,18 @@ If your model is configured with **Native Function Calling** (see the [**Central ### How it works: - **Requirements**: - **Image Generation** must be enabled globally in **Admin Panel → Settings → Images** - - The model must have the **Image Generation** capability enabled -- **No Chat Toggle Needed**: With Native Mode, the `generate_image` tool is automatically included when the model has the `image_generation` capability. You don't need to manually toggle it on per chat. + - **Builtin Tools** capability must be enabled for the model (in **Admin Panel > Settings > Models > Capabilities**) + - The model must have the **Image Generation** capability enabled (in **Admin Panel > Settings > Models > Capabilities**) + - **Image Generation toggle** must be ON in the chat interface - **Natural Language**: You can simply ask the model: *"Generate an image of a cybernetic forest."* -- **Action**: If **Native Mode** is active and the model has the capability, it will invoke the `generate_image` tool. +- **Action**: If **Native Mode** is active and all conditions are met, it will invoke the `generate_image` tool. - **Display**: The generated image is displayed directly in the chat interface. - **Editing**: This also supports **Image Editing** (inpainting) via the `edit_image` tool (e.g., *"Make the sky in this image red"*). +:::tip Enabling Image Generation by Default +Go to **Admin Panel > Settings > Models**, select a model, and scroll to **Default Features**. Toggle on **Image Generation** so it's pre-enabled for new chats with this model. +::: + This approach allows the model to "reason" about the prompt before generating, or even generate multiple images as part of a complex request. diff --git a/docs/features/plugin/tools/development.mdx b/docs/features/plugin/tools/development.mdx index a896e12d7..8cc67a801 100644 --- a/docs/features/plugin/tools/development.mdx +++ b/docs/features/plugin/tools/development.mdx @@ -158,8 +158,8 @@ Agentic tool calling requires **high-quality frontier models** to work reliably. | Tool | Purpose | Requirements | |------|---------|--------------| | **Search & Web** | | | -| `search_web` | Search the public web for information. Best for current events, external references, or topics not covered in internal documents. | `ENABLE_WEB_SEARCH` enabled + model `web_search` capability. | -| `fetch_url` | Visits a URL and extracts text content via the Web Loader. | Part of Web Search feature. | +| `search_web` | Search the public web for information. Best for current events, external references, or topics not covered in internal documents. | `ENABLE_WEB_SEARCH` enabled + model `web_search` capability + Web Search toggle ON in chat. | +| `fetch_url` | Visits a URL and extracts text content via the Web Loader. | Same requirements as `search_web`. | | **Knowledge Base** | | | | `list_knowledge_bases` | List the user's accessible knowledge bases with file counts. | Always available. | | `search_knowledge_bases` | Search knowledge bases by name and description. | Always available. | @@ -167,14 +167,14 @@ Agentic tool calling requires **high-quality frontier models** to work reliably. | `view_knowledge_file` | Get the full content of a file from a knowledge base. | Always available. | | `query_knowledge_bases` | Search internal knowledge bases using semantic/vector search. Should be your first choice for finding information before searching the web. | Always available. | | **Image Gen** | | | -| `generate_image` | Generates a new image based on a prompt (supports `steps`). | `ENABLE_IMAGE_GENERATION` enabled + model `image_generation` capability. | -| `edit_image` | Edits an existing image based on a prompt and URL. | `ENABLE_IMAGE_EDIT` enabled + model `image_generation` capability. | +| `generate_image` | Generates a new image based on a prompt (supports `steps`). | `ENABLE_IMAGE_GENERATION` enabled + model `image_generation` capability + Image Generation toggle ON in chat. | +| `edit_image` | Edits an existing image based on a prompt and URL. | `ENABLE_IMAGE_EDIT` enabled + model `image_generation` capability + Image Generation toggle ON in chat. | | **Code Interpreter** | | | -| `execute_code` | Execute Python code in a sandboxed environment. Supports calculations, data analysis, and visualizations. Uses either Pyodide (browser-based) or Jupyter (server-side) depending on configuration. | `ENABLE_CODE_INTERPRETER` enabled + model `code_interpreter` capability. | +| `execute_code` | Execute Python code in a sandboxed environment. Supports calculations, data analysis, and visualizations. Uses either Pyodide (browser-based) or Jupyter (server-side) depending on configuration. | `ENABLE_CODE_INTERPRETER` enabled + model `code_interpreter` capability + Code Interpreter toggle ON in chat. | | **Memory** | | | -| `search_memories` | Searches the user's personal memory/personalization bank. | Memory feature enabled. | -| `add_memory` | Stores a new fact in the user's personalization memory. | Memory feature enabled. | -| `replace_memory_content` | Updates an existing memory record by its unique ID. | Memory feature enabled. | +| `search_memories` | Searches the user's personal memory/personalization bank. | Memory feature enabled globally and for the user. | +| `add_memory` | Stores a new fact in the user's personalization memory. | Memory feature enabled globally and for the user. | +| `replace_memory_content` | Updates an existing memory record by its unique ID. | Memory feature enabled globally and for the user. | | **Notes** | | | | `search_notes` | Search the user's notes by title and content. | `ENABLE_NOTES` enabled. | | `view_note` | Get the full markdown content of a specific note. | `ENABLE_NOTES` enabled. | @@ -203,18 +203,35 @@ Agentic tool calling requires **high-quality frontier models** to work reliably. This table provides a quick reference for developers. For the complete user-facing guide on how to enable and use these tools, see the [**Tool Calling Modes Guide**](/features/plugin/tools#tool-calling-modes-default-vs-native). ::: -:::warning Model Capability vs. Chat Toggle in Native Mode -In **Native Mode**, builtin tools are included based on the **model's capability settings**, not the chat-level toggles. If you: +:::tip Chat Toggle + Model Capability Control in Native Mode +In **Native Mode**, builtin tools are only injected when **all four conditions are met**: -1. Use **Native Mode** function calling -2. **Disable** a capability (e.g., `web_search`) on the model -3. **Manually enable** the feature toggle in the chat (e.g., Web Search toggle) +1. **Feature enabled globally** (e.g., Web Search enabled at **Admin Panel > Settings > Web Search**) +2. **Builtin Tools** capability ON for the model (in **Admin Panel > Settings > Models > Capabilities**) +3. **Feature-specific capability** ON for the model (e.g., `web_search` capability in **Admin Panel > Settings > Models > Capabilities**) +4. **Chat toggle** enabled (e.g., Web Search toggle ON in the chat interface) -The builtin tool will **NOT** be passed to the model—the model cannot call `search_web()` as a function. +This gives you fine-grained control: +- **Admins** can disable features globally or per-model via capabilities +- **Users** can enable/disable tools per-chat via the toggles in the chat interface +- **Filters** (inlet functions) can programmatically control tool availability by modifying the `body["features"]` dict before the request is processed. For example, an inlet filter could set `body["features"]["web_search"] = False` to disable web search tools for specific conditions. See the [Filter Development Guide](/features/plugin/functions/filter#inlet-function-input-pre-processing) and the [Reserved Arguments Reference](/features/plugin/development/reserved-args#body) for details on the `features` dict structure. -**However**, features like Web Search that have RAG-style fallbacks will still work via context injection. The chat toggle triggers the traditional behavior (search results injected into context), just without giving the model autonomous control via tool calling. +**Example:** If Web Search is enabled globally, Builtin Tools is ON, `web_search` capability is ON, but the Web Search toggle is OFF in a specific chat, the model will NOT have access to `search_web()` for that conversation. +::: + +:::info Enabling Features by Default +Tired of manually enabling features for every chat? You can configure defaults: + +**Admin-level (per-model):** +Go to **Admin Panel > Settings > Models**, select a model, and scroll to the **Default Features** section. Toggle on **Web Search**, **Image Generation**, and/or **Code Interpreter**. When users start a new chat with this model, these features will be pre-enabled. + +**User-level:** +Go to **Settings > Interface** and find the **Web Search** setting. Click to toggle it to **Always**. This ensures Web Search is enabled for all your chats regardless of model defaults. -In **Default Mode** (non-native), the chat toggle fully controls the feature via RAG-style injection, independent of capability settings. +**Benefits:** +- Reduces friction for users who always want certain tools available +- Ensures consistent behavior across chats without manual toggling +- Allows admins to set organization-wide defaults per model ::: diff --git a/docs/features/plugin/tools/index.mdx b/docs/features/plugin/tools/index.mdx index fd8f7d1e2..93322f582 100644 --- a/docs/features/plugin/tools/index.mdx +++ b/docs/features/plugin/tools/index.mdx @@ -151,8 +151,8 @@ These models excel at multi-step reasoning, proper JSON formatting, and autonomo | Tool | Purpose | Requirements | |------|---------|--------------| | **Search & Web** | | | -| `search_web` | Search the public web for information. Best for current events, external references, or topics not covered in internal documents. | `ENABLE_WEB_SEARCH` enabled. | -| `fetch_url` | Visits a URL and extracts text content via the Web Loader. | Part of Web Search feature. | +| `search_web` | Search the public web for information. Best for current events, external references, or topics not covered in internal documents. | `ENABLE_WEB_SEARCH` enabled + model `web_search` capability + Web Search toggle ON in chat. | +| `fetch_url` | Visits a URL and extracts text content via the Web Loader. | Same requirements as `search_web`. | | **Knowledge Base** | | | | `list_knowledge_bases` | List the user's accessible knowledge bases with file counts. | Always available. | | `query_knowledge_bases` | Search knowledge bases by semantic similarity to query. Finds KBs whose name/description match the meaning of your query. Use this to discover relevant knowledge bases before querying their files. | Always available. | @@ -161,12 +161,12 @@ These models excel at multi-step reasoning, proper JSON formatting, and autonomo | `search_knowledge_files` | Search files across accessible knowledge bases by filename. | Always available. | | `view_knowledge_file` | Get the full content of a file from a knowledge base. | Always available. | | **Image Gen** | | | -| `generate_image` | Generates a new image based on a prompt (supports `steps`). | `ENABLE_IMAGE_GENERATION` enabled. | -| `edit_image` | Edits an existing image based on a prompt and URL. | `ENABLE_IMAGE_EDIT` enabled.| +| `generate_image` | Generates a new image based on a prompt (supports `steps`). | `ENABLE_IMAGE_GENERATION` enabled + model `image_generation` capability + Image Generation toggle ON in chat. | +| `edit_image` | Edits an existing image based on a prompt and URL. | `ENABLE_IMAGE_EDIT` enabled + model `image_generation` capability + Image Generation toggle ON in chat. | | **Memory** | | | -| `search_memories` | Searches the user's personal memory/personalization bank. Supports an optional `count` parameter to specify how many memories to return (default: 5). | Memory feature enabled. | -| `add_memory` | Stores a new fact in the user's personalization memory. | Memory feature enabled. | -| `replace_memory_content` | Updates an existing memory record by its unique ID. | Memory feature enabled. | +| `search_memories` | Searches the user's personal memory/personalization bank. Supports an optional `count` parameter to specify how many memories to return (default: 5). | Memory feature enabled globally and for the user. | +| `add_memory` | Stores a new fact in the user's personalization memory. | Memory feature enabled globally and for the user. | +| `replace_memory_content` | Updates an existing memory record by its unique ID. | Memory feature enabled globally and for the user. | | **Notes** | | | | `search_notes` | Search the user's notes by title and content. | `ENABLE_NOTES` enabled. | | `view_note` | Get the full markdown content of a specific note. | `ENABLE_NOTES` enabled. | @@ -188,6 +188,19 @@ These models excel at multi-step reasoning, proper JSON formatting, and autonomo Open WebUI automatically detects and stores your timezone when you log in. This allows time-related tools and features to provide accurate local times without any manual configuration. Your timezone is determined from your browser settings. ::: +:::tip Four-Layer Tool Control +Feature-specific tools (Web Search, Image Generation, Code Interpreter) require **all four conditions** to be met: + +1. **Feature enabled globally** (e.g., **Admin Panel > Settings > Web Search / Code Execution / Images**) +2. **Builtin Tools** capability ON for the model +3. **Feature-specific capability** ON for the model (e.g., `web_search`) +4. **Chat toggle** enabled for the feature + +**Enabling Features by Default:** +- **Admins:** Go to **Admin Panel > Settings > Models**, select a model, and scroll to **Default Features**. Toggle on the desired features so they're pre-enabled for new chats. +- **Users:** Go to **Settings > Interface** and set **Web Search** to **Always**. +::: + **Why use these?** It allows for **Deep Research** (searching the web multiple times, or querying knowledge bases), **Contextual Awareness** (looking up previous chats or notes), **Dynamic Personalization** (saving facts), and **Precise Automation** (generating content based on existing notes or documents). #### Disabling Builtin Tools (Per-Model) diff --git a/docs/features/web-search/agentic-search.mdx b/docs/features/web-search/agentic-search.mdx index 5f9f39cbd..2c2c8ca1e 100644 --- a/docs/features/web-search/agentic-search.mdx +++ b/docs/features/web-search/agentic-search.mdx @@ -35,12 +35,18 @@ To unlock these features, your model must support native tool calling and have s * In the same model settings, under **Advanced Parameters**, set **Function Calling** to `Native`. 4. **Use a Quality Model**: Ensure you're using a frontier model with strong reasoning capabilities for best results. -:::tip Model Capability vs. Chat Toggle -In **Native Mode**, the `search_web` and `fetch_url` tools are automatically included based on the model's `web_search` capability setting. The chat toggle is not required. - -In **Default Mode** (non-native), the chat toggle still controls whether web search is performed via RAG-style injection. - -**Important**: If you disable the `web_search` capability on a model but use Native Mode, the tools won't be available even if you manually toggle Web Search on in the chat. +:::tip Four-Layer Tool Control +In **Native Mode**, the `search_web` and `fetch_url` tools require **all four conditions** to be met: +1. **Feature enabled globally**: Web Search enabled at **Admin Panel > Settings > Web Search** +2. **Builtin Tools** capability ON for the model (in **Admin Panel > Settings > Models > Capabilities**) +3. **Model capability**: `web_search` capability ON (in **Admin Panel > Settings > Models > Capabilities**) +4. **Chat toggle**: Web Search toggle ON in the chat interface + +This gives both admins and users fine-grained control. Inlet filters can also programmatically control tool availability by modifying `body["features"]`—see the [Filter Development Guide](/features/plugin/functions/filter) for details. + +**Enabling Web Search by Default:** +- **Admins:** Go to **Admin Panel > Settings > Models**, select a model, and scroll to **Default Features**. Toggle on **Web Search** so it's pre-enabled for all new chats with this model. +- **Users:** Go to **Settings > Interface** and set **Web Search** to **Always**. ::: ## How Native Tools Handle Data (Agentic Mode) From 38bb1670e5e6ea11895751bfdf0235d19299c0e0 Mon Sep 17 00:00:00 2001 From: Classic298 <27028174+Classic298@users.noreply.github.com> Date: Sat, 17 Jan 2026 10:58:48 +0100 Subject: [PATCH 2/3] Update index.mdx --- docs/features/plugin/tools/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/features/plugin/tools/index.mdx b/docs/features/plugin/tools/index.mdx index 779e4eddc..3ba21f616 100644 --- a/docs/features/plugin/tools/index.mdx +++ b/docs/features/plugin/tools/index.mdx @@ -150,8 +150,8 @@ These models excel at multi-step reasoning, proper JSON formatting, and autonomo | Tool | Purpose | |------|---------| -| **Search & Web** | *Requires `ENABLE_WEB_SEARCH` + model `web_search` capability + chat toggle ON.* | -| `search_web` | Search the public web for information. Best for current events, external references, or topics not covered in internal documents. | +| **Search & Web** | | +| `search_web` | *Requires `ENABLE_WEB_SEARCH` + model `web_search` capability + chat toggle ON.* – Search the public web for information. Best for current events, external references, or topics not covered in internal documents. | | `fetch_url` | Visits a URL and extracts text content via the Web Loader. | | **Knowledge Base** | *Always available.* | | `list_knowledge_bases` | List the user's accessible knowledge bases with file counts. | From 512ed33d5fb24e6503dfc8eb8a8ff0842b4256cd Mon Sep 17 00:00:00 2001 From: Classic298 <27028174+Classic298@users.noreply.github.com> Date: Sat, 17 Jan 2026 10:59:44 +0100 Subject: [PATCH 3/3] Update agentic-search.mdx --- docs/features/web-search/agentic-search.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/web-search/agentic-search.mdx b/docs/features/web-search/agentic-search.mdx index 2c2c8ca1e..74b7ba471 100644 --- a/docs/features/web-search/agentic-search.mdx +++ b/docs/features/web-search/agentic-search.mdx @@ -36,7 +36,7 @@ To unlock these features, your model must support native tool calling and have s 4. **Use a Quality Model**: Ensure you're using a frontier model with strong reasoning capabilities for best results. :::tip Four-Layer Tool Control -In **Native Mode**, the `search_web` and `fetch_url` tools require **all four conditions** to be met: +In **Native Mode**, the `search_web` tool requires **all four conditions** to be met: 1. **Feature enabled globally**: Web Search enabled at **Admin Panel > Settings > Web Search** 2. **Builtin Tools** capability ON for the model (in **Admin Panel > Settings > Models > Capabilities**) 3. **Model capability**: `web_search` capability ON (in **Admin Panel > Settings > Models > Capabilities**)