Table of Contents

Understanding Tools in Agentic AI


TL;DR

Tools are external functions that extend language models beyond text generation, enabling AI agents to interact with the real world. By invoking tools, models can search databases, call APIs, execute code, read files, and perform calculations, transforming conversational systems into practical agents that ground their responses in real data and accomplish concrete tasks.


What Exactly are Tools?

Tools, also known as function calling or tool calling, are structured interfaces that allow language models to delegate specific tasks to external capabilities. Rather than attempting to generate all information from learned parameters, models can:

  • Recognize when a task requires external data or computation
  • Invoke the appropriate tool with structured arguments
  • Incorporate the tool's result into their reasoning and response

Think of tools as the hands and eyes of an AI agent. While the language model provides the brain, understanding, reasoning, and planning, tools provide the ability to:

  • Fetch current information (weather, stock prices, news)
  • Perform precise calculations (currency conversion, unit conversion)
  • Access external systems (databases, APIs, file systems)
  • Execute code or scripts
  • Interact with business logic and domain-specific services

Why Use Tools?

  1. Grounded Responses: Eliminate hallucinations by fetching real-time data instead of generating plausible-sounding but incorrect information.
  2. Extended Capabilities: Break free from the model's training cutoff and knowledge limitations by accessing current external information.
  3. Deterministic Operations: Delegate mathematical calculations, data transformations, and precise operations to tools rather than relying on approximations.
  4. Workflow Automation: Chain multiple tools together to accomplish complex, multi-step tasks in a single conversational turn.
  5. Domain Specialization: Connect models to proprietary databases, internal APIs, and business-specific services without retraining.

Technical Insights on Tools

The Tool Calling Lifecycle

Tool calling follows a structured request-response pattern:

  1. Registration: Tools are registered with their metadata:

    • Name: Unique identifier (e.g., get_weather)
    • Description: Natural language explanation of purpose
    • Input Schema: JSON Schema defining expected arguments

  2. Invocation Decision: The model analyzes the user's query and determines:

    • Whether a tool is needed
    • Which tool(s) to invoke
    • What arguments to pass

  3. Argument Construction: The model generates structured JSON matching the tool's schema:

    {
  "city": "Paris",
  "units": "metric"
}

  4. Execution: The runtime parses arguments, validates against the schema, and executes the tool.

  5. Result Injection: The tool's output is injected back into the conversation context:

    {
  "temperature": 18,
  "conditions": "partly cloudy",
  "humidity": 65
}

  6. Response Generation: The model uses the tool result to formulate a grounded, accurate answer.

Tool Calling Modes

Modern systems support multiple execution patterns:

  • Simple Function: One tool, one call per turn
  • Multiple Function: Sequential tool chaining (tool A → result → tool B → result)
  • Parallel Function: Concurrent execution of multiple independent tools
  • Parallel Multiple Function: Combining sequential chaining with parallel execution

Practical Use Cases for Tools

  • Real-Time Data Access: Weather forecasts, stock quotes, exchange rates, current events
  • Calculations & Conversions: Unit conversions, mathematical operations, date/time calculations
  • Information Retrieval: Database queries, document search, knowledge base lookups
  • External Service Integration: Email sending, calendar management, task creation
  • Code Execution: Running scripts, data analysis, file processing
  • Validation & Verification: Fact-checking, data validation, compliance checks

Key Terms

  • Tool/Function: An external capability with a defined interface that the model can invoke
  • Tool Schema: JSON Schema specification defining expected input parameters and types
  • Tool Call: A structured request from the model to execute a specific tool with arguments
  • Tool Result: The structured output returned by a tool after execution
  • Tool Policy: Runtime configuration controlling tool selection, execution limits, and safety constraints
  • Tool Registry: Collection of available tools registered for a conversation or agent. In LM-Kit.NET, the ToolRegistry also holds a PermissionPolicy property and provides an EvaluatePermission() method for checking tool access at runtime.
  • Tool Metadata: Structured information about a tool's behavior exposed through the IToolMetadata interface. Includes the tool's category, side effect type (ToolSideEffect), risk level (ToolRiskLevel), default approval mode (ToolApprovalMode), and boolean flags for idempotency and read-only behavior. All LM-Kit.NET built-in tools provide metadata automatically, and custom tools can implement IToolMetadata for the same benefits.
  • Tool Risk Level: A classification (ToolRiskLevel) indicating how dangerous a tool is to execute. The four levels are Low (pure computation, no side effects), Medium (local reads or idempotent network reads), High (local writes or network writes), and Critical (irreversible actions such as process execution or email sending). Use BuiltInTools.GetByMaxRisk() to filter tools by their maximum acceptable risk.
  • Tool Permission Policy: A runtime policy (ToolPermissionPolicy) that governs which tools an agent is allowed to call. Built with a fluent API supporting Allow(), Deny(), AllowCategory(), DenyCategory(), RequireApproval(), RequireApprovalForCategory(), and SetMaxRiskLevel(). The policy evaluates each tool call and returns a ToolPermissionResult of Allowed, Denied, or ApprovalRequired. Attach a policy to an agent via AgentBuilder.WithPermissionPolicy() or set it on ToolRegistry.PermissionPolicy.
  • Tool Approval: A human-in-the-loop mechanism triggered when a ToolPermissionPolicy returns ApprovalRequired for a tool call. The ToolApprovalRequired event fires on MultiTurnConversation and AgentExecutor with ToolApprovalRequestEventArgs, which includes the pending ToolCall, Tool, RiskLevel, SideEffect, and an Approved property. Set Approved = true to allow the call, or leave it false (the default) to deny it. If no handler is subscribed, the tool call is denied by default. This enables interactive confirmation workflows for sensitive operations.
  • MCP (Model Context Protocol): Standardized protocol for discovering and invoking external tool catalogs

