LlmTornado

Function Tools ​

Overview ​

Function tools enable agents to perform actions beyond text generation by calling C# methods. Agents can decide when and how to use tools based on the user's request.

Quick Start ​

csharp
using LlmTornado.Agents;

// Define tool functions
[Description("get the weather")]
[ToolName("GetWeatherTool")] //optional attribute to override tool name
string GetWeather([Description("city to get weather from")] string city)
{
    return $"Weather in {city}: 22°C, Sunny";
}

[Description("perform add Or multiply math Calculation")]
string Calculate(
[Description("math operation to perform (add or multiply)")] 
string operation, 
double a, double b)
{
    double result =  operation switch
    {
        "add" => a + b,
        "multiply" => a * b,
        _ => 0
    };

    return result.ToString();
}

// Create agent with tools
TornadoAgent agent = new TornadoAgent(
    client: api,
    model: ChatModel.OpenAi.Gpt41.V41,
    instructions: "You are a helpful assistant with weather and calculation tools.",
    tools: [GetWeather, Calculate]  
);

Conversation result = await agent.RunAsync("What's the weather in Prague?");

Tool Definition ​

  • [Description(" some description ")] Attribute can be applied to both Methods, and method Parameters to provide additional context
  • [ToolName("ToolName")] Attribute can be applied to method to override the Function name (Required for lambda functions)

Simple Function Tool ​

csharp
[Description("Description")]
[ToolName("ToolName")] //optional attribute to override tool name
string MyTool([Description("Description")]string param1, [Description("Description")]string param2)
{
    // Tool implementation
    return $"Result: {param1} - {param2}";
}

TornadoAgent agent = new TornadoAgent(
    api, model,
    tools: [MyTool] 
);

Advanced Tool definitions ​

More advanced tool definitions should be added using the Core LlmTornado methodology

csharp
TornadoAgent agent = new TornadoAgent(api, model);

Tool checkBank =  new Tool(
        ([SchemaAnyOf(typeof(PayPal), typeof(BankTransfer))] IList<IPaymentMethod> paymentMethod, ToolArguments args) =>
        {
            // model sometimes creates only one, flaky
            Assert.That(paymentMethod.Count, Is.GreaterThan(0));
            return $"Payment processed using {paymentMethod.GetType().Name}";
        }
    )

Tool getOrder = new Tool(
        new ToolFunction("get_order_details", "Gets details of a given order", new
        {
            type = "object",
            properties = new
            {
                id = new
                {
                    type = "string",
                    description = "ID of the order"
                }
            },
            required = new List<string> { "id" }
        }))

agent.AddTornadoTool(checkBank);
agent.AddTornadoTool(getOrder);

Tool Parameters ​

Supported Types ​

  • Primitive types: string, int, double, bool, DateTime
  • Collections: T[]
  • Complex types: Custom classes/structs
  • Enums: Strongly-typed enumerations

Tool Permissions ​

Control which tools require user permission:

csharp
Dictionary<string, bool> permissions = new Dictionary<string, bool>
{
    ["dangerous_operation"] = true,  // Requires permission
    ["safe_operation"] = false       // No permission needed
};

TornadoAgent agent = new TornadoAgent(
    api, model,
    tools: toolList,
    toolPermissionRequired: permissions
);

Best Practices ​

Tool Design ​

  • Keep tools focused on single responsibilities
  • Use descriptive names and parameters
  • Return meaningful, actionable results
  • Handle errors gracefully

Error Handling ​

csharp
string SafeTool(string input)
{
    try
    {
        // Tool logic
        return "Success";
    }
    catch (Exception ex)
    {
        return $"Error: {ex.Message}";
    }
}

Documentation ​

csharp
/// <summary>
/// Retrieves weather information for a specified city.
/// </summary>
/// <param name="city">The name of the city</param>
/// <param name="units">Temperature units (celsius/fahrenheit)</param>
/// <returns>Weather information as a formatted string</returns>
string GetWeather(string city, string units = "celsius")
{
    // Implementation
}

Common Issues ​

Tool Not Being Called ​

Solutions:

  • Ensure model supports function calling
  • Check tool description is clear
  • Verify instructions mention tool availability

Argument Type Mismatch ​

Solutions:

  • Use correct C# types
  • Implement ToolArguments for flexibility
  • Add validation in tool implementation