Tools & Keyed DI

Tools are the agent's hands. A skill says "I need file_system" and the harness resolves an implementation, wraps it in safety guarantees, and presents it to the LLM as a callable function. The pattern is more interesting than it looks — let's open the hood.

The ITool interface

Every internal tool implements one interface. It looks roughly like this:

public interface ITool
{
    string Name { get; }                                  // "file_system"
    string Description { get; }                           // "Reads files from disk under sandbox"
    IReadOnlyList<string> SupportedOperations { get; }    // ["read", "list", "write"]

    // Concurrency + risk metadata — all defaulted, override only when it differs:
    bool IsReadOnly => false;                             // read-only tools can batch in parallel
    bool IsConcurrencySafe => false;                      // fail-closed: assume not safe
    BlastRadius RiskTier => BlastRadius.Medium;           // feeds the graded-autonomy gate
    ToolOutputCategory? OutputCategory => null;           // null ⇒ sniff the output at runtime
    int? CompressionTokenThreshold => null;               // null ⇒ use the global default

    Task<ToolResult> ExecuteAsync(
        string operation,
        IReadOnlyDictionary<string, object?> parameters,
        CancellationToken cancellationToken = default);
}

One tool can expose multiple operations. file_system is a single ITool with operations read, list, write. This keeps the tool surface focused — the LLM sees one entry "file system" rather than three separate ones.

Keyed DI — the heart of the pattern

Tools are registered as keyed singletons in Infrastructure.AI/DependencyInjection.Tools.cs. Each tool exposes its key as a ToolName constant, and each registration is a factory lambda so the tool can pull its own collaborators from the container:

services.AddKeyedSingleton<ITool>(FileSystemTool.ToolName, (sp, _) =>
    new FileSystemTool(sp.GetRequiredService<IFileSystemService>()));

services.AddKeyedSingleton<ITool>(EchoCalculateTool.ToolName, (_, _) => new EchoCalculateTool());

services.AddKeyedSingleton<ITool>(DocumentSearchTool.ToolName, (sp, _) =>
    new DocumentSearchTool(sp.GetRequiredService<IRagOrchestrator>()));

services.AddKeyedSingleton<ITool>(RestrictedSearchTool.ToolName, (sp, _) =>
    new RestrictedSearchTool(/* ... */));
// ...

The real built-in tools are FileSystemTool (file_system), EchoCalculateTool (echo_calculate), RestrictedSearchTool (restricted_search), DocumentSearchTool (document_search), and the generative-UI render tools (Chapter 16). There is no CalculationTool or WebSearchTool — those names are historical.

When AgentFactory processes a skill's allowed-tools list, it does exactly:

foreach (var toolName in skill.AllowedTools)
{
    var tool = serviceProvider.GetRequiredKeyedService<ITool>(toolName);
    var aiTool = _toolConverter.Convert(tool, skill.AllowedOperations(toolName));
    aiTools.Add(aiTool);
}

From ITool to AITool

The LLM doesn't know about ITool. It speaks the Microsoft.Extensions.AI.AITool contract — a JSON-schema'd function with a callback. The bridge is AIToolConverter:

var aiFunction = AIFunctionFactory.Create(
    async (string operation, JsonElement? parametersJson, CancellationToken ct) =>
    {
        if (!activeOperations.Contains(operation, StringComparer.OrdinalIgnoreCase))
            return $"Error: Operation '{operation}' is not available.";

        var parameters = ParseParameters(parametersJson);
        var result = await tool.ExecuteAsync(operation, parameters, ct);
        return result.Success ? result.Output ?? "OK" : $"Error: {result.Error}";
    },
    new AIFunctionFactoryOptions
    {
        Name = tool.Name,
        Description = description    // built from purpose + operations + param hints
    });

The LLM sees a function called e.g. file_system that takes two parameters: operation (one of the supported ops) and parametersJson (a JSON object of operation-specific arguments). When the LLM calls it, the converter routes to tool.ExecuteAsync.

Operation filtering by skill

A skill can declare not just which tools it can use but which operations within each tool. The converter respects this — only operations in the intersection of skill.allowed-tools and tool.SupportedOperations are exposed to the LLM. This is how a "read-only research" skill prevents the agent from invoking file_system.write.

The file system sandbox — case study

FileSystemTool (in Infrastructure.AI/Tools/) is the ITool the agent calls; it delegates to FileSystemService, which implements IFileSystemService and is the canonical example of why this architecture matters. Every operation goes through a path validator:

