What are Tools?

⚠️ Critical Security Warning

Workspace Tools and Functions execute arbitrary Python code on your server. Only install from trusted sources, review code before importing, and restrict Workspace access to trusted administrators only. Granting a user the ability to create or import Tools is equivalent to giving them shell access to the server. For full details, see the Plugin Security Warning.

⚙️ Tools are the various ways you can extend an LLM's capabilities beyond simple text generation. When enabled, they allow your chatbot to do amazing things like search the web, scrape data, generate images, talk back using AI voices, and more.

Because there are several ways to integrate "Tools" in Open WebUI, it's important to understand which type you are using.

---

Tooling Taxonomy: Which "Tool" are you using?

🧩 Users often encounter the term "Tools" in different contexts. Here is how to distinguish them:

Type	Location in UI	Best For...	Source
Native Features	Admin/Settings	Core platform functionality (these are the built-in system tools)	Built-in to Open WebUI
Workspace Tools	Workspace > Tools	User-created or community Python scripts, the most powerful, least restricted option	Community Library
Native MCP (HTTP)	Settings > Connections	Standard MCP servers reachable via HTTP/SSE	External tool server
MCP via Proxy (MCPO)	Settings > Connections	Local stdio-based MCP servers (e.g., Claude Desktop tools)	External tool server (via MCPO Adapter)
OpenAPI Servers	Settings > Connections	Standard REST/OpenAPI web services	External tool server

The last three (MCP HTTP, MCPO, OpenAPI) are all external tool servers: the tool code runs on a separate process or machine and Open WebUI calls it over HTTP. Native Features are the built-in system tools that ship with Open WebUI. Workspace Tools are Python that runs in-process; for the most demanding use cases they are by far the most capable option with the fewest limitations (see below).

1. Native Features (Built-in)

These are deeply integrated into Open WebUI and generally don't require external scripts.

