Open WebUI टूल कॉल नहीं कर रहा: Native Mode, Tool Search और मॉडल संगतता जाँचें

टूल enabled है, मॉडल कहता है कि वह उसे इस्तेमाल करेगा, लेकिन chat में असली tool call दिखाई नहीं देता। केवल इस लक्षण से यह तय नहीं होता कि गलती मॉडल की है, Open WebUI की है या MCP/OpenAPI server की। सबसे भरोसेमंद तरीका है पहले एक छोटा और सुरक्षित reverse_string टूल चलाकर baseline बनाना, फिर Native Mode, Tool Search और model connection को एक-एक करके बदलना।

इस प्रक्रिया में मूल connection हटाने की जरूरत नहीं है। अंत में आपके पास चार conditions की ऐसी तुलना होगी जिसमें वास्तविक call और execution records होंगे। उसी के आधार पर आप तय कर पाएँगे कि Tool Search बंद करना है, जरूरी टूल को Always Loaded में रखना है या tool workflows को किसी verified model connection पर चलाना है।

समस्या को पाँच अलग layers में देखें

Open WebUI में “टूल enabled है” केवल UI state बताता है। सफल execution के लिए कम से कम पाँच layers काम करनी चाहिए।

Layer	क्या सही होना चाहिए	भ्रामक संकेत
1. Visibility और access	वर्तमान user टूल देख और पढ़ सके	Admin के लिए काम करता है, दूसरे user के लिए टूल चुपचाप गायब
2. Chat, mode और capability	Chat में Native और target tool enabled हों; built-in system tool के लिए Workspace → Models → Capabilities → Builtin Tools तथा संबंधित category भी enabled हो	Builtin Tools off है, या उसे Workspace/MCP/OpenAPI के common master switch की तरह समझ लिया गया
3. Request payload	Backend को full tool definition या installed version का supported deferred helper मिले	Tool Search schema defer करता है, लेकिन UI में टूल enabled दिखता है
4. Model backend	Backend सही target का structured call और valid arguments लौटाए	मॉडल plain text में “मैंने call किया” लिखता है, wrong operation चुनता है या bad arguments भेजता है
5. Execution	Open WebUI, MCP या OpenAPI server सही call चलाकर result लौटाए	सही call बना, लेकिन auth, route, protocol या server execution पर fail हुआ

ऊपर से नीचे जाँचें। User access और actual target call देखे बिना MCP server दोबारा बनाना समय और evidence दोनों खराब कर सकता है।

बदलाव से पहले baseline सुरक्षित करें

कम से कम ये चीजें लिख लें:

• Open WebUI version और deployment method;
• connection name, exact Model ID, UI model name और actual provider, gateway, Base URL या route;
• Model Settings → Advanced Params → Function Calling का effective value;
• built-in system tool के लिए Workspace → Models → Capabilities → Builtin Tools और relevant category switches;
• वर्तमान chat में Integrations → Tools से enabled tools और testing user का read access;
• Settings → Admin → Interface → Chat में दिखाई देने वाले चार effective values: Tool Search, Defer Built-in Tools, Deferral Threshold (characters) और Always Loaded Tools;
• इनके full configuration names: ENABLE_TOOL_SEARCH, TOOL_SEARCH_DEFER_BUILTIN_TOOLS, TOOL_SEARCH_DEFER_THRESHOLD, TOOL_SEARCH_ALWAYS_LOADED;
• failing capability built-in system tool, Workspace Tool, MCP या OpenAPI में से कौन-सी है;
• एक failed prompt, timestamp, chat export/screenshot और उसी समय के Open WebUI तथा tool-server logs।

Connection के toggle से उसे configuration मिटाए बिना disable किया जा सकता है। तुलना के लिए control-tool-test जैसे अलग नाम वाला connection बनाएँ; production connection को overwrite न करें।

दो बातें अलग रखें:

1. Normal chat काम करता है — केवल text request पूरा हुआ।
2. Tool calling काम करता है — target structured call, valid arguments, execution record और returned result सभी मिले।

