included documentation how to add tools

AGENTS.md

@@ -119,6 +119,19 @@ When adding configuration options, update:
 - `app/MindWork AI Studio/Tools/PluginSystem/PluginConfigurationObject.cs` for parsing logic of complex configuration objects.
 - `app/MindWork AI Studio/Plugins/configuration/plugin.lua` to document the new configuration option.
 
+## Tool Calling System
+
+**Documentation:** `documentation/Tools.md`
+
+When adding, changing, or removing model-driven tools, keep these parts in sync:
+- `app/MindWork AI Studio/wwwroot/tool_definitions/` for the tool JSON definition.
+- `app/MindWork AI Studio/Tools/ToolCallingSystem/ToolCallingImplementations/` for the `IToolImplementation` class.
+- `app/MindWork AI Studio/Program.cs` for DI registration of the implementation.
+- `app/MindWork AI Studio/Tools/ToolCallingSystem/ToolSelectionRules.cs` when default tool dependencies or minimum provider confidence rules change.
+- `app/MindWork AI Studio/Plugins/configuration/plugin.lua` when administrators can configure or manage the tool or its settings.
+
+Tool implementations must treat model-provided arguments as untrusted input. Validate settings and arguments, protect secrets with `SensitiveTraceArgumentNames`, use `ToolExecutionBlockedException` for intentional policy blocks, and check provider confidence before returning sensitive data to the model.
+
 ## RAG (Retrieval-Augmented Generation)
 
 RAG integration is currently in development (preview feature). Architecture:
@@ -214,4 +227,4 @@ following words:
 - Downgraded
 - Upgraded
 
-The entire changelog is sorted by these categories in the order shown above. The language used for the changelog is US English.
+The entire changelog is sorted by these categories in the order shown above. The language used for the changelog is US English.

README.md

@@ -185,6 +185,8 @@ If you're interested in learning more about future plans, check out our [roadmap
 
 You want to know how to build MindWork AI Studio from source? [Check out the instructions here](documentation/Build.md).
 
+Do you want to add or maintain model-driven tools? [Read the tool development guide here](documentation/Tools.md).
+
 </details>
 
 <details>
