[PR #1386] [MERGED] docs: tools and tool-ids URL parameters need the prefixed ID for tool server connections #1352

New issue

Closed

opened 2026-10-18 14:19:03 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-18 14:19:03 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/open-webui/docs/pull/1386
Author: @silentoplayz
Created: 9/9/2026
Status: ✅ Merged
Merged: 9/9/2026
Merged by: @silentoplayz

Base: main ← Head: docs/url-params-tool-server-ids

📝 Commits (1)

e898f29 Document the prefixed IDs tool server connections need in the tools and tool-ids URL parameters

📊 Changes

1 file changed (+2 additions, -1 deletions)

View changed files

📝 docs/features/chat-conversations/chat-features/url-params.md (+2 -1)

📄 Description

Summary

The URL Parameters page says tools and tool-ids take "tool IDs" and shows tool1,tool2. That works for workspace tools, whose ID is the plain ID. It does not work for tool server connections, because Open WebUI keys those as server:mcp:<server-id> for MCP connections and server:<server-id> for OpenAPI connections. Passing the bare connection ID activates nothing.

This PR adds a note under Tool Selection that spells out both forms with an example. It also covers the fallback for an OpenAPI connection without an ID and says that an unmatched ID is not activated. It links the API reference section that already documents the server:mcp: form. The overview table row gets one sentence so the prefix is visible at a glance.

The UI side of the same trip-up is open-webui/open-webui#29802: an unmatched ID from the URL shows a tool count of 1 with no tool selected.

Checklist

I have reviewed the relevant documentation and matched the existing style.
This PR meets Open WebUI's contribution standards: it is accurate, relevant to users, narrowly scoped, maintainable, and not promotional content, advertising, lead generation, SEO placement, or a request to list a product, service, provider, integration, gateway, tool, or company primarily for visibility.
I understand that PRs that do not meet these standards may be closed without review and will not be merged. Repeated, low-quality, off-topic, promotional, or intentionally misleading submissions may result in the contributor being blocked from future participation in Open WebUI repositories.

Notes for reviewers

I hit this tonight with /?tool-ids=deepwiki for an MCP connection whose ID is deepwiki. The chat input showed a tool count of 1, but the tool was not selected in the Integrations menu and opening the menu cleared the count. server:mcp:deepwiki is the value that parameter wants.

The ID forms come from open-webui/open-webui at 674760bfc1122e0a19fe299e05a86d1cbb528e6f: OpenAPI connections at routers/tools.py#L117, MCP connections at routers/tools.py#L153, and the position fallback for an OpenAPI connection with no ID at utils/tools.py#L1535-L1537.

The linked anchor is the same one docs/reference/server-side-tool-calling.md already uses.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/open-webui/docs/pull/1386 **Author:** [@silentoplayz](https://github.com/silentoplayz) **Created:** 9/9/2026 **Status:** ✅ Merged **Merged:** 9/9/2026 **Merged by:** [@silentoplayz](https://github.com/silentoplayz) **Base:** `main` ← **Head:** `docs/url-params-tool-server-ids` --- ### 📝 Commits (1) - [`e898f29`](https://github.com/open-webui/docs/commit/e898f296107d6bd682509be4465dc19c26533d55) Document the prefixed IDs tool server connections need in the tools and tool-ids URL parameters ### 📊 Changes **1 file changed** (+2 additions, -1 deletions) <details> <summary>View changed files</summary> 📝 `docs/features/chat-conversations/chat-features/url-params.md` (+2 -1) </details> ### 📄 Description ## Summary The URL Parameters page says `tools` and `tool-ids` take "tool IDs" and shows `tool1,tool2`. That works for workspace tools, whose ID is the plain ID. It does not work for tool server connections, because Open WebUI keys those as `server:mcp:<server-id>` for MCP connections and `server:<server-id>` for OpenAPI connections. Passing the bare connection ID activates nothing. This PR adds a note under Tool Selection that spells out both forms with an example. It also covers the fallback for an OpenAPI connection without an ID and says that an unmatched ID is not activated. It links the API reference section that already documents the `server:mcp:` form. The overview table row gets one sentence so the prefix is visible at a glance. ## Related issue or discussion The UI side of the same trip-up is open-webui/open-webui#29802: an unmatched ID from the URL shows a tool count of 1 with no tool selected. ## Checklist - [x] I have reviewed the relevant documentation and matched the existing style. - [x] This PR meets Open WebUI's contribution standards: it is accurate, relevant to users, narrowly scoped, maintainable, and not promotional content, advertising, lead generation, SEO placement, or a request to list a product, service, provider, integration, gateway, tool, or company primarily for visibility. - [x] I understand that PRs that do not meet these standards may be closed without review and will not be merged. Repeated, low-quality, off-topic, promotional, or intentionally misleading submissions may result in the contributor being blocked from future participation in Open WebUI repositories. ## Notes for reviewers I hit this tonight with `/?tool-ids=deepwiki` for an MCP connection whose ID is `deepwiki`. The chat input showed a tool count of 1, but the tool was not selected in the Integrations menu and opening the menu cleared the count. `server:mcp:deepwiki` is the value that parameter wants. The ID forms come from `open-webui/open-webui` at `674760bfc1122e0a19fe299e05a86d1cbb528e6f`: OpenAPI connections at [`routers/tools.py#L117`](https://github.com/open-webui/open-webui/blob/674760bfc1122e0a19fe299e05a86d1cbb528e6f/backend/open_webui/routers/tools.py#L117), MCP connections at [`routers/tools.py#L153`](https://github.com/open-webui/open-webui/blob/674760bfc1122e0a19fe299e05a86d1cbb528e6f/backend/open_webui/routers/tools.py#L153), and the position fallback for an OpenAPI connection with no ID at [`utils/tools.py#L1535-L1537`](https://github.com/open-webui/open-webui/blob/674760bfc1122e0a19fe299e05a86d1cbb528e6f/backend/open_webui/utils/tools.py#L1535-L1537). The linked anchor is the same one `docs/reference/server-side-tool-calling.md` already uses. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-18 14:19:03 +00:00