Tools in LM-Kit.NET

In LM-Kit.NET, tools integrate seamlessly into multi-turn conversations with three flexible registration approaches and comprehensive safety controls:

Approach 1: ITool Implementation (Full Control)

public sealed class WeatherTool : ITool
{
    public string Name => "get_weather";
    public string Description => "Get current weather for a city";
    
    public string InputSchema => """
    {
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "City name"}
        },
        "required": ["city"]
    }
    """;

    public async Task<string> InvokeAsync(string arguments, CancellationToken ct)
    {
        var city = JsonDocument.Parse(arguments)
            .RootElement.GetProperty("city").GetString();
        var data = await FetchWeatherAsync(city);
        return JsonSerializer.Serialize(new { city, temp = data.Temp });
    }
}

// Register and use
var model = LM.LoadFromModelID("glm4.7-flash");
using var chat = new MultiTurnConversation(model);
chat.Tools.Register(new WeatherTool());

Approach 2: Method Annotations (Quick Prototyping)

public sealed class MyTools
{
    [LMFunction("convert_currency", "Convert amount between currencies")]
    public string ConvertCurrency(decimal amount, string from, string to)
    {
        var rate = GetExchangeRate(from, to);
        return JsonSerializer.Serialize(new { result = amount * rate });
    }
}

// Auto-register all annotated methods
var tools = LMFunctionToolBinder.FromType<MyTools>();
chat.Tools.Register(tools);

Approach 3: MCP Integration (External Catalogs)

// Import tools from MCP server
var mcp = new McpClient(
    new Uri("https://mcp.example.com/api"), 
    new HttpClient()
);
chat.Tools.Register(mcp);

Safety and Policy Controls

// Configure tool behavior
chat.ToolPolicy = new ToolCallPolicy
{
    Choice = ToolChoice.Auto,        // Let model decide
    MaxCallsPerTurn = 3,             // Prevent runaway loops
    AllowParallelCalls = false       // Sequential execution only
};

// Human-in-the-loop approval via event
chat.BeforeToolInvocation += (sender, e) =>
{
    Console.WriteLine($"About to call: {e.ToolCall.Name}");
    // Access tool metadata and permission result
    Console.WriteLine($"  Risk: {e.Tool?.RiskLevel}, Permission: {e.PermissionResult}");
    if (RequiresApproval(e.ToolCall.Name))
    {
        e.Cancel = !PromptUserApproval();
    }
};

// Audit and logging
chat.AfterToolInvocation += (sender, e) =>
{
    LogToolExecution(e.ToolCallResult);
};

Permission Policies

using LMKit.Agents.Tools;

// Define a permission policy with the fluent API
var policy = new ToolPermissionPolicy()
    .AllowCategory("Data")
    .AllowCategory("Numeric")
    .DenyCategory("IO")
    .RequireApproval("web_search")
    .SetMaxRiskLevel(ToolRiskLevel.Medium);

// Attach to an agent
var agent = Agent.CreateBuilder(model)
    .WithPermissionPolicy(policy)
    .WithTools(tools =>
    {
        tools.Register(BuiltInTools.CalcArithmetic);
        tools.Register(BuiltInTools.WebSearch);
    })
    .Build();

// Handle approval requests
using var executor = new AgentExecutor();
executor.ToolApprovalRequired += (sender, e) =>
{
    Console.Write($"Approve {e.ToolCall.Name}? (y/n): ");
    e.Approved = Console.ReadLine()?.Trim() == "y";
};

LM-Kit.NET Built-in Tools

LM-Kit.NET includes a comprehensive set of ready-to-use tools organized by category in the LMKit.Agents.Tools.BuiltIn namespace:

Category Tools
Data Json, Xml, Csv, Ini, Html, Yaml, Markdown, QRCode, Database, Spreadsheet
Text Text, Diff, Regex, Template, Encoding, Slug, AsciiArt
Numeric Calculator, Conversion, Stats, Random, Guid, Financial
Security Hash, Crypto, Validator, Jwt, Password, Checksum
Utility DateTime, Cron, SemVer, Url, Color, Performance, TimeZone
IO FileSystem, Environment, Process, Compress, Watch, Clipboard
Net Http, Network, WebSearch, Smtp, RssFeed, Ftp
Document PdfSplit, PdfInfo, PdfToImage, PdfMerge, ImageToPdf, PdfUnlock, ImageDeskew, ImageCrop, ImageResize, DocumentText, Ocr, MarkdownToPdf, EmlToPdf, HtmlToMarkdown, MarkdownToHtml, DocxToMarkdown, MarkdownToDocx, EmlToMarkdown, MboxToMarkdown

Access tools through the BuiltInTools factory class.


  • ITool: Interface for implementing custom tools
  • IToolMetadata: Interface exposing tool category, risk level, side effects, and approval mode
  • ToolRegistry: Manages tool collections, with PermissionPolicy and EvaluatePermission() support
  • ToolPermissionPolicy: Fluent policy for allowing, denying, or requiring approval for tools
  • ToolCallPolicy: Configures tool execution behavior
  • LMFunctionAttribute: Annotate methods for tool binding
  • McpClient: Connect to MCP servers for external tools


External Resources


Summary

Tools transform language models from text generators into practical agents capable of real-world interaction. By providing structured interfaces for external capabilities, tools enable models to ground their responses in current data, perform precise operations, and automate complex workflows, all while maintaining safety through validation, policy controls, and human oversight. In LM-Kit.NET, tools run entirely on-device, preserving privacy while delivering the power of agentic AI.

Share