@@ -213,4 +215,4 @@ MindWork AI Studio is licensed under the `FSL-1.1-MIT` license (functional sourc
 
 For more details, refer to the [LICENSE](LICENSE.md) file. This license structure ensures you have plenty of freedom to use and enjoy the software while protecting our work.
 
-</details>
+</details>

app/MindWork AI Studio/Plugins/configuration/plugin.lua

@@ -213,13 +213,12 @@ CONFIG["SETTINGS"] = {}
 -- CONFIG["SETTINGS"]["DataApp.ShortcutVoiceRecording"] = "CmdOrControl+1"
 
 -- Configure the minimum provider confidence level required for individual tools.
--- Tool IDs include: web_search, read_web_page, get_current_weather
+-- Tool IDs include: web_search, read_web_page
 -- Allowed values are: NONE, UNTRUSTED, VERY_LOW, LOW, MODERATE, MEDIUM, HIGH
--- Defaults: web_search = MEDIUM, read_web_page = MEDIUM, get_current_weather = NONE
+-- Defaults: web_search = MEDIUM, read_web_page = MEDIUM, but higher confidence is recommended
 -- CONFIG["SETTINGS"]["DataTools.MinimumProviderConfidenceByToolId"] = {
 --     ["web_search"] = "MEDIUM",
---     ["read_web_page"] = "MEDIUM",
+--     ["read_web_page"] = "MEDIUM"
---     ["get_current_weather"] = "NONE"
 -- }
 
 -- Configure private or VPN hosts that the Read Web Page tool may access.

app/MindWork AI Studio/wwwroot/changelog/v26.3.1.md

@@ -8,6 +8,7 @@
 - Added math rendering in chats for LaTeX display formulas, including block formats such as `$$ ... $$` and `\[ ... \]`.
 - Added the latest OpenAI models.
 - Added minimum provider confidence settings for tools, so sensitive tools such as web search can be limited to trusted providers. Configuration plugins can also manage these defaults for organizations.
+- Added documentation for developers who want to add or maintain tools in AI Studio.
 - Released the document analysis assistant after an intense testing phase.
 - Improved enterprise deployment for organizations: administrators can now provide up to 10 centrally managed enterprise configuration slots, use policy files on Linux and macOS, and continue using older configuration formats as a fallback during migration.
 - Improved the profile selection for assistants and the chat. You can now explicitly choose between the app default profile, no profile, or a specific profile.
@@ -30,3 +31,4 @@
 - Fixed security issues in the native app runtime by strengthening how AI Studio creates and protects the secret values used for its internal secure connection.
 - Updated several security-sensitive Rust dependencies in the native runtime to address known vulnerabilities.
 - Updated .NET to v9.0.14
+- Removed the internal demo weather tool from the tool list.

documentation/Tools.md

@@ -0,0 +1,176 @@
+# Tool Development
+
+This document explains how model-driven tools are added to AI Studio. Tool calling let a model request a small, well-defined action during a chat or assistant run, such as searching the web or reading a web page.
+
+Tools are part of the .NET app. They are not Lua plugins and they are not loaded dynamically from user folders. Adding a tool requires code changes.
+
+## Architecture
+
+A tool has two parts:
+
+- A JSON definition in `app/MindWork AI Studio/wwwroot/tool_definitions/`
+- A C# implementation of `IToolImplementation` in `app/MindWork AI Studio/Tools/ToolCallingSystem/ToolCallingImplementations/`
+
+At startup, `ToolRegistry` reads all JSON definitions and matches each definition to a registered implementation by `implementationKey`. `ToolExecutor` runs the implementation when a provider returns a matching function call.
+
+The provider only sees tools that are available for the current component, selected by the user or defaults, supported by the model, configured correctly, and allowed by the provider confidence rules.
+
+## Definition File
+
+Create one JSON file per tool under `wwwroot/tool_definitions`. The file describes the user-visible tool metadata, optional settings, and the function schema sent to the model.
+
+Example:
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "get_current_weather",
+  "implementationKey": "get_current_weather",
+  "visibleIn": {
+    "chat": true,
+    "assistants": true
+  },
+  "settingsSchema": {
+    "type": "object",
+    "properties": {
+      "demoLabel": {
+        "type": "string",
+        "secret": false
+      }
+    },
+    "required": [
+      "demoLabel"
+    ]
+  },
+  "function": {
+    "name": "get_current_weather",
+    "description": "Get the current weather in a given location.",
+    "strict": true,
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "city": {
+          "type": "string",
+          "description": "The city to find the weather for, e.g. 'San Francisco'."
+        },
+        "state": {
+          "type": "string",
+          "description": "The two-letter abbreviation for the state, e.g. 'CA'."
+        },
+        "unit": {
+          "type": "string",
+          "description": "The unit to fetch the temperature in.",
+          "enum": [
+            "celsius",
+            "fahrenheit"
+          ]
+        }
+      },
+      "required": [
+        "city",
+        "state",
+        "unit"
+      ],
+      "additionalProperties": false
+    }
+  }
+}
+```
+
+Use stable lower-case IDs with underscores. Keep `id`, `implementationKey`, and `function.name` identical unless there is a clear compatibility reason not to.
+
+## Implementation
+
+Implement `IToolImplementation` and register the class in `Program.cs` as an `IToolImplementation`.
+
+Example:
+
+```csharp
+using System.Text.Json;
+using AIStudio.Tools.PluginSystem;
+
+namespace AIStudio.Tools.ToolCallingSystem.ToolCallingImplementations;
+
+public sealed class GetCurrentWeatherTool : IToolImplementation
+{
+    private static string TB(string fallbackEN) => I18N.I.T(fallbackEN, typeof(GetCurrentWeatherTool).Namespace, nameof(GetCurrentWeatherTool));
+
+    public string ImplementationKey => "get_current_weather";
+
+    public string Icon => Icons.Material.Filled.Cloud;
+
+    public IReadOnlySet<string> SensitiveTraceArgumentNames => new HashSet<string>(StringComparer.Ordinal);
+
+    public string GetDisplayName() => TB("Current Weather");
+
+    public string GetDescription() => TB("Use this demo tool to retrieve the current weather for a given city and state.");
+
+    public string GetSettingsFieldLabel(string fieldName, ToolSettingsFieldDefinition fieldDefinition) => fieldName switch
+    {
+        "demoLabel" => TB("Demo Label"),
+        _ => TB(fieldDefinition.Title),
+    };
+
+    public string GetSettingsFieldDescription(string fieldName, ToolSettingsFieldDefinition fieldDefinition) => fieldName switch
+    {
+        "demoLabel" => TB("Required demo setting for validating tool settings."),
+        _ => TB(fieldDefinition.Description),
+    };
+
+    public Task<ToolExecutionResult> ExecuteAsync(JsonElement arguments, ToolExecutionContext context, CancellationToken token = default)
+    {
+        var city = arguments.TryGetProperty("city", out var cityValue) ? cityValue.GetString() ?? string.Empty : string.Empty;
+        var state = arguments.TryGetProperty("state", out var stateValue) ? stateValue.GetString() ?? string.Empty : string.Empty;
+        var unit = arguments.TryGetProperty("unit", out var unitValue) ? unitValue.GetString() ?? string.Empty : string.Empty;
+
+        if (unit is not ("celsius" or "fahrenheit"))
+            throw new ArgumentException($"Invalid unit '{unit}'.");
+
+        return Task.FromResult(new ToolExecutionResult
+        {
+            TextContent = $"The weather in {city}, {state} is 85 degrees {unit}.",
+        });
+    }
+}
+```
+
+Register it:
+
+```csharp
+builder.Services.AddSingleton<IToolImplementation, GetCurrentWeatherTool>();
+```
+
+The example above is documentation-only. Do not keep demo tools in the production tool catalog.
+
+## Settings And Secrets
+
+Tool settings are stored through `ToolSettingsService`. Plain settings are stored in the regular configuration data. Settings marked with `"secret": true` are stored in the OS keyring through the Rust service.
+
+Use `ValidateConfigurationAsync` when a setting needs more than "required field is present" validation, such as URL syntax, numeric limits, mutually exclusive options, or allowlist parsing.
+
+Use `SensitiveTraceArgumentNames` for model-provided arguments that must not be shown in tool traces. Do not return secrets in `TextContent`, `JsonContent`, exception messages, logs, or trace formatting.
+
+## Security
+
+Treat model-provided tool arguments as untrusted input.
+
+For tools that perform network requests:
+
+- Accept only the schemes and hosts that are required for the feature.
+- Validate redirects before following them.
+- Do not allow model-supplied URLs to access localhost, loopback, link-local, multicast, or private network targets unless the feature has an explicit policy for that.
+- Check `ToolExecutionContext.ProviderConfidence` before returning sensitive data to the model.
+- Throw `ToolExecutionBlockedException` for intentional policy blocks so the UI can show the call as blocked instead of failed.
+
+For settings that administrators should be able to manage centrally, add the setting to the appropriate `Settings/DataModel` class, register it with `ManagedConfiguration.Register(...)`, process it in `PluginConfiguration`, clean leftovers in `PluginFactory.Loading`, and document it in `Plugins/configuration/plugin.lua`.
+
+## Checklist
+
+- Add the JSON definition in `wwwroot/tool_definitions`.
+- Add the `IToolImplementation` class.
+- Register the implementation in `Program.cs`.
+- Validate settings and model arguments.
+- Protect secrets and sensitive trace arguments.
+- Add provider-confidence checks when tool output may contain sensitive data.
+- Update configuration plugin documentation when admins can manage the setting.
+- Add a changelog entry when users or administrators are affected.