private bool IsPathAllowed(string requestedPath)
{
    var absolute = Path.GetFullPath(requestedPath);
    return _allowedBasePaths.Any(allowed =>
        absolute.StartsWith(Path.GetFullPath(allowed), StringComparison.OrdinalIgnoreCase));
}

Allowed paths come from AppConfig.Infrastructure.FileSystem.AllowedBasePaths. Path traversal attacks (../../etc/passwd) are caught because Path.GetFullPath normalizes before comparison.

MCP tools join the same tool surface

Tools discovered on external MCP servers do not go through ITool. McpToolProvider casts the SDK's McpClientTool straight to Microsoft.Extensions.AI.AITool and hands the list to the agent — no wrapper class, no per-tool keyed DI. Once converted they sit alongside the internal tools in ChatOptions.Tools, so the agent doesn't know or care that github_create_issue lives on a remote MCP server. Both internal (ITool→AITool) and MCP (McpClientTool→AITool) tools are then wrapped by GovernedAIFunction (see below), so governance applies uniformly regardless of source. See MCP Server & Client for the discovery flow.

Invocation-time governance — GovernedAIFunction

Every converted tool — internal, MCP, or plugin-provided — is wrapped one more time by GovernedAIFunction (Application.AI.Common/Services/Tools/). It derives from DelegatingAIFunction, so the tool's name, description, and JSON schema pass through unchanged; only the invocation is intercepted. This is the single chokepoint for the agent's autonomous tool calls. On each call, InvokeCoreAsync runs three ambient gates in order, then executes, then optionally scrubs:

Risk tiers & blast radius

Each ITool declares its intrinsic RiskTier — a BlastRadius value (Trivial, Low, Medium, High, Critical) describing how much damage a single call can do. The default is Medium, but tools should override it: a read-only lookup as Trivial/Low, a tool that runs commands or touches production state as High/Critical. The tier flows straight into the graded-autonomy engine (gate 1 above) — higher autonomy tiers may auto-approve low-radius tools while still requiring human approval for high-radius ones — and it sets the severity when a call escalates. IToolRiskClassifier / ToolRiskClassifier resolve the effective tier.

Local plugin system

Beyond built-in tools and MCP-discovered tools, the harness supports local plugins — external directories that bundle their own skills and MCP servers. Declare plugins in appsettings.json:

"Plugins": {
  "Declarations": [
    {
      "Id": "code-analysis",
      "Path": "./plugins/code-analysis",
      "AllowedTools": ["file_system", "ast_parser"],
      "DeniedTools": ["file_system_write"],
      "AutonomyLevel": "Supervised"
    }
  ]
}

Each plugin directory contains a plugin.json manifest that lists its skills and MCP server endpoints. At startup, IPluginLoader reads the manifest, IPluginManifestReader parses it, and IPluginRegistry tracks the loaded plugins. Skills from plugins are loaded as Injected mode — they receive all MCP tools from their plugin's servers automatically.

Generative-UI render tools

One special tool family lets the agent render inline UI in a connected browser instead of returning text: render_image, render_form, render_table, and render_chart. They share a base class (SingleRenderProxyTool) and a client round-trip bridge, and they're deduplicated so the model sees one tool per widget. The full flow — backend tools, the frontend {render, validate, ack} registry, widget persistence, and the acting Dashboard agent — is its own chapter. See Chapter 16 · Generative UI & Widgets.

Tool output compression

Tools can return large outputs — a diagnostic dump, a JSON API response, or a verbose XML document. Sending all of this to the LLM wastes tokens and can exceed context limits. The ToolOutputCompressionBehavior MediatR pipeline behavior solves this by compressing tool outputs before they reach the agent.

How it works: each tool declares an OutputCategory (of type ToolOutputCategory), or leaves it null and lets ContentTypeDetector sniff the output at runtime. Based on the category, a strategy is selected:

Compression only triggers when the output exceeds a token threshold — the global ToolOutputCompressionConfig.DefaultTokenThreshold (default 2000 tokens, under AppConfig.AI.ToolOutputCompression), or a per-tool override via ITool.CompressionTokenThreshold. Below that, tool output passes through unchanged. When LlmFallbackEnabled is set, an economy-tier model summarizes FreeText that heuristics can't shrink enough.

Where each tool lives in the repo

Observability

Every tool invocation is wrapped in an OpenTelemetry span by the chat client middleware. The span includes the tool name, the operation, latency, and success/failure. ToolExecutionMetrics also emits a Counter per invocation. When an agent goes off the rails, the first place to look is the tool-call sequence in a Jaeger trace — see Observability & Safety.

Where to go from here