मॉडल का plain-text दावा कि उसने reverse_string चलाया, proof नहीं है।

सुनिश्चित करें कि वर्तमान chat सच में Native Mode पर है

Open WebUI की current documentation Native को default और supported tool-calling mode बताती है। Legacy पुराने behavior के लिए रखा गया unsupported opt-out है।

तीन scopes जाँचें, क्योंकि कोई भी दूसरे को override कर सकता है:

1. global Model Defaults;
2. चुने हुए model के Advanced Params;
3. वर्तमान chat के Chat Controls।

Test के समय effective value को Native रखें। Legacy का behavior और Tool Search एक साथ test न करें, क्योंकि Tool Search Native Mode पर लागू होता है।

यदि missing capability Open WebUI का built-in system tool है, Workspace → Models में selected model edit करें और Capabilities खोलें। Builtin Tools तथा relevant category enabled होनी चाहिए। यह switch केवल Native Mode में built-in system tools की injection नियंत्रित करता है; यह Workspace reverse_string, MCP या OpenAPI tools का common master switch नहीं है।

Workspace, MCP और OpenAPI paths के लिए उनके अलग controls जाँचें:

• message box के पास Integrations खोलें;
• Tools चुनकर diagnostic या external tool को current chat में enable करें;
• यदि tool model पर attach है, तब भी current user का read access जाँचें।

Workspace Tool को model से attach करना access control को bypass नहीं करता। Read permission न होने पर tool model को भेजा ही नहीं जा सकता।

एक छोटा read-only test tool बनाएँ

Workspace Tools Open WebUI server के भीतर Python चलाते हैं, इसलिए इन्हें केवल trusted administrator बनाए या import करे। Diagnosis के लिए ऐसा function रखें जो files, network, database या system commands को touch न करे।

Workspace → Tools में यह tool बनाएँ:

"""
title: Read-only Tool Check
description: Reverses a string for tool-call diagnostics
version: 1.0.0
"""

class Tools:
    async def reverse_string(self, string: str) -> str:
        """
        दिए गए text को reverse करता है, बिना external data पढ़े या बदले।

        :param string: वही text जिसे ठीक-ठीक reverse करना है।
        :return: उल्टे क्रम में text।
        """
        return string[::-1]

Tool save करें, testing user को access दें और current chat में Integrations → Tools से enable करें।

हर test के लिए नए chat में यही fixed prompt भेजें:

string tool-check-7 पर reverse_string टूल का उपयोग करना अनिवार्य है।
इसे खुद reverse मत करो और अनुमान मत लगाओ।
टूल लौटने के बाद केवल टूल result लिखो।

Expected result:

7-kcehc-loot

सिर्फ यही text मिल जाना pass नहीं है। PASS के लिए चारों signals चाहिए:

• trace या tool activity में structured reverse_string call;
• argument में tool-check-7;
• Open WebUI या server log में matching execution record;
• tool result 7-kcehc-loot, जिसे final answer ने इस्तेमाल किया।

Chat record, call details और same timestamp वाले logs save करें। बाद की हर condition नए chat में, उसी tool और prompt से चलाएँ।

चार controlled conditions चलाएँ

एक बार में एक variable बदलें और change existing Admin UI से करें, केवल environment-variable names देखकर नहीं:

1. Settings → Admin → Interface → Chat खोलें।
2. नीचे की condition के अनुसार Tool Search, Defer Built-in Tools, Deferral Threshold (characters) और Always Loaded Tools set करें।
3. Save करके page दोबारा खोलें और वास्तव में दिख रहे values लिखें।
4. नया chat खोलकर वही fixed prompt चलाएँ।

ये fields क्रमशः ENABLE_TOOL_SEARCH, TOOL_SEARCH_DEFER_BUILTIN_TOOLS, TOOL_SEARCH_DEFER_THRESHOLD और TOOL_SEARCH_ALWAYS_LOADED से map होते हैं; चारों ConfigVar हैं। Default ENABLE_PERSISTENT_CONFIG=True होने पर Admin UI/database में saved values environment variables से पहले लागू होते हैं। इसलिए .env बदलकर restart करना यह साबित नहीं करता कि condition बदल गई। यदि deployment जानबूझकर ENABLE_PERSISTENT_CONFIG=False इस्तेमाल करता है, उसे record करें: startup पर environment values authoritative होंगे, और UI changes केवल running session में रहेंगे तथा restart पर खो जाएँगे।

