Agent tools overview | SoAI Documentation

SoAI's built-in tools let a model inspect or change resources through typed operations. The model requests a tool by name, SoAI validates its arguments and access conditions, and the result returns to the active turn. The Chat transcript keeps each call, approval decision, and result visible.

Use this overview to choose tools and set their policy. The generated Built-in tool reference is the canonical inventory of tool names, arguments, result schemas, and annotations.

Choose and enable tools

Family	Use it for
Web and knowledge tools	Search providers, page retrieval, indexed Knowledge, and MCP resources.
File and shell tools	Workspace reads and mutations, patches, searches, and persistent shell sessions.
Browser automation tools	Browser navigation, interaction, snapshots, tabs, downloads, and profiles.
Media reading tools	Images, audio, video frames, documents, and OCR.
Image generation tools	Image creation through the configured image backend.
Memory and history tools	Cross-conversation memory and access to permitted conversation history.
Planning and agent control tools	Plans, todo items, questions, subagents, and automation operations.
Productivity and feed tools	Mail, calendars, weather, news, feeds, and HTTP requests.
Skills	Load selected task instructions and read their supporting text through `skill_read`.
Utility tools	Arithmetic, units, hashing, encoding, and date operations.
Hardware tools	Hardware snapshots and protected GPU control or benchmark operations.
Secrets vault	Credential collection and autofill without placing plaintext in those tools' arguments or results.

Enable tools in a conversation

In the SoAI WebUI, open the conversation and select Chat configuration > Tools.
Turn on Tools enabled under MCP settings.
Choose tools separately for Chat, Plan, and Execute mode.
Choose whether protected calls require approval, then select Save.

The account needs MCP usage (MCP_USE), the installation-wide tool runtime must be enabled (TOOLS.MCP.ENABLED), and the selected model must support tool calling. The saved selection applies on the next turn. SoAI locks these controls while a turn is generating.

With skills selected, skill_read is available without adding it to the tool picker. Automatic loading needs tools enabled, at least one tool selected for the active mode, and model tool-calling support. An explicit $name request can load instructions with tools disabled.

Use mode-specific selection

The active conversation mode selects one of three saved lists. Chat is intended for ordinary conversation and bounded lookups. Plan allows investigation but blocks a tool whose metadata marks it destructive or does not provide valid destructive metadata. Execute can use the complete set the user selected. Plan mode does not mean that every allowed tool is read-only; selected tools can still reach external systems.

Reset stages SoAI's canonical selection for the active mode. Default tools (new chats) controls the starting lists used by later conversations. Indexed Knowledge can keep its required access tools selected while that conversation has indexed content and retrieval is active. See Agent mode, tool approvals, and checkpoints for the complete mode lifecycle.

Tool selection also changes SoAI's built-in system prompt. SoAI removes built-in capability guidance that depends on unavailable or unselected tools. It does not rewrite the custom system prompt saved under Chat configuration > Parameters; instructions written there still reach the model even when the named tool is unavailable.

Permissions and approvals

With Require tool approval enabled, an interactive WebUI turn shows the tool name, call ID when present, and arguments before a protected call runs. Approve or deny the call. Remembered approval normally applies to that tool for the signed-in account; browser-autofill approvals are limited to the destination site. If SoAI cannot establish that scope, it refuses to save an unscoped remembered autofill approval.

A tool prompts when its metadata marks it destructive, explicitly requires approval, or has missing or invalid destructive metadata. Approval dialogs belong to interactive WebUI turns. API and background runs cannot pause for that dialog. An Administrator can clear their own remembered decisions through Settings > Reset > Tool approvals.

Understand selection, permission, and availability

Selecting a tool only makes it eligible for the model. Each call still has to pass its runtime feature setting, account permissions, ownership checks, conversation mode, and argument validation. For example, shell calls require Terminal and shell access (TERMINAL_USE) in addition to MCP usage.

SoAI conversations can use conversation-scoped tools such as soai_documentation, stop_conversation, and skill_read; the latter also requires an eligible skill selection. Administrators receive additional protected hardware-control and hardware-benchmark tools. MCP server mode exposes a subset of the public catalog, which excludes these conversation-scoped and administrator-only tools.

Control installation-wide availability

An Administrator with Configuration changes (CONFIG_PATCH) selects the Settings button at the right of the header, then Settings, then Advanced in the page header. Paste the full configuration path into settings search, change the value, and select Save. These controls can disable the whole tool runtime or specific families. The main switches are:

TOOLS.MCP.ENABLED for the complete tool system.
TOOLS.MCP.BROWSER.ENABLED for browser tools.
TOOLS.MCP.SHELL.ENABLED for new shell work and shell input.
TOOLS.MCP.GENERATE_IMAGE.ENABLED for image generation.
TOOLS.RAG.ENABLED for indexed Knowledge and its tools.

A disabled family rejects its calls even if the tool remains selected in an existing conversation. Some settings require a restart; Advanced Settings reports that state after Save.

External clients and the trust boundary

SoAI's MCP server publishes a configured subset of the public catalog to clients that authenticate with an MCP token. Its exposure list is deliberately narrower than the integrated-agent catalog. A client still needs the owning account's required ACL actions. See Use SoAI as an MCP server for tokens, transport, and exposure controls.

SoAI can also use tools supplied by external MCP servers. Those connections are configured separately and appear beside built-in tools in the conversation picker. See Connect MCP servers to SoAI.

A compatible /v1/chat/completions request that carries a SoAI conversation ID can use that conversation's server-side agent configuration. Request-supplied compatible tool definitions are different: SoAI passes them through for the API client to execute. See HTTP API reference for the boundary.

Apply the trust boundary

Start with the smallest tool set that can complete the work. A read-only label does not grant account access, and a confirmation prompt does not make an unsafe deployment trustworthy. Shell and file tools act with the SoAI process's host access; browser, mail, calendar, HTTP, and search tools can cross the installation boundary. Review Security hardening and the Hardening checklist before enabling high-impact tools for other users or external clients.