Interface ITool

Namespace: LMKit.Agents.Tools

Assembly: LM-Kit.NET.dll

Defines the contract for a tool that can be invoked by language models through an agent.

public interface ITool

Examples

Example: Implementing a weather tool

using LMKit.Agents.Tools;
using System.Net.Http.Json;
using System.Text.Json;

public class WeatherTool : ITool
{
    private readonly HttpClient _httpClient = new();

    public string Name => "get_weather";

    public string Description => "Get current weather conditions for a location";

    public string InputSchema => """
        {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City name or coordinates (e.g., 'Paris, FR' or '48.8566,2.3522')"
                },
                "units": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "default": "celsius",
                    "description": "Temperature units"
                }
            },
            "required": ["location"]
        }
        """;

    public async Task<string> InvokeAsync(string arguments, CancellationToken cancellationToken = default)
    {
        var args = JsonSerializer.Deserialize<WeatherArgs>(arguments);

        // Call weather API (simplified example)
        var response = await _httpClient.GetFromJsonAsync<WeatherResponse>(
            $"https://api.weather.com/current?location={args.Location}&units={args.Units}",
            cancellationToken);

        return JsonSerializer.Serialize(new
        {
            location = args.Location,
            temperature = response.Temperature,
            conditions = response.Conditions,
            humidity = response.Humidity
        });
    }

    private record WeatherArgs(string Location, string Units = "celsius");
    private record WeatherResponse(double Temperature, string Conditions, int Humidity);
}

Example: Implementing a database query tool

using LMKit.Agents.Tools;
using System.Text.Json;

public class DatabaseQueryTool : ITool
{
    private readonly IDbConnection _connection;

    public DatabaseQueryTool(IDbConnection connection)
    {
        _connection = connection;
    }

    public string Name => "query_database";

    public string Description => "Execute a read-only SQL query against the database";

    public string InputSchema => """
        {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "SQL SELECT query to execute"
                },
                "maxRows": {
                    "type": "integer",
                    "default": 100,
                    "description": "Maximum rows to return"
                }
            },
            "required": ["query"]
        }
        """;

    public async Task<string> InvokeAsync(string arguments, CancellationToken cancellationToken = default)
    {
        var args = JsonSerializer.Deserialize<QueryArgs>(arguments);

        // Validate query is read-only
        if (!args.Query.TrimStart().StartsWith("SELECT", StringComparison.OrdinalIgnoreCase))
        {
            throw new ArgumentException("Only SELECT queries are allowed");
        }

        // Execute and return results as JSON
        var results = await ExecuteQueryAsync(args.Query, args.MaxRows, cancellationToken);
        return JsonSerializer.Serialize(new { rows = results, count = results.Count });
    }

    private record QueryArgs(string Query, int MaxRows = 100);
}

Remarks

Implement this interface to create custom tools that agents can use to perform actions, retrieve data, or interact with external systems. The language model discovers tools through their Name and Description, uses InputSchema to construct valid arguments, and calls InvokeAsync(string, CancellationToken) with JSON arguments.

Tool Design Guidelines

Naming: Use lowercase snake_case names (e.g., get_weather, search_database). Keep names stable across versions to avoid breaking model behavior.
Description: Write a concise, imperative summary (under 200 characters recommended). This text directly influences when the model chooses to use the tool.
Schema: Define a clear JSON Schema with explicit types, required fields, and descriptions for each parameter. Avoid deeply nested or ambiguous structures.
Output: Return compact, structured JSON. The model processes this output to formulate its response.

Alternative: Attribute-Based Tools
For simpler cases, consider using LMFunctionAttribute on methods instead of implementing ITool directly. The ToolRegistry can automatically discover and wrap annotated methods.

Properties

Description: Gets a concise description of what the tool does.

InputSchema: Gets the JSON Schema defining the expected input arguments.

Name: Gets the stable, unique identifier for this tool.

Methods

InvokeAsync(string, CancellationToken): Executes the tool with the specified JSON arguments.

Table of Contents

Interface ITool

Examples

Remarks

Properties

Methods