Tool Use in Go — Go Patterns

The Problem

LLMs can request tool calls by name — but the agent needs to route that name to the right Go function, validate arguments, and return a structured result. Hardcoding a switch on tool names couples the agent to every tool and makes adding new tools a surgery on the core loop.

The Solution

Define a Tool interface with Name(), Description(), and Execute(). A ToolRegistry holds a map[string]Tool and exposes a single Dispatch(call ToolCall) method. The agent remains unaware of concrete tool types — it just passes ToolCall structs from the LLM to the registry. New tools are registered at startup with no changes to the agent.

Structure

Tool Use Pattern

Step 1 of 4

LLM Selects a Tool

The LLM response contains a structured ToolCall with the tool name and JSON arguments. The agent deserializes this into a ToolCall struct and passes it to the registry — no branching required.

flowchart LR
LLM["LLM Response
(ToolCall JSON)"]
Agent["Agent"]
Registry["ToolRegistry
Dispatch()"]
Web["WebSearchTool"]
Calc["CalculatorTool"]
Result["ToolResult"]

LLM -->|"ToolCall{name, args}"| Agent
Agent --> Registry
Registry -->|"name=web_search"| Web
Registry -->|"name=calculator"| Calc
Web --> Result
Calc --> Result
Result --> Agent

Implementation

gofmt ✓

package main

import "context"

// Tool is a named, self-describing capability the agent can invoke.
type Tool interface {
	Name() string
	Description() string
	Execute(ctx context.Context, args map[string]any) (string, error)
}

// ToolCall is the LLM-selected invocation received from the model.
type ToolCall struct {
	Name string
	Args map[string]any
}

// ToolResult pairs a call with its output.
type ToolResult struct {
	Call   ToolCall
	Output string
	Err    error
}

package main

import (
	"context"
	"fmt"
	"strconv"
)

// ToolRegistry maps tool names to their implementations.
type ToolRegistry struct {
	tools map[string]Tool
}

func NewToolRegistry(tools ...Tool) *ToolRegistry {
	m := make(map[string]Tool, len(tools))
	for _, t := range tools {
		m[t.Name()] = t
	}
	return &ToolRegistry{tools: m}
}

// Dispatch executes the tool named in the call and returns its result.
func (r *ToolRegistry) Dispatch(ctx context.Context, call ToolCall) ToolResult {
	tool, ok := r.tools[call.Name]
	if !ok {
		return ToolResult{Call: call, Err: fmt.Errorf("unknown tool %q", call.Name)}
	}
	out, err := tool.Execute(ctx, call.Args)
	return ToolResult{Call: call, Output: out, Err: err}
}

// Schemas returns a JSON-serialisable description of all registered tools.
func (r *ToolRegistry) Schemas() []map[string]string {
	schemas := make([]map[string]string, 0, len(r.tools))
	for _, t := range r.tools {
		schemas = append(schemas, map[string]string{
			"name":        t.Name(),
			"description": t.Description(),
		})
	}
	return schemas
}

// WebSearchTool simulates a web search capability.
type WebSearchTool struct{}

func (w *WebSearchTool) Name() string        { return "web_search" }
func (w *WebSearchTool) Description() string { return "Search the web for up-to-date information." }
func (w *WebSearchTool) Execute(_ context.Context, args map[string]any) (string, error) {
	query, _ := args["query"].(string)
	return fmt.Sprintf("search results for %q: [stub result]", query), nil
}

// CalculatorTool evaluates simple arithmetic expressions.
type CalculatorTool struct{}

func (c *CalculatorTool) Name() string        { return "calculator" }
func (c *CalculatorTool) Description() string { return "Evaluate a mathematical expression." }
func (c *CalculatorTool) Execute(_ context.Context, args map[string]any) (string, error) {
	expr, _ := args["expression"].(string)
	// Real implementation would parse and evaluate the expression.
	_ = expr
	return strconv.FormatFloat(42.0, 'f', -1, 64), nil
}

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log"
)

func main() {
	registry := NewToolRegistry(&WebSearchTool{}, &CalculatorTool{})

	// Simulate receiving a tool call from the LLM as JSON.
	rawCall := `{"name":"web_search","args":{"query":"Go concurrency patterns"}}`

	var payload struct {
		Name string         `json:"name"`
		Args map[string]any `json:"args"`
	}
	if err := json.Unmarshal([]byte(rawCall), &payload); err != nil {
		log.Fatalf("unmarshal: %v", err)
	}

	call := ToolCall{Name: payload.Name, Args: payload.Args}
	result := registry.Dispatch(context.Background(), call)
	if result.Err != nil {
		log.Fatalf("tool error: %v", result.Err)
	}

	fmt.Printf("Tool: %s\nResult: %s\n", result.Call.Name, result.Output)
	// Output:
	// Tool: web_search
	// Result: search results for "Go concurrency patterns": [stub result]
}

Real-World Analogy

A company switchboard: callers ask for a department by name, and the operator routes them. The caller doesn’t know the internal extension; the switchboard does. Adding a new department means registering a new extension — the operator’s routing logic stays unchanged.

Pros and Cons

| Pros | Cons | |------|------| | Open/closed — add tools without touching the agent | map[string]any args lose type safety at the boundary | | Registry serves as a schema catalog for the LLM prompt | Requires careful description writing so the LLM selects the right tool | | Tools are independently testable units | Dispatch errors are silent if not surfaced back to the LLM | | Schemas can be serialized to JSON for the LLM’s function-calling API | Large tool registries can overwhelm the model’s context window |

Best Practices

Keep tool Description() precise and action-oriented — the LLM uses it verbatim to decide when to call the tool.
Validate required args inside Execute() and return descriptive errors so the agent can reason about what went wrong.
Expose Schemas() from the registry to auto-generate the function-calling spec for your LLM provider.
Use strongly-typed wrapper structs internally and unmarshal from map[string]any at the tool boundary only.
Group related tools under a common prefix (e.g., fs_read, fs_write) to help the LLM reason about tool families.

When to Use

Any agent that calls external APIs, executes code, reads files, or queries databases.
When you want to add or remove capabilities at runtime without redeploying the agent logic.
Multi-tenant systems where different tenants have different tool sets.

When NOT to Use

Agents with a single, fixed action — the registry adds unnecessary indirection.
Deterministic pipelines where tools are always called in a fixed order — use a plain function call.

Tool Use