Condition	Native	Tool Search	Defer Built-in Tools	Threshold	Always Loaded	उद्देश्य
A	On	Off	Current value record करें; इस Workspace Tool पर लागू नहीं	लागू नहीं	लागू नहीं	Full reverse_string definition से basic path verify करना
B	On	On	On और recorded; built-in tools को प्रभावित करता है, reverse_string को नहीं	0	Test tool का exact model-visible name	Always Loaded path test करना
C	On	On	On और recorded	0	Empty	Deferred path force करके search_tools और target call observe करना
D	On	C जैसा	C जैसा	0	Empty	दूसरे connection को पहले A, जरूरत हो तो B से qualify करके C दोहराना

Threshold 0 अस्थायी रूप से जरूरी है। सामान्य rule केवल configured character count से लंबी serialized definitions defer करता है। छोटा reverse_string default threshold के नीचे रह सकता है; तब C deferred path test ही नहीं करेगा। Diagnosis के बाद production values restore करें।

Condition A: पहले basic Native path साबित करें

Settings → Admin → Interface → Chat में Tool Search off करें, save करके page दोबारा खोलें और effective value verify करें। फिर नए chat में fixed prompt चलाएँ। केवल restart को setting change का proof न मानें।

• A pass: user access, Native calling, यह model route और Workspace execution minimal case में काम करते हैं।
• Target structured call नहीं: chat tool selection, read permission, effective Function Calling और backend की native structured-tool support जाँचें।
• Call बना लेकिन execution fail: model call stage तक पहुँचा; arguments, schema और Open WebUI execution logs देखें।

A pass हुए बिना Tool Search को दोष देना जल्दबाजी है।

Condition B: Always Loaded path जाँचें

उसी UI में Tool Search on करें, Defer Built-in Tools on करके value record करें, Deferral Threshold (characters) को 0 रखें और test tool का exact model-visible name Always Loaded Tools में डालें। Save, reopen और verify करने के बाद नया chat चलाएँ।

Always Loaded matching case-sensitive है और exact name या glob pattern लेती है। MCP tool का model-visible name आम तौर पर <server ID>_<tool name> होता है। Internal MCP method name से अनुमान न लगाएँ; actual tool list या request trace से copy करें।

• B pass: Tool Search enabled होने पर full schema के साथ यह tool callable है।
• A pass, B fail: saved/reopened UI values, exact name, letter case, true configuration source और tested Open WebUI instance जाँचें।

Condition C: deferred path force करें

Tool Search और Defer Built-in Tools on रखें, threshold 0 रखें, Always Loaded Tools खाली करें, save/reopen करके effective values verify करें और नए chat में वही prompt चलाएँ।

दो stages अलग-अलग record करें:

• क्या search_tools call हुआ?
• क्या उसने reverse_string definition लौटाई?
• उसके बाद target structured call बना?
• Open WebUI v0.12.2 या बाद में क्या call_tool आया और उसका tool_name तथा JSON arguments reverse_string और tool-check-7 को target करते हैं?
• क्या reverse_string वास्तव में execute हुआ और expected result लौटा?
• क्या model ने wrong tool चुना, plain text में call जैसा output लिखा या call ही नहीं किया?

यदि A और B pass हैं लेकिन C में search_tools नहीं आता, effective UI values, threshold, installed version और model/route की Tool Search helper चुनने की क्षमता देखें। यदि search_tools pass है लेकिन target structured call नहीं आता, model capability, visible name/schema, actual provider route, version और deferred compatibility को खुला रखें।

