Tools

Tools let agents take action: query a database, call an API, evaluate arithmetic, search the web.

How tools work

LogicGrid handles the loop:

1. The agent's system prompt describes each tool to the LLM (or sends them via the provider's native tool API — see Tool calling strategy).
2. The LLM responds either with a normal answer or with a structured tool call (name + JSON args).
3. LogicGrid invokes the tool, feeds the result back to the LLM as a tool message, and the LLM continues generating.
4. The loop repeats until the LLM emits a non-tool response — that's the final answer.

Tools live in the agent's constructor:

using LogicGrid.Core.Tools;
using LogicGrid.Tools.Tools;

IAgent math = new Agent<string>(
    name: "Mathlete",
    description: "Solves arithmetic.",
    systemPrompt: "Use the calculator tool when the user asks for a number.",
    llm: llm,
    tools: new ToolBase[] { new CalculatorTool() });

Authoring a tool

Inherit from ToolBase<TArgs> for typed arguments — LogicGrid generates the JSON schema for the LLM and deserializes args for you.

using System.ComponentModel;
using LogicGrid.Core.Tools;

public sealed class WeatherArgs
{
    [Description("City name, e.g. 'Tokyo'")]
    public string City { get; set; } = "";
}

public sealed class WeatherTool : ToolBase<WeatherArgs>
{
    public override string Name => "get_weather";
    public override string Description =>
        "Get the current temperature in a city. " +
        "Use when the user asks about weather.";

    public override Task<string> ExecuteAsync(
        WeatherArgs args, CancellationToken ct = default)
    {
        // call your weather API here
        return Task.FromResult($"It's 12°C and cloudy in {args.City}.");
    }
}

The full authoring story (typed vs untyped, schema generation, side-effect tools) lives at Custom tools (typed) and Custom tools (untyped).

Built-in tools

LogicGrid has five tools in LogicGrid.Tools:

Tool	What it does
CalculatorTool	Evaluates arithmetic expressions safely.
DateTimeTool	Returns the current date/time in any timezone.
HttpGetTool	Fetches a URL and returns the response body (HTML stripped).
JsonExtractTool	Extracts a value from a JSON document via dot-notation path.
WebSearchTool	Web search via Brave, Tavily, or SerpAPI. Bring your own API key.

Per-tool reference with args classes and config: Built-in tools.

MCP tools

Any Model Context Protocol server's tools can be wrapped as LogicGrid tools using LogicGrid.Mcp. File system access, database queries, GitHub, Slack — anything you can do from Claude Desktop or a VS Code MCP integration also works inside a LogicGrid agent.

using LogicGrid.Core.Tools;            // ToolBase
using LogicGrid.Mcp;                   // McpHttpClient, McpToolAdapter

using var client = new McpHttpClient("https://your-mcp-server.example.com");
await client.ConnectAsync();
IList<ToolBase> tools = await McpToolAdapter.GetAllAsync(client);

IAgent agent = new Agent<string>(
    name:         "FileBot",
    description:  "Reads and writes files via MCP.",
    systemPrompt: "Use tools to access files.",
    llm:          llm,
    tools:        tools);

McpToolAdapter.GetAllAsync is a static helper in LogicGrid.Mcp that asks the connected MCP client for its tool list and wraps each one as a LogicGrid ToolBase.

See MCP overview.

Tool errors

If a tool throws, the exception message is fed back to the LLM as the tool result. The LLM usually recovers gracefully (tries different arguments, falls back, or apologises to the user). Don't catch exceptions inside the tool unless you want to format the error message yourself.

The framework also fires ToolCallFailedEvent on every exception so you can see them in the trace and logs — and subscribe a handler to react: forward to your error tracker, retry against a fallback tool, raise an alert, etc. See Events for the full handler API.