owui-tools/docs/open-webui.md

Registering it in Open WebUI

Two steps, both by hand, and the second is the one people skip.

1. The tool connection

Admin Panel → Settings → Integrations.

Not Settings → Tools in your own profile. That adds the connection for you only, and every other account sees an assistant with no tools and no explanation. It is the single most common setup mistake here.

Field	Value
Type	OpenAPI
URL	http://owuitools-gw:8000
Auth	Bearer, and your OWUITOOLS_AUTH_TOKEN
Name	anything
Visibility	Public

owuitools-gw resolves because the gateway container joins openwebui_default. It is the only container in this project that does — everything else sits on an internal network with no route out except through squid. If your Open WebUI is elsewhere, publish the gateway's port and use the host address.

Save. Open WebUI fetches the spec; you should see 22 tools.

Re-save it after any schema change

Open WebUI caches the spec from when the connection was saved. Adding a tool, switching one off in configs/tools.toml, or editing a docstring all need:

docker compose restart api

…and then Save on the connection again. Without that you keep the old list.

2. The model

Workspace → Models → your model → Edit.

• System prompt: paste ../configs/assistant/system-prompt.md.
• Tools: enable the connection.
• Function Calling: Default. Not Legacy — Legacy reformats the tool definitions in a way that loses the request-body schema, which is where the enums and defaults live.
• Advanced Params: num_ctx must match what Ollama actually loaded, or it reloads the model mid-conversation. See advanced-params.md.

The system prompt is doing most of the work. The tool descriptions alone do not produce using tools instead of recalling, checking rather than asserting, or saying "I don't know".

3. Forward the user headers

On the Open WebUI container:

ENABLE_FORWARD_USER_INFO_HEADERS: "True"

The tool server keys its per-user rate limits off X-OpenWebUI-User-Id, and the VM sub-agent's live view needs the chat id. Without it the limiter treats every request as the same anonymous caller and the live view silently does nothing.

Trimming the tool list

Open WebUI has a Function Name Filter List on the connection, which hides tools from one model. It is the wrong lever for this: the spec is still fetched, the endpoint still answers, and the setting lives in Open WebUI's database where you cannot read it.

Use ../configs/tools.toml instead. It removes the tool, so you stop paying its schema tokens on every turn.

Checking it worked

Ask something a tool should answer and recall should not:

what's the current version of ripgrep?

You should see a lookup_package call. If the model answers from memory, check Function Calling is Default and the system prompt was actually pasted.