Tool use: the model asks, your app acts

The model never runs anything. It asks for a tool call, your code validates and runs it, and returns the result.

The idea

Tool use lets a model work with the real world without ever touching it. You describe the tools (name, purpose, input shape). When the model decides one is needed, it replies with a tool_use block and stops with the reason tool_use. Your app checks the request, runs the real function, and sends the output back as a tool_result. Then the model continues and writes the final answer. The model proposes; your code disposes.

Code

public record ToolDef(string Name, string Description);

public static class OrderBot
{
    private static readonly ToolDef[] Tools = { new("get_order_status", "Look up an order by its id") };

    public static async Task<string> AnswerAsync(IMessagesClient client, string question)
    {
        var messages = new List<Message> { Message.User(question) };
        while (true)
        {
            var reply = await client.SendAsync(messages, Tools);
            messages.Add(reply.AsMessage());
            if (reply.StopReason != "tool_use") return reply.Text;

            foreach (var use in reply.ToolUses)
            {
                string result;
                if (!IsValid(use)) result = "error: invalid input";
                else result = await RunToolAsync(use.Name, use.Input);
                messages.Add(Message.ToolResult(use.Id, result));
            }
        }
    }
}

Tips

• Interview line: "The model does not execute tools. It outputs a structured request, and my code decides whether and how to run it."
• Always validate the tool name and input in code, and check the user is allowed to do that action. The model’s request is untrusted input.
• A tool_result is sent back in a user message and is linked to the request by the tool_use id.
• Good tool names and descriptions matter: the model chooses a tool by reading them.

In the .NET library

Represent each tool as a normal C# method plus a JSON schema for its input. Use System.Text.Json to deserialize use.Input into a typed record, which doubles as validation. Return clear error strings so the model can recover or explain.