Manual Tool Use & Function Calling

Relevant source files

The following files were used as context for generating this wiki page:

• examples/tools/main.go
• examples/tools-streaming/main.go
• examples/tools-streaming-jsonschema/main.go
• schemautil.go
• tools.md
• message_test.go

Manual Tool Use and Function Calling in the Anthropic Go SDK allows developers to provide Claude with external capabilities by defining executable functions and their schemas. Unlike automated runners, the manual approach gives the developer full control over the conversation loop, including message accumulation, tool execution logic, and how results are sent back to the model.

This system relies on defining tools using JSON schemas, handling model-generated tool_use content blocks, executing local code based on those blocks, and returning tool_result blocks to continue the dialogue.

Core Architecture and Data Flow

The manual tool use flow is a cyclical process where the developer manages the transition between the Assistant's reasoning and the execution of local functions.

The diagram shows the manual feedback loop where tool calls are intercepted by the application, processed, and the results are fed back into the next API request.
Sources: examples/tools/main.go:49-143, examples/tools-streaming/main.go:50-143

Key Data Structures

Manual tool use relies on several key parameters and types defined within the anthropic package.

Component	Description
ToolParam	Defines a tool's name, description, and input schema.
ToolInputSchemaParam	Represents the JSON schema for tool inputs.
ToolUseBlock	A block in the model's response indicating a tool should be executed.
ToolResultBlock	A block sent by the user containing the output of a tool execution.
MessageParam	The structure used to maintain conversational history, including tool results.

Sources: examples/tools/main.go:21-72, message_test.go:484-493

Defining Tools and Schemas

To enable tool use, tools must be defined with an JSON schema that describes the expected input for each function. The SDK provides utility functions to transform standard JSON schemas into the specific format required by the Anthropic API.

Schema Transformation

The schemautil.go file provides logic to ensure schemas conform to Anthropic's expectations, such as:

• Forcing objects to have additionalProperties: false.
• Filtering string formats to only supported types (e.g., date-time, uuid, ipv4).
• Managing nested $defs and $ref objects.
• Appending unsupported properties to the description for model awareness.

Sources: schemautil.go:76-200, examples/structured-outputs/main.go:44-59

JSON Schema Integration

Developers can generate schemas manually using ToolInputSchemaParam or automatically via reflection from Go structs.

type GetCoordinatesInput struct {
    Location string `json:"location" jsonschema_description:"The location to look up."`
}

// Generate schema via reflection or manual definition
toolParam := anthropic.ToolParam{
    Name:        "get_coordinates",
    Description: anthropic.String("Accepts a place as an address, then returns coordinates."),
    InputSchema: anthropic.ToolInputSchemaParam{
        Properties: map[string]any{
            "location": map[string]any{
                "type":        "string",
                "description": "The location to look up.",
            },
        },
    },
}

Sources: examples/tools/main.go:21-34, examples/tools-streaming-jsonschema/main.go:137-154

Manual Execution Loop

The manual loop involves iterating until the model no longer produces tool_use blocks.

Step 1: Sending Initial Request

The process starts by including the defined tools in the Tools field of MessageNewParams.

Step 2: Processing Content Blocks

When the model responds, the application must iterate through message.Content and identify ToolUseBlock types. Each block contains an ID, Name, and Input.

Step 3: Executing Logic and Accumulating Results

The application parses the Input (often using json.Unmarshal), executes the corresponding Go function, and stores the result in a ToolResultBlock.

Streaming Tool Use

Manual tool use also supports streaming, where events are emitted as the model generates the tool call.

• Content Block Start: Emits the tool Name and type.
• Content Block Delta: Emits the PartialJSON for the tool's input as it is generated.
• Message Accumulation: The SDK's Accumulate method is used to reconstruct the full message from streaming events so it can be used for tool execution.

message := anthropic.Message{}
for stream.Next() {
    event := stream.Current()
    err := message.Accumulate(event) // Builds the full ToolUseBlock
    // Process display events...
}

Sources: examples/tools-streaming/main.go:73-100, message_test.go:509-543

Advanced Tool Configuration

The SDK supports several advanced options for tool behavior within the manual flow:

1. Tool Choice: Control whether the model must use a specific tool, any tool, or decide on its own using ToolChoiceUnionParam.
2. Strict Mode: Enforce strict adherence to schemas by setting Strict: anthropic.Bool(true) in the tool definition.
3. Cache Control: Support for ephemeral caching of tool definitions and conversational context to optimize token usage.

Sources: message_test.go:88-124, tools.md:144-154

Summary of Manual Implementation

Manual implementation is necessary when developers require custom logic for tool parallelization, specific error handling for external APIs, or complex UI updates between model turns. By managing the loop manually, applications can provide specific feedback to the model (via the is_error flag in tool results) when local execution fails.

Sources: examples/tools/main.go:138, tools.md:156-168