• Web Search: Integrated via engines like SearXNG, Google, or Tavily.
• URL Fetching: Extract text content directly from websites using # or native tools.
• Image Generation: Integrated with the OpenAI images API, ComfyUI, or Automatic1111.
• Memory: The ability for models to remember facts about you across chats.
• RAG (Knowledge): The ability to query uploaded documents (#).

In Native Mode, these features are exposed as Tools that the model can call independently.

2. Workspace Tools (Custom Plugins)

These are Python scripts that run directly within the Open WebUI environment. For the most demanding use cases, Workspace Tools are by far the most powerful option with the fewest limitations: they run in-process with full access to Python, the open_webui codebase, and the request context, so there is very little they can't do (see Under the Hood for the full extent). The external tool servers above are more constrained: they only see what you pass over HTTP and can't reach into Open WebUI itself.

• Capability: Can do anything Python can do (web scraping, complex math, API calls), and hold secrets (API keys) entirely server-side so neither the user nor the model can read them.
• Access: Managed via the Workspace menu.
• Safety: Always review code before importing, as these run on your server.
• ⚠️ Security Warning: Normal or untrusted users should not be given permission to access the Workspace Tools section. This access allows a user to upload and execute arbitrary Python code on your server, which could lead to a full system compromise.

3. MCP (Model Context Protocol)

🔌 MCP is an open standard that allows LLMs to interact with external data and tools.

• Native HTTP MCP: Open WebUI can connect directly to any MCP server that exposes an HTTP/SSE endpoint.
• MCPO (Proxy): Most community MCP servers use stdio (local command line). To use these in Open WebUI, you use the MCPO Proxy to bridge the connection.

4. OpenAPI / Function Calling Servers

Generic web servers that provide an OpenAPI (.json or .yaml) specification. Open WebUI can ingest these specs and treat every endpoint as a tool.

Open Terminal, a separate code-execution integration

Beyond the tool types above, Open WebUI also integrates with Open Terminal: an always-on, isolated Docker container that gives a model a real shell and filesystem. Once connected, it exposes its own set of built-in tools (run_command, read_file, write_file, grep_search, glob_search, process management, and more) that the model can call directly, effectively a sandboxed code-execution and file-handling environment, distinct from the per-message Code Interpreter tool. See the Open Terminal documentation for setup, multi-user, and security considerations.

---

How to Install & Manage Workspace Tools

📦 Workspace Tools are the most common way to extend your instance with community features.

1. Go to Community Tool Library
2. Choose a Tool, then click the Get button.
3. Enter your Open WebUI instance’s URL (e.g. http://localhost:3000).
4. Click Import to WebUI.

Safety Tip

Never import a Tool you don’t recognize or trust. These are Python scripts and might run unsafe code on your host system. Crucially, ensure you only grant "Tool" permissions to trusted users, as the ability to create or import tools is equivalent to the ability to run arbitrary code on the server.

---

How to Use Tools in Chat

🔧 Once installed or connected, here’s how to enable them for your conversations:

Option 1: Enable on-the-fly (Specific Chat)

While chatting, click the Integrations icon in the input area (the four-diamond icon next to the ➕ button), then select Tools. You’ll see a list of available Tools, and you can toggle them on specifically for that session.

Option 2: Enable by Default (Global/Model Level)

1. Go to Workspace ➡️ Models.
2. Choose the model you’re using and click the ✏️ edit icon.
3. Scroll to the Tools section.
4. ✅ Check the Tools you want this model to always have access to by default.
5. Click Save.

For models that support it, Native tool calling mode (see Tool Calling Modes below) lets the model itself decide which of the attached tools to call on each turn. This replaces the older prompt-injection "auto-tool" filter approach and is the recommended way to let the model auto-select tools.

Attached Tools Still Require User Access

Attaching a workspace tool to a model does not bypass access control. When a user chats with the model, Open WebUI checks whether that specific user has read access to each attached tool. Tools the user cannot access are silently skipped, so the model won't be able to call them.

Example scenario: An admin creates a private tool and attaches it to a model shared with all users. Regular users chatting with this model will not have the tool available because they don't have read access to the tool itself.

Solution: Make sure users who need the model's tools also have read access to each tool (via access grants, group permissions, or by making the tool public). The "Workspace → Tools" permission controls whether users can create and manage tools; it does not affect whether model-attached tools work for them.

---

Tool Calling Modes: Native vs. Legacy

Native is the default as of v0.10.0; "Legacy" (formerly "Default") is the unsupported opt-out

Native (Agentic) Mode is now the default. As of v0.10.0, every chat and model that has not explicitly chosen a tool-calling mode runs Native, which relies on the model's built-in function-calling support. The old prompt-injection approach, previously called Default, is now renamed Legacy. It is the explicit opt-out and remains unsupported: no feature work, no bug fixes, no built-in system tools, and incompatible with modern Open WebUI features (Agentic Research, Interleaved Thinking, the built-in Memory/Notes/Knowledge/Channels tools, and web-search/image-gen/code-interpreter tool injection).

Breaking change: if any of your models depended on the old prompt-based behavior, they now run Native unless you switch them back to Legacy, per chat, per model, or globally in your default model parameters. If a model struggles with Native, the right fix is a stronger tool-calling model, not falling back to Legacy.

Open WebUI exposes the setting in Model Settings → Advanced Params → Function Calling: Native Mode (Agentic Mode), the default and only supported mode, and Legacy Mode (formerly Default), the prompt-based opt-out kept only for backward compatibility.

🔴 Legacy Mode (Prompt-based, formerly "Default")

Unsupported

Legacy Mode (the option previously labeled Default) is no longer supported. It is documented here for reference only. New and existing deployments should use Native Mode. Bug reports, feature requests, and support questions about Legacy Mode behavior will not be actioned.

In Legacy Mode, Open WebUI manages tool selection by injecting a long prompt template that guides the model to output a tool request in a bespoke format. It was a reasonable approach in 2023; it has been obsolete since mainstream providers and open-weights models gained proper function-calling APIs.

Why it is legacy:

• Breaks KV cache. The injected prompt changes every turn, preventing LLM engines from reusing cached key-value pairs. Every message pays the full prefill cost again.
• Higher latency and token cost. Bulky tool-description prompts on every turn.
• Unreliable for multi-step chaining. Parsing natural-language tool requests is fragile compared to structured tool calls.
• Cannot access built-in system tools. Memory, Notes, Knowledge, Channels, Agentic Research, Interleaved Thinking, and the tool-injected Web Search / Image Generation / Code Interpreter features are Native-only.
• Does not support modern capabilities. Every new feature shipped since 2024 targets Native Mode.

How to switch all models to Legacy

Since v0.10.0 Native is the default, so you never need to "turn Native on". The only tool-calling switch you might need to make is the reverse: forcing Legacy back on for models that depended on the old prompt-injection behavior and cannot be moved to a stronger Native-capable model. Set Function Calling to Legacy at whichever scope you need (mirrors the Native controls below):

1. Every model at once (global default, fastest):
   • Navigate to Settings → Admin → AI → Models.
   • Click the Model Defaults button at the top of the models list to open global model parameters (they apply to every model, current and future, unless a specific model overrides them).
   • There, set Function Calling to Legacy, then Save. Every model that has not set its own value now runs Legacy. You do not need to edit them one by one.
2. Per-Model Override: edit a specific model in Settings → Admin → AI → Models and set Function Calling to Legacy under Model Params → Advanced Params. Overrides the global default for that model only.
3. Per-Chat Override: inside a chat, open Chat Controls → Advanced Params and set Function Calling to Legacy for that chat only.

Prefer environment variables? Use DEFAULT_MODEL_PARAMS

To move an entire instance to Legacy through env vars, set the same global default with:

DEFAULT_MODEL_PARAMS: '{"function_calling": "legacy"}'

function_calling is a key inside DEFAULT_MODEL_PARAMS; there is no standalone FUNCTION_CALLING_MODE (or similar) variable. The only value that changes behavior is "legacy"; leaving it unset (or "native") keeps the default, Native.

🟢 Native Mode (Agentic Mode / System Function Calling): The Only Supported Mode

Native Mode (also called Agentic Mode) leverages the model's built-in capability to handle tool definitions and return structured tool calls (JSON). It is the default as of v0.10.0 and the recommended mode for all models that support it, which includes the vast majority of modern models (2024+).

Model Quality Matters

Agentic tool calling needs a model that is current, not one that is expensive. Very small or older models often struggle with the multi-step reasoning and strict state management involved, and may produce malformed JSON. A cheap, fast, current model is plenty: GPT-5.6 Luna, Gemini 3.5 Flash-Lite, MiniMax M3, DeepSeek V4 Flash, or locally Qwen 3.6 27B or Muse Glimmer 30B.

Why use Native Mode (Agentic Mode)?

• Speed & Efficiency: Lower latency as it avoids bulky prompt-based tool selection.
• KV Cache Friendly: Tool definitions are sent as structured parameters (not injected into the prompt), so they don't invalidate the KV cache between turns. This can significantly reduce latency and token costs.
• Reliability: Higher accuracy in following tool schemas (with quality models).
• Multi-step Chaining: Essential for Agentic Research and Interleaved Thinking where a model needs to call multiple tools in succession.
• Autonomous Decision-Making: Models can decide when to search, which tools to use, and how to combine results.
• System Tools: Only Native Mode unlocks the built-in system tools (memory, notes, knowledge, channels, etc.).

How to Enable Native Mode (Agentic Mode)

Native Mode is the default as of v0.10.0, so new and existing models use it unless they are explicitly set to Legacy. You can still set Function Calling explicitly (to pin Native, or to switch a model to Legacy) at these levels:

1. Pin Native for Every Model (optional, since Native is already the default):
   • Navigate to Settings → Admin → AI → Models.
   • Click the Model Defaults button at the top of the models list. This opens global model parameters, which apply to every model in your instance (current and future) unless a specific model overrides them.
   • Under Model Parameters, set Function Calling to Native.
   • Save. This only re-asserts the existing default; you would normally leave it unset. Use it if you want the value pinned explicitly rather than relying on the default.
2. Per-Model Override:
   • In Settings → Admin → AI → Models, pick a specific model and click its edit button.
   • Under Model Params, expand Advanced Params and set Function Calling to Native. This value overrides the global default for that model only.
   • Use this when a specific model needs different parameters; otherwise prefer the global setting.
3. Per-Chat Override:
   • Inside a chat, open Chat Controls (right sidebar).
   • Under Advanced Params, set Function Calling to Native. Applies to that chat only.

Set any parameter globally, once, for all models

The global model parameters panel (the Model Defaults button in Settings → Admin → AI → Models) lets you configure any model parameter (function_calling, temperature, top_p, max_tokens, etc.) once, for every model in your Open WebUI instance, current and future, unless a specific model overrides it. For tool calling specifically you rarely need it: Native is already the default. The one tool-calling switch you would set here is Function Calling = Legacy, to move a whole instance back to Legacy (see How to switch all models to Legacy).

Prefer environment variables? Use DEFAULT_MODEL_PARAMS

If you configure your instance entirely through env vars, DEFAULT_MODEL_PARAMS sets the same global defaults. function_calling is a key inside it; there is no standalone FUNCTION_CALLING_MODE (or similar) variable. Because Native is the default, the only value worth setting here is "legacy" (to move the whole instance to Legacy, per above):

DEFAULT_MODEL_PARAMS: '{"function_calling": "legacy"}'

Leaving function_calling unset (or "native") keeps the default, Native.

Model Requirements & Caveats

Minimum model tier (not a maintained list)

Reliable agentic tool calling does not require a frontier model — it requires a current one. Any of these is a solid minimum, each verified working at the time of writing:

• GPT-5.6 Luna (OpenAI) — cheap, fast, and genuinely strong at tool calling
• Gemini 3.5 Flash-Lite or Gemini 3.1 Flash-Lite (Google)
• MiniMax M3
• DeepSeek V4 Flash
• Muse Glimmer 30B or Qwen 3.6 27B (local, open-weight)

This list is not continuously updated — chasing every model release is impossible and adds no value. Use whatever current model your provider offers; you don't need the latest and greatest, just something recent.

• Capable Local Models: Open-weight models built for agentic work (e.g., Muse Glimmer 30B, Qwen 3.6 27B, Gemma 4 12B, gpt-oss 120B) work well with Native Mode. Muse Glimmer in particular is Apache 2.0, runs agentic loops reliably on a single 24 GB GPU, and is a good default for local tool calling.
• Small Local Models: Small local models (under ~30B parameters) often produce malformed JSON or fail multi-step tool chains even in Native Mode. The fix is to use a stronger model for tool-calling workloads, not to fall back to Legacy Mode (Legacy is unsupported). If your hardware forces you to use a small model, accept that tool calling will be unreliable at this tier, or offload only tool-using conversations to a cloud model.

Known Model-Specific Issues

DeepSeek V3.2 Function Calling Issues

DeepSeek V3.2 has known issues with native function calling that cause reproducible failures. Despite being a 600B+ parameter model, it often outputs malformed tool calls.

The Problem: DeepSeek V3.2 was trained using a proprietary format called DSML (DeepSeek Markup Language) for tool calls. When using native function calling, the model sometimes outputs raw DSML/XML-like syntax instead of proper JSON:

• <functionInvoke name="fetch_url"> instead of valid JSON
• <function_calls> / </function_calls> tags in content
• Garbled hybrid text like prominentfunction_cinvoke name="search_parameter

Why it happens: This is heavily model-dependent behavior induced during DeepSeek's fine-tuning process. DeepSeek chose to train their model on DSML rather than standard OpenAI-style JSON tool calls. While inference providers (VertexAI, OpenRouter, etc.) attempt to intercept DSML blocks and convert them to OpenAI-style JSON, this translation layer is unreliable under certain conditions (streaming, high temperature, high concurrency, multi-turn conversations). The primary responsibility lies with DeepSeek for using a non-standard format that requires fragile translation.

Known contributing factors:

• Higher temperature values correlate with more malformed output
• Multi-round conversations (6-8+ turns) can cause the model to stop calling functions entirely
• Complex multi-step workflows (15-30 tool calls) may cause "schema drift" where argument formats degrade

Workarounds:

• Use a different model for agentic workloads. GPT-5.6 Luna, Claude Sonnet 5, Gemini 3.5 Flash-Lite, MiniMax M3, and DeepSeek V4 Flash are all reliable in Native Mode and are the recommended choice when DeepSeek V3.2 misbehaves.
• Lower temperature when using tool calling with DeepSeek V3.2.
• Limit multi-round tool-calling sessions.

Legacy Mode is not a supported workaround even for DeepSeek; it is unsupported and will not be extended to cover this case. This is a DeepSeek model/API issue, not an Open WebUI issue. Open WebUI correctly sends tools in standard OpenAI format; the malformed output originates from DeepSeek's non-standard internal DSML format.

Feature	Legacy Mode (formerly Default)	Native Mode (Default, Only Supported)
Status	❌ Legacy, no longer supported	✅ Required, all models should use this
Latency	Medium/High	Low
KV Cache	❌ Breaks cache on every turn	✅ Cache-friendly
Model Compatibility	Any text model (obsolete concern)	Every mainstream model since 2024
Logic	Prompt-injection parsed by Open WebUI	Structured tool calls via provider API
System Tools	❌ Not available	✅ Full access (Memory, Notes, Knowledge, Channels, Web Search, Image Gen, Code Interpreter)
Agentic Research / Interleaved Thinking	❌ Unsupported	✅ Supported
Complex Chaining	⚠️ Unreliable	✅ Excellent
Future development	❌ None	✅ All new features target this mode

Built-in System Tools (Native/Agentic Mode)

🛠️ These are the Builtin Tools (the capability name shown in the Model Editor). When Native Mode (Agentic Mode) is enabled, Open WebUI automatically injects powerful system tools. This unlocks truly agentic behaviors where any current tool-calling model (GPT-5.6 Luna, Claude Sonnet 5, Gemini 3.5 Flash-Lite, MiniMax M3, or Muse Glimmer 30B locally) can perform multi-step research, explore knowledge bases, or manage user memory autonomously.

Tool	Purpose
Search & Web	Requires ENABLE_WEB_SEARCH enabled AND per-chat "Web Search" toggle enabled.
search_web	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	Requires per-model "Knowledge Base" category enabled (default: on). Which tools are injected depends on whether the model has attached knowledge; see note below.
list_knowledge	List attached knowledge (KBs, files, notes). Start here when attachments exist.
list_knowledge_bases	List accessible knowledge bases with file counts.
query_knowledge_bases	Semantic search over KB names/descriptions to find the right KB.
search_knowledge_bases	Text search over KB names/descriptions.
query_knowledge_files	Search file contents via the RAG retrieval pipeline (hybrid + rerank when enabled). Main tool for finding answers in docs.
search_knowledge_files	Search files by filename.
grep_knowledge_files	Exact text / regex search across knowledge file content. Returns matching lines with line numbers. Complements query_knowledge_files (semantic) when you need literal matches.
view_file	Read a user-accessible file by ID with character pagination (offset, max_chars) or line range (start_line, end_line, optional line_numbers).
view_knowledge_file	Read a knowledge-base file by ID with pagination (offset, max_chars).
kb_exec (opt-in)	Filesystem-style command interface for knowledge bases (ls, tree, cat, head, tail, sed, grep, find, wc, stat, with pipe support). Directory-aware: ls docs/, tree, grep "x" docs/, and path-based file refs (docs/api/auth.md). Replaces the discovery/read tools above when ENABLE_KB_EXEC is set.
Files	Requires per-model "Files" category enabled, the model's File Upload capability on with File Context off, the user's chat.file_upload permission, and at least one file attached to the current chat. Covers files the user attached to the conversation, not knowledge bases.
list_chat_files	List the files attached to the current chat, with each file's ID, filename, content type and size.
query_chat_files	Semantic / RAG search across the attached files, or one file when given its ID. Results are returned as cited chunks.
grep_chat_files	Exact text / regex search across the attached files, returning matching lines with file IDs and line numbers, or just per-file counts. Capped at 50 matches by default, the same KNOWLEDGE_GREP_MAX_MATCHES limit the knowledge greps use.
view_file	Read one of the attached files by ID, with character pagination or a line range. Same tool, and the same VIEW_FILE_DEFAULT_MAX_CHARS / VIEW_FILE_MAX_CHARS sizing, as when it reads a knowledge file.
Image Gen	Requires image generation enabled (per-tool) AND per-chat "Image Generation" toggle enabled.
generate_image	Generates a new image based on a prompt. Requires ENABLE_IMAGE_GENERATION.
edit_image	Edits existing images based on a prompt and image URLs. Requires ENABLE_IMAGE_EDIT.
Code Interpreter	Requires ENABLE_CODE_INTERPRETER enabled (default: on) AND per-chat "Code Interpreter" toggle enabled.
execute_code	Executes code in a sandboxed environment and returns the output.
Memory	Requires Memory feature enabled AND per-model "Memory" category enabled (default: on).
search_memories	Searches the user's personal memory/personalization bank.
list_memory_paths	Lists the paths memories are filed under.
read_memory_path	Reads the memories stored under one path.
list_memories	Lists all stored memories for the user.
update_memory	Applies a batch of add, replace, move or remove operations.
add_memory	Stores a new fact in the user's personalization memory.
replace_memory_content	Updates an existing memory record by its unique ID.
delete_memory	Deletes a memory by its ID.
Notes	Requires ENABLE_NOTES AND per-model "Notes" category enabled (default: on) AND the user's features.notes permission. Inside a note-attached chat these three checks are skipped and the note tools are always injected; see the note below.
search_notes	Search the user's notes by title and content.
view_note	Get the full markdown content of a specific note.
write_note	Create a new private note for the user.
replace_note_content	Update an existing note, replacing the whole content or applying range edits to part of it.
Chat History	Requires per-model "Chat History" category enabled (default: on).
search_chats	Simple text search across chat titles and message content. Returns matching chat IDs and snippets.
view_chat	Reads and returns the full message history of a specific chat by ID.
Channels	Requires ENABLE_CHANNELS AND per-model "Channels" category enabled (default: on).
search_channels	Find public or accessible channels by name/description.
search_channel_messages	Search for specific messages inside accessible channels.
view_channel_message	View a specific message or its details in a channel.
view_channel_thread	View a full message thread/replies in a channel.
Task Management	Requires per-model "Task Management" category enabled (default: on).
create_tasks	Create a structured task checklist for the current chat. Called once at the start of multi-step work to define all steps.
update_task	Update the status of a single task by id (pending, in_progress, completed, cancelled). Called after finishing each step.
Automations	Requires per-model "Automations" category enabled (default: on) AND ENABLE_AUTOMATIONS enabled AND user has features.automations permission (admins always pass).
create_automation	Create a scheduled automation with a name, prompt, and RRULE schedule, optionally filed into a folder. Uses the current chat model.
update_automation	Update an existing automation's name, prompt, schedule, folder, or model.
list_automations	List the user's scheduled automations with status, schedule, and next runs.
toggle_automation	Pause or resume a scheduled automation.
delete_automation	Delete a scheduled automation and all its run history.
Calendar	Requires per-model "Calendar" category enabled (default: on) AND ENABLE_CALENDAR enabled AND user has features.calendar permission (admins always pass).
search_calendar_events	Search calendar events by text and/or date range across all accessible calendars.
create_calendar_event	Create a new event on the user's default or specified calendar.
update_calendar_event	Update an existing event's title, time, description, location, or cancel it.
delete_calendar_event	Delete a calendar event permanently.
Skills	Requires at least one skill to be attached to the model via Workspace or Settings > Admin > AI > Models → Edit → Skills. The model receives a summary of attached skills in its system prompt and can call view_skill to load full instructions on demand. No separate builtin tools category checkbox is needed; attaching a skill is the only requirement.
view_skill	Load the full instructions of a skill by name. The tool is injected when skills are attached; resolving a skill still follows normal ownership/access-grant checks.
Time Tools	Requires per-model "Time & Calculation" category enabled (default: on).
get_current_timestamp	Get the current UTC Unix timestamp and ISO date.
calculate_timestamp	Calculate relative timestamps (e.g., "3 days ago").
Sub-agents	Requires ENABLE_SUBAGENTS enabled (default: off) AND per-model "Sub-agents" category enabled (default: on). Never injected into a sub-agent itself, or for direct connections. This category gates timer as well; there is no separate Timers category.
delegate_task	Delegate a focused task to a parallel sub-agent running the same model and tools, and return its result. See Sub-agents.
timer	Set a one-shot timer that sends a prompt back into this chat when it fires, producing a new reply. See Timers.
Notifications	Requires ENABLE_USER_WEBHOOKS enabled (default: off) AND the user holding the features.webhooks permission (admins always pass) AND per-model "Notifications" category enabled (default: on).
notify	Send a notification to one of the user's configured webhook targets. See Notifications.

Attached Chat Files

The Files category is the agentic alternative to putting an uploaded file's text straight into the prompt. It is injected only when the model uploads files but does not use file context — when file context is on, the content is already in the conversation and the tools would be redundant — and only while the chat actually has attachments.

The model then works the file the way it works a knowledge base: list_chat_files to see what is there, query_chat_files for meaning, grep_chat_files for literal strings and line numbers, view_file to read a passage. Chunks returned by query_chat_files are rendered as citations, the same as knowledge results. Every file is still re-checked against the user's own access before it is read, so an attachment they can no longer open is skipped rather than searched.

Images in Tool Results

A tool can return images as well as text — generate_image and edit_image do, and so can a custom tool. How that reaches the model depends on the provider:

• On the Responses API, the image rides along inside the tool result, where it belongs.
• On Chat Completions, a tool message may only carry text. The image is therefore split off: the tool result is delivered as plain text, and the images that came with it follow in a short user message that hands them to the model for analysis.

The effect is that a model on a Chat Completions provider can actually look at what a tool produced — generate an image and then critique or edit it — instead of receiving a result it cannot open. Nothing extra is shown in the conversation; the images were already rendered from the tool result itself.

Knowledge Tool Availability (At a Glance)

Use this quick matrix instead of memorizing per-row caveats.

Tool	Model has attached knowledge	Model has no attached knowledge
list_knowledge	✅	❌
list_knowledge_bases	❌	✅
search_knowledge_bases	❌	✅
query_knowledge_bases	❌	✅
search_knowledge_files	✅ (auto-scoped)	✅ (all accessible KBs)
query_knowledge_files	✅ (auto-scoped)	✅
grep_knowledge_files	✅ (auto-scoped)	✅
view_file	✅ (when attached items include files/collections)	❌
view_knowledge_file	✅ (when attached items include files/collections)	✅
view_note	✅ (when attached items include notes)	❌

Quick rule: list_knowledge and list_knowledge_bases are mutually exclusive.

"Attached knowledge" is not only what the model carries. Three sources are pooled, de-duplicated, and treated the same by the matrix above:

• knowledge attached to the model in its editor,
• knowledge attached to the folder the chat sits in,
• knowledge bases and notes attached to the chat itself — counted only when the model's File Context capability is off, since with it on the content is already in the conversation.

When the Knowledge Base category is enabled and any of these are present, the model's system prompt gains an <attached_knowledge> block listing each item's type, ID, name, and which of the three it came from. This is a table of contents, not the content: it tells the model what it may reach for and gives it the IDs to pass to query_knowledge_files and friends, so it can scope a search to one knowledge base instead of guessing or searching everything.

kb_exec replaces the matrix when enabled

When ENABLE_KB_EXEC is set, Open WebUI injects kb_exec instead of the file-oriented tools listed above. Still injected alongside it: query_knowledge_files (always), view_note (when notes are attached), and query_knowledge_bases + search_knowledge_bases (when no KB is attached). The model interacts with files through familiar shell commands. See the Knowledge feature page for details.

Tool Reference

Tool	Parameters	Output
Search & Web
search_web	query (required), count (default: admin-configured WEB_SEARCH_RESULT_COUNT; capped at admin maximum when provided)	Array of {title, link, snippet}
fetch_url	url (required)	Plain text content, untruncated unless the admin sets WEB_FETCH_MAX_CONTENT_LENGTH
Knowledge Base
list_knowledge	knowledge_id (optional, pages into one base's files), skip (default: 0), count (default: 50, capped at 200)	{knowledge_bases: [{id, name, description, file_count, files: [{id, filename}]}], files: [{id, filename, updated_at}], notes: [{id, title}]}, and with knowledge_id set the base also carries files_skip, files_count, files_total and has_more
list_knowledge_bases	count (default: 10), skip (default: 0)	Array of {id, name, description, file_count}
query_knowledge_bases	query (required), count (default: 5)	Array of {id, name, description} by similarity
search_knowledge_bases	query (required), count (default: 5), skip (default: 0)	Array of {id, name, description, file_count}
query_knowledge_files	query (required), knowledge_ids (optional), count (default: 5)	Array of chunks like {content, source, file_id, distance?}; note hits include {note_id, type: "note"}
search_knowledge_files	query (required), knowledge_id (optional), count (default: 5), skip (default: 0)	Array of {id, filename, knowledge_id, knowledge_name}
grep_knowledge_files	pattern (required; regex auto-detected), file_id (optional, single-file mode), case_insensitive (default: false), count_only (default: false)	Matching lines with file IDs, filenames, and 1-indexed line numbers (capped at 50 matches by default, see KNOWLEDGE_GREP_MAX_MATCHES)
view_file	file_id (required), offset (default: 0), max_chars (default: 10000, cap: 100000; both configurable), line_numbers (default: false), start_line / end_line (optional; line-based addressing overrides offset/max_chars)	{id, filename, content, updated_at, created_at}, includes truncated, total_chars, next_offset when paginated, or total_lines, showing_lines, next_start_line in line mode
view_knowledge_file	file_id (required), offset (default: 0), max_chars (default: 10000, cap: 100000; both configurable)	{id, filename, content, knowledge_id, knowledge_name}, includes pagination metadata when truncated
kb_exec	command (required), a filesystem-style command: ls (root) / ls <dir>/ / ls -a (flat with paths), tree / tree <dir>/, cat -n <file>, head -N <file>, tail -N <file>, sed -n '<a>,<b>p' <file>, grep [-i|-l|-c] "<pattern>" [<dir>/|<file>|*.ext], find [<dir>/] "<glob>", wc <file>, stat <file>; supports pipes (grep "auth" | head -5); files referenced by path (docs/api/auth.md), filename, or file ID	Plain text command output (matches/listing/tree/file content as appropriate)
Image Gen
generate_image	prompt (required)	{status, message, images}, auto-displayed
edit_image	prompt (required), image_urls (required)	{status, message, images}, auto-displayed
Code Interpreter
execute_code	code (required)	{status, stdout, stderr, result}
Memory
search_memories	query (default: ""), count (default: 5), type (default: all), path, memory_id	Array of {id, type, path, content, created_at, updated_at}
list_memory_paths	query (default: ""), count (default: 100), type (default: all)	The paths memories are filed under
read_memory_path	path (required), count (default: 50), type (default: all), include_children (default: true)	The memories stored under that path
update_memory	operations (required, a list of add, replace, move or remove entries)	Per-operation results
add_memory	content (required), type (default: user), path	{status: "success", id, type, path}
replace_memory_content	memory_id (required), content (required), type, path	{status: "success", id, type, path, content}
delete_memory	memory_id (required)	{status: "success", message}
list_memories	None	Array of {id, type, path, content, created_at, updated_at}
Notes
search_notes	query (required), count (default: 5), start_timestamp, end_timestamp	Array of {id, title, snippet, updated_at}
view_note	note_id (required)	{id, title, content, updated_at, created_at}
write_note	title (required), content (required)	{status: "success", id}
replace_note_content	note_id (required), content (optional; the new markdown for a whole-note update), operations (optional; range edits, each {"action": "replace", "content": ...} or {"action": "replace_range", "start", "end", "content", "expected"}), title (optional)	{status: "success", id, title, updated_at, applied_operation_count}. Errors carry a machine-readable code (not_found, write_access_denied, invalid_range, range_out_of_bounds, expected_mismatch, overlapping_operations, content_required, …)
Chat History
search_chats	query (required), count (default: 5), start_timestamp, end_timestamp	Array of {id, title, snippet, updated_at}
view_chat	chat_id (required)	{id, title, messages: [{role, content}]}
Channels
search_channels	query (required), count (default: 5)	Array of {id, name, description, type}
search_channel_messages	query (required), count (default: 10), start_timestamp, end_timestamp	Array of {channel_id, channel_name, message_id, content_snippet, is_thread_reply, parent_id, created_at}
view_channel_message	message_id (required)	{id, content, user_name, created_at, reply_count}
view_channel_thread	parent_message_id (required)	{channel_id, channel_name, thread_id, message_count, messages: [...]}
Task Management
create_tasks	tasks (required): list of {content (required), status (default: pending), id (optional, auto-generated)}	{tasks: [...], summary: {total, pending, in_progress, completed, cancelled}}
update_task	id (required), status (default: completed; one of pending, in_progress, completed, cancelled)	{tasks: [...], summary: {total, pending, in_progress, completed, cancelled}}
Automations
create_automation	name (required), prompt (required), rrule (required), folder_id (optional, files the generated chats into one of the user's folders)	{status, id, name, model_id, folder_id, is_active, next_runs}
update_automation	automation_id (required), name, prompt, rrule, model_id, folder_id (all optional; only provided fields are changed)	{status, id, name, model_id, folder_id, is_active, next_runs}
list_automations	status (optional: "active", "paused", or omit for all), count (default: 10)	{automations: [{id, name, prompt_snippet, model_id, rrule, is_active, last_run_at, next_runs}], total}
toggle_automation	automation_id (required)	{status, id, name, is_active}
delete_automation	automation_id (required)	{status, message}
Calendar
search_calendar_events	query (optional), start (optional datetime string, e.g. "2026-04-20 00:00"), end (optional datetime string), count (default: 10)	{events: [{id, calendar_id, title, description, start, end, all_day, location, color, is_cancelled}], total}
create_calendar_event	title (required), start (required datetime string), end (optional), description (optional), calendar_id (optional; uses default calendar), all_day (default: false), location (optional)	{status, id, calendar_id, title, start, end, ...}
update_calendar_event	event_id (required), title, description, start, end, all_day, location, is_cancelled (all optional; only provided fields are changed)	{status, id, title, start, end, ...}
delete_calendar_event	event_id (required)	{status, message}
Skills
view_skill	name (required)	{name, content}
Time Tools
get_current_timestamp	None	{current_timestamp, current_iso}
calculate_timestamp	days_ago, weeks_ago, months_ago, years_ago (all default: 0)	{current_timestamp, current_iso, calculated_timestamp, calculated_iso}
Sub-agents
delegate_task	task (required), context (optional; decisions, findings or file paths to carry across), background (default: false; the parameter is removed from the schema entirely unless SUBAGENTS_BACKGROUND_ENABLED is on)	Foreground: the sub-agent's final answer as text, truncated at SUBAGENTS_MAX_OUTPUT. Background: a JSON handle {status: "dispatched", delegation_id, subagent_chat_id, mode, task}, with the result posted into the parent chat later. Errors are returned as an Error: ... string rather than raised
timer	prompt (required; sent back into the chat when the timer fires), at (required; a relative offset such as 10s, 5m, 1h, 2d, +10s or in 10 seconds, or an RFC 3339 timestamp that must carry an explicit timezone; must be in the future), cancel_on (optional list of chat.read, chat.user_message)	{"status": "set", "at": "<RFC 3339 UTC>", "cancel_on": [...]} as a JSON string. Errors are returned as a plain Error: ... string, not JSON
Notifications
notify	message (required; the notification body), target (optional target id; empty uses the default target), title (optional)	Notification sent to {target_id}., or Notification failed: {reason}

Builtin tools behave differently inside a note-attached chat

The chat opened from a note is an internal chat of type note, and builtin tools are gated differently there. Two separate overrides apply:

The note tools are always injected. search_notes, view_note, write_note and replace_note_content load regardless of the notes.enable config, the model's Notes category, and the user's features.notes permission. Turning notes off by any of those three controls does not remove them there.

The whole builtin-tool surface is force-enabled. A note chat activates builtin tools even when the request would not normally qualify: without a UI session, with function_calling set to legacy, and even when the model's builtin_tools capability is switched off. So a model an administrator deliberately configured without builtin tools still receives them (memory, web search, code interpreter, image generation and the rest, subject to each category's own gate) inside a note chat. If you rely on that capability toggle to keep tools away from a model, it does not hold in this one context.

Separately, view_note and replace_note_content short-circuit access control for admins: an admin reads or rewrites any note without the owner or grant check other users are subject to. Consistent with admins being root-equivalent elsewhere, but worth knowing if you relied on the previous behaviour, where admins were checked like everyone else.

Note attachments are also injected: every non-image file on the note is added as retrieval context on every message in that chat.

Automatic Timezone Detection

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.

Knowledge Tool Injection Depends on Attachments

Knowledge tool availability changes based on whether the model has attached knowledge. Use the Knowledge Tool Availability matrix above as the source of truth.

• With attachments: the model gets scoped knowledge tools.
• Without attachments: the model gets KB discovery tools.
• list_knowledge and list_knowledge_bases are mutually exclusive.

Attached Knowledge Still Requires User Access

Attaching a knowledge base to a custom model does not bypass access control. When a user chats with the model, query_knowledge_files checks whether that specific user has permission to access each attached knowledge item. Items the user cannot access are silently excluded from search results.

Access requirements by knowledge type:

Attached Type	User Needs
Knowledge Base (collection)	Owner, admin, or explicit read access grant
Individual File	Owner or admin only (no access grants)
Note	Owner, admin, or explicit read access grant

Example scenario: An admin creates a private knowledge base and attaches it to a custom model shared with all users. Regular users chatting with this model will get empty results from query_knowledge_files because they don't have read access to the KB itself, even though they can use the model.

Solution: Make sure users who need access to the model's knowledge also have read access to the underlying knowledge base (via access grants or group permissions in the Knowledge settings).

Recommended KB Tool Workflow

With attached knowledge:

1. First call list_knowledge to discover attached KBs, files, and notes
2. Use query_knowledge_files to search file contents (auto-scoped to attachments)
3. Use view_file or view_knowledge_file to read specific files; use offset and max_chars for large files

Without attached knowledge:

1. First call list_knowledge_bases to discover what knowledge is available
2. Then use query_knowledge_files to search file contents within relevant KBs
3. If still empty, the files may not be embedded yet, or you may have Full Context mode enabled which bypasses the vector store

Do NOT use Full Context mode with knowledge tools. Full Context injects file content directly and doesn't store embeddings, so query_knowledge_files will return empty. Use Focused Retrieval (default) for tool-based access.

Knowledge Base Tools and Hybrid Search

The native query_knowledge_files tool uses hybrid search + reranking when ENABLE_RAG_HYBRID_SEARCH is enabled in admin settings, giving you the same search quality as the standard RAG pipeline. When hybrid search is disabled, it falls back to simple vector search.

Knowledge is NOT Auto-Injected in Native Mode

Important: When using Native Function Calling, attached knowledge is not automatically injected into the conversation. The model must actively call knowledge tools to search and retrieve information.

If your model isn't using attached knowledge:

1. Add instructions to your system prompt telling the model to discover and query knowledge bases. Example: "When users ask questions, first use list_knowledge to see what knowledge is available, then use query_knowledge_files to search the relevant knowledge base before answering. If no knowledge is attached to this model, use list_knowledge_bases first to discover available KBs."
2. Or disable Native Function Calling for that model to restore automatic RAG injection.
3. Or use "Full Context" mode for attached knowledge (click on the attachment and select "Use Entire Document") which always injects the full content.

See Knowledge Scoping with Native Function Calling for more details.

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)

The Builtin Tools capability can be toggled on or off for each model in the Workspace > Models editor under Capabilities. When enabled (the default), all the system tools listed above are automatically injected when using Native Mode.

When to disable Builtin Tools:

Scenario	Reason to Disable
Model doesn't support function calling	Smaller or older models may not handle the tools parameter correctly
Simpler/predictable behavior needed	You want the model to work only with pre-injected context, no autonomous tool calls
Security/control concerns	Prevents the model from actively querying knowledge bases, searching chats, accessing memories, etc.
Token efficiency	Tool specifications consume tokens; disabling saves context window space

What happens when Builtin Tools is disabled:

1. No tool injection: The model won't receive any of the built-in system tools, even in Native Mode.
2. RAG still works (if File Context is enabled): Attached files are still processed via RAG and injected as context.
3. No autonomous retrieval: The model cannot decide to search knowledge bases or fetch additional information; it works only with what's provided upfront.

Granular Builtin Tool Categories (Per-Model)

When the Builtin Tools capability is enabled, you can further control which categories of builtin tools are available to the model. This appears in the Model Editor as a set of checkboxes under Builtin Tools.

Category	Tools Included	Description
Time & Calculation	get_current_timestamp, calculate_timestamp	Get current time and perform date/time calculations
Memory	search_memories, list_memory_paths, read_memory_path, list_memories, update_memory, add_memory, replace_memory_content, delete_memory	Search and manage user memories
Chat History	search_chats, view_chat	Search and view user chat history
Notes	search_notes, view_note, write_note, replace_note_content	Search, view, and manage user notes
Knowledge Base	list_knowledge, list_knowledge_bases, search_knowledge_bases, query_knowledge_bases, search_knowledge_files, query_knowledge_files, grep_knowledge_files, view_file, view_knowledge_file (or kb_exec + query_knowledge_files + view_note/query_knowledge_bases/search_knowledge_bases as applicable when ENABLE_KB_EXEC is set)	Browse and query knowledge bases
Web Search	search_web, fetch_url	Search the web and fetch URL content
Image Generation	generate_image, edit_image	Generate and edit images
Code Interpreter	execute_code	Execute code in a sandboxed environment
Channels	search_channels, search_channel_messages, view_channel_message, view_channel_thread	Search channels and channel messages
Task Management	create_tasks, update_task	Create a structured task/todo list and update individual task statuses in the active chat
Automations	create_automation, update_automation, list_automations, toggle_automation, delete_automation	Create and manage scheduled automations from chat
Calendar	search_calendar_events, create_calendar_event, update_calendar_event, delete_calendar_event	Search, create, update, and delete calendar events

All categories are enabled by default. Disabling a category prevents those specific tools from being injected, while keeping other categories active.

Skills / view_skill, Not a Category Toggle

The view_skill tool does not appear in the Builtin Tools category checkboxes. It is injected when at least one skill is attached to the model via Workspace → Models → Edit → Skills. When skills are attached:

1. The model receives a summary of each attached skill (name + description) in its system prompt via <available_skills> tags
2. The view_skill tool is injected so the model can load full instructions on demand
3. If no skills are attached, view_skill is not available

Users can also select skills per-chat (via the chat input bar), which injects the skill's full content directly into the system prompt instead of requiring a view_skill call.

Use cases for granular control:

Scenario	Recommended Configuration
Privacy-focused model	Disable Memory and Chat History to prevent access to personal data
Read-only assistant	Disable Notes (prevents creating/modifying notes) but keep Knowledge Base enabled
Minimal token usage	Enable only the categories the model actually needs
Knowledge-centric bot	Disable everything except Knowledge Base and Time

note

These per-category toggles only appear when the main Builtin Tools capability is enabled. If you disable Builtin Tools entirely, no tools are injected regardless of category settings.

Global Features Take Precedence

Enabling a per-model category toggle does not override global feature flags. For example, if ENABLE_NOTES is disabled globally (Admin Panel), Notes tools will not be available even if the "Notes" category is enabled for the model. The per-model toggles only allow you to further restrict what's already available; they cannot enable features that are disabled at the global level.

User-Level Permissions Also Apply

Builtin tools that correspond to an RBAC feature permission are also gated by the user's Features permissions. Even if a tool category is enabled on the model and the global feature flag is on, the tool will not be injected if the user lacks the corresponding features.* permission. Admins always pass these checks.

Tool Category	Required features.* Permission
Memory	features.memories
Web Search	features.web_search
Image Generation	features.image_generation
Code Interpreter	features.code_interpreter
Notes	features.notes
Channels	features.channels
Automations	features.automations
Calendar	features.calendar

This ensures that RBAC permissions are respected end-to-end: disabling a feature for a user prevents the model from calling those tools on their behalf, not just hiding the UI.

Per-Chat Feature Toggles (Web Search, Image Generation, Code Interpreter)

Web Search, Image Generation, and Code Interpreter built-in tools have an additional layer of control: the per-chat feature toggle in the chat input bar. For these tools to be injected in Native Mode, all three conditions must be met:

1. Global config enabled: the feature is turned on in Admin Panel (e.g., ENABLE_WEB_SEARCH)
2. Model capability enabled: the model has the capability checked in Workspace > Models (e.g., "Web Search")
3. Per-chat toggle enabled: the user has activated the feature for this specific chat via the chat input bar toggles

This means users can disable web search (or image generation, or code interpreter) on a per-conversation basis, even if it's enabled globally and on the model. This is useful for chats where information must stay offline or where you want to prevent unintended tool usage.

Full Agentic Experience

For the best out-of-the-box agentic experience, administrators can enable Web Search, Image Generation, and Code Interpreter as default features for a model. In Settings > Admin > AI > Models, click the pencil (Edit) on your target model and toggle these three on under Default Features. This ensures they are active in every new chat by default, so users get the full tool-calling experience without manually enabling each toggle. Users can still turn them off per-chat if needed.

Builtin Tools vs File Context

Builtin Tools controls whether the model gets tools for autonomous retrieval. It does not control whether file content is injected via RAG; that's controlled by the separate File Context capability.

• File Context = Whether Open WebUI extracts and injects file content (RAG processing)
• Builtin Tools = Whether the model gets tools to autonomously search/retrieve additional content

See File Context vs Builtin Tools for a detailed comparison.

Interleaved Thinking

🧠 When using Native Mode (Agentic Mode), high-tier models can engage in Interleaved Thinking. This is a powerful "Thought → Action → Thought → Action → Thought → ..." loop where the model can reason about a task, execute one or more tools, evaluate the results, and then decide on its next move.

Quality Models Required

Interleaved thinking requires a model that can maintain context across multiple tool calls and choose tools sensibly. Current reasoning-capable models handle this — GPT-5.6, Claude Sonnet 5, Gemini 3.6 Flash, or MiniMax M3 are a reasonable minimum. Older or very small models will not.

This is fundamentally different from a single-shot tool call. In an interleaved workflow, the model follows a cycle:

1. Reason: Analyze the user's intent and identify information gaps.
2. Act: Call a tool (e.g., query_knowledge_files for internal docs or search_web and fetch_url for web research).
3. Think: Read the tool's output and update its internal understanding.
4. Iterate: If the answer isn't clear, call another tool (e.g., view_knowledge_file to read a specific document or fetch_url to read a specific page) or refine the search.
5. Finalize: Only after completing this "Deep Research" cycle does the model provide a final, grounded answer.

This behavior is what transforms a standard chatbot into an Agentic AI capable of solving complex, multi-step problems autonomously.

For long-running workflows, combine interleaved tool use with create_tasks (to lay out the plan upfront) and update_task (to mark each step done as work progresses) so the model can plan explicitly, track progress, and keep users aligned on next actions.

---

---

🚀 Summary & Next Steps

Tools bring your AI to life by giving it hands to interact with the world.

• Browse Tools: openwebui.com/search
• Advanced Setup: Learn more about MCP Support
• Development: Writing your own Custom Toolkits