Sixteen tools search public sources, fetch pages, query the conversation's indexed Knowledge, read resources published by connected MCP servers, and consult the documentation installed with SoAI. These paths have different setup, cost, and failure modes.
In the SoAI WebUI, use a tool in a chat by selecting Chat configuration in the chat header, then
Tools. Turn on Tools enabled, choose tools for the required mode, and select
Save. The account needs MCP usage (MCP_USE). The conversation web-search controls and direct search endpoint also require
Web search (WEB_SEARCH). The selected model must support tool calling,
and the relevant provider, indexed collection, or connected MCP server must be available.
Installed SoAI documentation
soai_documentation searches and reads the documentation bundled with the installed SoAI release. It
works offline and needs no search provider, embedding model, or index configuration. Search with a concise English
phrase or an exact configuration key or tool name. Results include canonical page IDs and matching excerpts; pass
one of those IDs as page to read the page, then continue with next_offset_chars while the
response is truncated.
New conversations include this tool in the standard Chat, Plan, and Execute selections. A conversation with a
customized saved tool list keeps that list, so enable soai_documentation explicitly in its tool picker
when needed. The bundle describes the installed release. Use the settings and status pages for live system state,
and consult the SoAI website when you need information about a newer release.
Web search
SoAI gives each search provider its own tool rather than one tool with a provider argument. All six take a
query and an optional limit, which defaults to 5 and stops at 25. The rest of the
arguments differ by provider.
| Tool | Needs | Extra arguments |
|---|---|---|
web_search_brave |
A Brave Search API key | country, search_lang, freshness |
web_search_duckduckgo |
DuckDuckGo needs no account or key. | region |
web_search_google |
A Google Programmable Search API key and engine ID | safe |
web_search_searxng |
Your own SearXNG instance | categories, engines |
web_search_serper |
A Serper API key | gl, hl |
web_search_tavily |
A Tavily API key | search_depth, include_domains, exclude_domains |
web_search_duckduckgo is the only search tool in the default Chat, Plan, and Execute lists, and the
only provider that works on a fresh installation without configuration. Every other provider needs a credential or,
for SearXNG, a configured instance. Running your own SearXNG keeps queries on infrastructure you control while still
aggregating several engines.
Adding a provider key
An administrator with MCP administration (MCP_ADMIN) selects Open settings menu at the right
of the header, then Settings and MCP. Find Search provider API keys,
select the provider, paste the key, and save. SoAI stores it encrypted
rather than writing it into config.yaml, and the list shows it masked from then on. A key supplied
through the environment shows up in the same list marked as coming from the environment.
Provider defaults are installation-wide configuration. An administrator with Configuration changes (CONFIG_PATCH)
selects Open settings menu at the right of the header, then Settings, then
Advanced in the Settings page header. The page becomes Advanced settings and the
control changes to Basic. SearXNG needs its base URL set at
TOOLS.RAG.SEARXNG.BASE_URL before
its tool can reach anything, and Google needs
TOOLS.RAG.GOOGLE.SEARCH_ENGINE_ID. The rest are optional: default country and language for Brave, search depth for Tavily, geolocation and language
for Serper, safe-search level for Google, categories and engine list for SearXNG. SoAI applies
TOOLS.RAG.WEB.SEARCH_RETRY_ATTEMPTS
and
TOOLS.RAG.WEB.SEARCH_RETRY_DELAY
across all providers. Select Save after editing.
Fetching a page
web_fetch downloads one URL and pulls the readable content out of it. extract_mode selects
markdown, text, or html. It also grabs a screenshot through the browser
runtime so the model can see the layout, which you can switch off for a single call with
screenshot: false. When browser tools are disabled installation-wide, SoAI skips the screenshot and
fetches the text anyway (rather than failing the request). The extraction step runs no JavaScript, so use
Browser automation tools for client-rendered pages, login screens, or
bot challenges.
SoAI caps the response. max_chars defaults to
TOOLS.MCP.WEB_FETCH.DEFAULT_MAX_CHARS, 50,000. If a call requests more than
TOOLS.MCP.WEB_FETCH.MAX_CHARS_LIMIT, SoAI accepts the call but applies the 100,000-character limit. Content past the effective cap carries a
truncation marker.
The conversation Knowledge base
Every conversation can hold its own document collection. On the Chat page, open the Add attachments dialog from the composer and choose its Knowledge tab. Use Upload file, Upload folder, or Load from Workspace to add source material. The same tab shows processing status. Reindex appears after documents exist and becomes available when an embedding model is configured. See Attachments and file context for the WebUI flow and the difference between direct files, workspace references, and Knowledge.
Retrieval controls live elsewhere. Open Chat configuration, choose the Knowledge tab, and use the Knowledge settings section to select the embedding model, chunking method, and retrieval strategy. Knowledge and document collections (RAG) covers the pipeline in full. The five tools below are the part an agent can drive.
| Tool | What it does |
|---|---|
knowledge_config_get |
Reads back the retrieval strategy, chunking settings, embedding model, and reranking config. |
knowledge_list |
Lists the indexed documents with their processing status. Paginated. |
knowledge_reindex |
Re-embeds the whole collection with a different model. Destructive, needs confirm: true,
and runs as a background job instead of blocking the turn.
|
knowledge_search |
Searches everything indexed for the conversation, local files and ingested web pages alike. Takes
retrieval_strategy (similarity, mmr, or hybrid),
top_k, and similarity_threshold.
|
knowledge_web_fetch |
Fetches a URL, indexes it, and returns immediate context from the new document. Accepts chunking, embedding, and retrieval arguments. |
web_fetch returns extracted content without adding it to Knowledge.
knowledge_web_fetch also accepts chunking and embedding settings, then indexes the page so a later
knowledge_search can find it. Use the second when the page is reference material the conversation will
return to, and the first for a one-off lookup.
When a conversation has indexed Knowledge attached, SoAI keeps the knowledge tools enabled and marks them as managed in the tool picker. The tools stay enabled while that content remains active.
Resources from connected MCP servers
When you connect SoAI to external MCP servers, those servers can publish resources as well as tools. An
administrator with MCP administration (MCP_ADMIN) selects Open settings menu at the right of
the header, then Settings and MCP. Add servers under MCP servers;
what they expose then appears in the Resources and Tools panels on the same tab.
Three tools read those resources. mcp_resources_list enumerates them,
mcp_resource_templates_list enumerates URI templates, and mcp_resource_read fetches one by
server ID and URI. Leave the server argument off either list tool and it queries every connected server
at once. MCP overview covers registering servers and their transports.
Network behaviour
Search and fetching share one HTTP layer. Its installation-wide switch is
TOOLS.RAG.WEB.ENABLED. The related
controls cover user agent and rotation, an optional proxy or proxy pool, a URL cache with a TTL, per-request and
total timeouts, and a download ceiling of
TOOLS.RAG.WEB.MAX_URL_SIZE_MB, 10 by default.
TOOLS.MCP.WEB_FETCH.BLOCK_PRIVATE_NETWORK_EGRESS
defaults to true, so web_fetch blocks destinations on private networks.
TOOLS.MCP.HTTP_REQUEST.BLOCK_PRIVATE_NETWORK_EGRESS
does the same for http_request. Turn off a tool's setting only when that tool must reach a trusted LAN
service; doing so permits private-network egress for that tool.
Security hardening explains why these per-tool controls do not replace the
deployment's private network boundary.
With offline mode on, SoAI refuses search outright and restricts fetching to URLs that resolve to the local machine. The tool returns an error naming the flag rather than hanging until it times out.
When web extraction falls back to browser-backed rendering,
TOOLS.RAG.WEB.BROWSER_RENDER_BLOCK_ADS
applies the shared EasyList request filter and defaults to true. This reduces malicious-ad exposure but
does not make fetched content or its instructions trustworthy. See
Browser ad blocking for the boundary.