Strict backend behavior version-dependent है। Open WebUI v0.12.2 और बाद में deferred tool को declared call_tool के जरिए tool_name और JSON arguments के साथ invoke किया जाता है, जिससे current tools list तक सीमित backends support हो सकते हैं। पुराने versions deferred tool name को direct call करते थे, जिसे strict backend reject कर सकता था। पुराने issue को लागू करने से पहले installed version जाँचें। Public issue एक deployment और backend family का user report है, universal rule नहीं।

Condition D: केवल model connection बदलें

सिर्फ Native label से दूसरा connection deferred compatibility control नहीं बन जाता। पहले exact Model ID, actual provider/gateway, Base URL या route और Open WebUI version record करें। Tool Search off रखकर उसी read-only tool से A baseline चलाएँ, जरूरत हो तो B भी। Ordinary और Always Loaded paths pass होने के बाद ही tool, prompt, UI values, threshold और empty Always Loaded बदले बिना C को D के रूप में दोहराएँ।

• D pass, C fail: original model route differentiator है। उसे normal chat के लिए रखें और deferred-tool work verified route से चलाएँ।
• Second connection A या B fail: वह valid deferred control नहीं है; baseline पहले fix या replace करें।
• दोनों connections पर A/B pass, लेकिन C/D fail: यह branch खुली रखें कि दोनों actual backends/routes installed version का deferred flow support नहीं करते। अलग model names भी एक ही strict provider, gateway या router पर जा सकते हैं। Real route और version verify करें, फिर search_tools success तथा target structured call के आधार पर अगला step चुनें; इसे केवल Open WebUI config, name या execution issue न कहें।
• C और D दोनों pass: production tool की visible definition, operation selection, arguments, permissions या server अधिक संभावित कारण हैं।

Result के आधार पर सबसे छोटा fix चुनें

Evidence	अगला कदम
A fail और target structured call नहीं	Access, chat tool toggle, Native या backend की native function-calling support ठीक करें
A तथा B pass, C में search_tools नहीं	Effective UI values, threshold, installed version और helper-selection ability verify करें
search_tools pass, target structured call नहीं	Model capability, visible name/schema, actual provider route, version और deferred compatibility जाँचें; minimal fallback Always Loaded या Tool Search off है
Target call है, reverse_string execute नहीं	Open WebUI execution logs और call_tool target/arguments देखें
A–C pass, production tool fail	Model-visible definition, selected operation, arguments, Tool Search treatment, actual route, access और server evidence देखें
केवल एक qualified connection fail	उसे text chat के लिए रखें; tool tasks वही A/B/C pass करने वाले connection पर चलाएँ
दोनों qualified connections C/D fail	दोनों backends या shared route की deferred incompatibility branch रखें; search_tools, target call, route और version compare करें

यदि tools कम हैं, experimental Tool Search बंद करना अक्सर सबसे सरल और reliable choice है। यदि schemas बहुत अधिक और बड़े हैं, Tool Search रखें, लेकिन frequently used low-risk tools को Always Loaded करें और हर model connection अलग से certify करें।

Workspace baseline के बाद MCP/OpenAPI जाँचें

reverse_string pass केवल यह साबित करता है कि route एक simple single-string Workspace schema को call कर सकता है। इससे यह साबित नहीं होता कि वही model complex external tool चुनेगा, सही operation लेगा, valid arguments बनाएगा या multi-step workflow पूरा करेगा। Open WebUI MCP और OpenAPI docs working connection के बावजूद इन model limitations को स्पष्ट रूप से बनाए रखती हैं।

Server diagnosis से पहले production tool की वही definition capture करें जो model देखता है, और actual target-call evidence रखें:

• Target call नहीं, wrong operation या bad arguments: model capability, tool name/description/schema, Tool Search और actual model/provider route को suspect list में रखें।
• Correct structured target call बना, लेकिन server तक नहीं पहुँचा या transport/auth error लौटा: URL, access control, authentication, protocol, proxy, TLS और server जाँचें।
• Server ने correct operation लिया, लेकिन arguments reject किए या application error दिया: call को exposed schema से compare करें और server handling देखें।

MCP: transport, access और visible name

