Added a way to switch off tools you never need (#1115)

documentation/Enterprise IT.md

@@ -741,6 +741,8 @@ The export reads saved, effective settings, including organization-managed value
 
 Some tools only make sense together and form a tool collection, such as **Mailboxes** with Search Mails, Read Mail, and Count Mails. **Tool Settings** shows such a collection as one row, and its export covers all of its tools: each area names its tool, and the minimum provider confidence goes under the ID of the collection, e.g., `mailboxes`. Wherever your configuration names tools — `DataTools.DisabledToolIds`, `DataTools.MinimumProviderConfidenceByToolId`, chat templates, and document analysis policies — use the ID of the collection for them. The ID of one of its tools counts for the whole collection, so naming it switches off the whole collection or sets its confidence; of several levels set for a collection and its tools, the highest applies. Tool settings stay with each tool and keep the `"<toolId>.<fieldName>"` keys.
 
+Users can switch off tools themselves in **Tool Settings**, for example, the Confluence search when they have no Confluence. A tool they switched off appears in no tool selection, and the AI cannot use it. This choice belongs to each user and is not part of a configuration. It can only take tools away: a tool you switch off with `DataTools.DisabledToolIds` stays off, and its switch is locked.
+
 ### Complete tool export
 
 For example, save a timeout of `30`, a content limit of `12000`, an empty private-host list, and free address choice switched off for **Read Web Page**. Select its General area, **Locked settings**, and **Include minimum provider confidence**. With its default confidence requirement of `VERY_LOW`, the export is:
@@ -795,7 +797,7 @@ Writing the `DataSourceOptions` table at all is already the statement that this
 | `SEMANTIC_SEARCH` (default) | The AI searches the data sources itself, through the tool `semantic_search`, whenever a question calls for it. No agent takes part: `AutomaticDataSourceSelection` lets the AI itself choose among all data sources it may use, and `AutomaticValidation` has no effect. |
 | `EVERY_MESSAGE` | AI Studio searches the data sources with every message, before the AI answers, with the agents for selection and validation as configured. |
 
-Semantic search only works where `semantic_search` can be offered: the model has to be able to call tools, neither `DataTools.EnableTools` nor `DataTools.DisabledToolIds` may switch it off, and the provider has to meet a minimum confidence you set for it in `DataTools.MinimumProviderConfidenceByToolId`. Otherwise, the chat searches with every message instead. A template that leaves `RetrievalMode` out gets `SEMANTIC_SEARCH`, not the chat default. That chat default is the setting `DataChat.PreselectedDataSourcesRetrievalMode`, with the same two values.
+Semantic search only works where `semantic_search` can be offered: the model has to be able to call tools, neither `DataTools.EnableTools` nor `DataTools.DisabledToolIds` may switch it off, nor may the user in **Tool Settings**, and the provider has to meet a minimum confidence you set for it in `DataTools.MinimumProviderConfidenceByToolId`. Otherwise, the chat searches with every message instead. A template that leaves `RetrievalMode` out gets `SEMANTIC_SEARCH`, not the chat default. That chat default is the setting `DataChat.PreselectedDataSourcesRetrievalMode`, with the same two values.
 
 When an [assistant plugin](../app/MindWork%20AI%20Studio/Plugins/assistants/README.md) opens a chat directly and its chat template names tools, data sources, a provider, or a profile, that template decides them alone; what the launcher names is dropped with a warning in the log. Its README explains the rule and how such sources are checked.
 

documentation/Tools.md

@@ -10,6 +10,7 @@ The provider only sees local tools that are
 
 - present in this installation, which a tool of a preview feature only is while the preview is switched on, and
 - available for the current component and
+- switched off neither by the organization nor by the user and
 - selected by the user or defaults, or offering themselves from the context of the chat, and
 - supported by the model and
 - configured correctly and
@@ -84,7 +85,7 @@ A result in `JsonContent` reaches the model the way `ToolExecutionResult.ToModel
 
 ## Tools Which Offer Themselves
 
-Most tools are selected: by the user, by the defaults of a component, by a chat template, or by the rules of an assistant. A tool whose use follows from the chat instead sets `Activation = ToolActivation.CONTEXT`. Nobody can select such a tool, so it appears in no selection. `ToolRegistry.GetCatalogAsync` leaves it out of every list built for a component, and `ToolRegistry.NormalizeSelection` drops it from a selection which names it anyway, such as the one of a chat template. The tool list of the app settings still shows it, so that an organization can switch it off or raise the confidence it requires. `semantic_search` is the only such tool so far.
+Most tools are selected: by the user, by the defaults of a component, by a chat template, or by the rules of an assistant. A tool whose use follows from the chat instead sets `Activation = ToolActivation.CONTEXT`. Nobody can select such a tool, so it appears in no selection. `ToolRegistry.GetCatalogAsync` leaves it out of every list built for a component, and `ToolRegistry.NormalizeSelection` drops it from a selection which names it anyway, such as the one of a chat template. The tool list of the app settings still shows it, so that the user or an organization can switch it off or raise the confidence it requires. `semantic_search` is the only such tool so far.
 
 The registry takes every context tool of the component as a candidate and runs it through the same checks as a selected one. A tool which passes them is then asked what it offers in this request, through `IToolImplementation.ResolveFunctionAsync`. Most tools leave that method alone and offer the function they registered. A tool which has to know the chat first returns a function tailored to it, or null when it has nothing to offer, and is then left out of the request. Only the description and the parameters of the answer count; the name and the strict mode stay as registered, because the calls of the model find their tool by its name. A resolution which throws costs that one tool and no other.
 
@@ -103,7 +104,7 @@ Paging stays stateless: every call brings its query and its page again. It has t
 
 ## Tool Collections
 
-Some tools only make sense together. Searching mails without being able to read the ones found gets in the way, and reading them with less trust than the search asks for would protect nothing. Such tools form a collection: people select it as one entry, it needs one minimum provider confidence, and an organization switches it off as one. The model still sees each of its tools on its own and calls each by its name.
+Some tools only make sense together. Searching mails without being able to read the ones found gets in the way, and reading them with less trust than the search asks for would protect nothing. Such tools form a collection: people select it as one entry, it needs one minimum provider confidence, and the user or an organization switches it off as one. The model still sees each of its tools on its own and calls each by its name.
 
 A collection is an `IToolCollection` class next to its tools, registered in `Program.cs`. It states its `ToolCollectionDefinition`: its ID, the IDs of its tools in the order they are listed, its minimum provider confidence, and a description for a model which picks the tools of an assistant. Its name, description, and icon come from its own members, so they can be translated. Whether it exists right now follows from its tools: it disappears with the last of them, e.g., while their preview is switched off. `ToolRegistry` registers collections after the tools and leaves out what it cannot accept: a collection taking the ID of a tool, a tool which is not registered or which offers itself from the context of a chat, and a tool another collection claimed first.
 
@@ -117,6 +118,16 @@ Three methods of the registry translate between both views:
 
 The settings of a tool stay with the tool, also inside a collection. An organization addresses them by `"<toolId>.<fieldName>"`, and the settings dialog of a collection shows one section per tool. `mailboxes` is the only declared collection so far, with `search_mails`, `read_mail`, and `count_mails`.
 
+## Switched-Off Tools
+
+A collection can be switched off twice: by an organization in `DataTools.DisabledToolIds`, and by the user in `DataTools.UserDisabledToolIds`, through the switch of its row in the tool settings. Somebody without a Confluence wiki never needs its search, and a tool which stays in every selection with a warning about its missing settings only gets in the way. The list of the user is not managed: it only takes tools away, and what the organization switched off stays off whatever it holds. Both lists name collections, like every other setting about tools.
+
+`ToolRegistry.IsToolActive` is the one gate for both lists. Every list, the preparation of a request, the token count, and `ToolRegistry.GetOfferBlockReasonAsync` ask it, so a switched-off tool is neither offered to the model nor run, without a check of its own; `ToolExecutor` runs only what the request offered. When both lists name a collection, the organization is the reason which counts, because switching the tool on again would not help the user: `TOOL_SWITCHED_OFF` comes before `TOOL_SWITCHED_OFF_BY_USER`. `ToolCatalogItem.SwitchOffReason` carries the reason, so the user interface can tell both apart.
+
+What the user switched off disappears; what the organization switched off stays visible, locked, because the user has to learn why the tool does not work. `ToolRegistry.GetCatalogAsync` for a component therefore leaves out the collections the user switched off, and every selection is built from it. The catalog of all definitions, which the tool settings and the settings dialog of a tool use, keeps them, or nobody could switch them on again.
+
+Switching a collection off only hides it. A chat, a chat template, a document analysis policy, the defaults of a component, or an assistant plugin which names it keeps naming it, and switching it on again brings it back there. A selection field therefore shows a selection through `ToolRegistry.LeaveOutSwitchedOffByUser` and stores a change through `ToolRegistry.KeepSwitchedOffByUser`, which puts the switched-off collections back. Where the rules of an assistant name a switched-off tool, `ManagedToolsWarning` says that the run goes without it. Switching off `semantic_search` has the data sources searched with every message, as when an organization does it.
+
 ## Security
 
 Treat model-provided tool arguments as untrusted input. Refuse a wrong one rather than guessing what it meant: a placeholder such as `0` is not a page, and reading it as "no page" does something the model did not ask for. The model reads the refusal and tries again, so the message has to name the argument and the value that arrived, say what would be valid, and, for an optional argument, that leaving it out is always possible. `ToolArgumentReader` reads strings, positive integers, and values out of a fixed choice, alone or as a list, and words the refusals so; `WebSearchTool` shows how a tool uses it.