Open WebUI native MCP connection MCP (Streamable HTTP) इस्तेमाल करता है। केवल stdio expose करने वाला local MCP server सीधे native HTTP MCP connection नहीं है; उसे bridge/proxy चाहिए।

जाँचें:

• Type MCP है, OpenAPI नहीं;
• Streamable HTTP URL Open WebUI host/container से reachable है;
• authentication current user के लिए valid है;
• Access Control में testing user शामिल है;
• model-visible full definition और name <server ID>_<tool name> form में हैं;
• model ने सही target और valid arguments चुने;
• correct call MCP server logs तक पहुँचता है;
• response protocol result है, HTTP/auth/application error नहीं।

Correct target call नहीं है तो model/schema/Tool Search/route branch में रहें। Correct structured call है लेकिन server को request नहीं मिला तो URL, proxy, TLS और network देखें। Server ने correct operation लिया लेकिन arguments reject किए तो exposed schema से तुलना करें।

OpenAPI: operations discovery verify करें

Open WebUI OpenAPI 3.x path-item structure से operations खोजता है। Standard HTTP methods, usable parameter definitions और ऐसे stable names/descriptions जाँचें जिनसे model intended operation अलग कर सके।

Save करें:

• spec URL और tested version;
• Open WebUI द्वारा model को दिखाई गई actual tool names और definitions;
• model-selected operation और structured arguments;
• server access log और response status;
• वह returned body जो Open WebUI ने model को दिया।

Connection save होना execution proof नहीं है। /models verification fail होने से भी chat या tools की incompatibility स्वतः साबित नहीं होती; कुछ compatible providers standard /models implement नहीं करते। तब exact Model ID manually दें और A/B/C evidence तथा real production-tool call से निर्णय लें।

Optional BetterToken comparison connection

Original connection सुरक्षित रखते हुए एक OpenAI-compatible comparison connection जोड़ सकते हैं। BetterToken API Base URL:

https://www.bettertoken.ai/v1

Current catalog से वही exact Model ID चुनें जिसके supported_endpoint_types में openai हो, और अपना API key इस्तेमाल करें। Display name से ID guess न करें। Normal chat pass होना Tool Search compatibility का प्रमाण नहीं है।

उस connection पर भी A–D चलाएँ। यहाँ BetterToken सिर्फ alternate model API path और request usage observation का विकल्प है; यह Open WebUI, किसी model या Tool Search को fix करने का दावा नहीं है।

References:

• Open WebUI Tools
• Workspace Tool development
• OpenAI-compatible connections
• Open WebUI MCP
• OpenAPI Tool Servers
• BetterToken Chat Completions
• BetterToken model protocol catalog

एक reproducible diagnostic record रखें

Open WebUI version:
Deployment:
Connection:
Exact model ID:
Actual provider/gateway route:
Function Calling:
Builtin Tools capability/categories:
Tool Search UI value:
Defer Built-in Tools UI value:
Deferral Threshold UI value:
Always Loaded Tools UI value:
ENABLE_PERSISTENT_CONFIG mode:
ENABLE_TOOL_SEARCH:
TOOL_SEARCH_DEFER_BUILTIN_TOOLS:
TOOL_SEARCH_DEFER_THRESHOLD:
TOOL_SEARCH_ALWAYS_LOADED:
Tool visible name:
Prompt:
search_tools call observed:
target call_tool / structured invocation observed:
reverse_string execution log observed:
Returned value:
Timestamp:

Upgrade, model change या tool-server migration के बाद यही record compact regression test बनेगा।

पहला कदम

Connections हटाने या पूरे MCP को rebuild करने से शुरू न करें। Current chat को Native रखें, Tool Search off करें और tool-check-7 पर reverse_string चलाएँ। Structured call, execution log और 7-kcehc-loot तीनों मिलने के बाद ही forced deferral, Always Loaded और दूसरा connection compare करें।

यही evidence बताएगा कि minimal fix permission, mode, Tool Search, model backend या MCP/OpenAPI execution layer में कहाँ करना है।