Tool Calling

Ensemble provides a unified tool calling interface across all providers.

Tool Definition

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"]
      }
    },
    "required": ["location"]
  }
}

ToolDefinition Type

type ToolDefinition struct {
    Name         string            // Function name
    Description  string            // When/how to use
    Parameters   ParameterSchema   // JSON Schema for arguments
    Strict       *bool             // Strict validation (where supported)
    CacheControl *CacheControlConfig // Cache hints (Anthropic)
}

ParameterSchema

Full JSON Schema support including:

• Object, array, string, number, integer, boolean types
• Nested objects and arrays
• Enum constraints
• Numeric min/max
• String pattern, minLength, maxLength
• Array minItems, maxItems

Tool Calls in Responses

Tool calls appear as EventBlock entries with type tool_call:

{
  "type": "tool_call",
  "tool_call": {
    "id": "call_abc123",
    "name": "get_weather",
    "arguments": {"location": "San Francisco", "unit": "celsius"},
    "raw_arguments": "{\"location\":\"San Francisco\",\"unit\":\"celsius\"}"
  }
}

Tool Results

Send tool results back as messages with role tool:

{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "{\"temperature\": 18, \"condition\": \"foggy\"}"
}

Server-Side Tools

Some providers support server-side tools (web search, code execution). These are configured in the provider's allowed_server_tools whitelist:

providers:
  anthropic:
    allowed_server_tools:
      - type: text_editor_20250728
        name: str_replace_based_edit_tool
      - type: web_search
        name: web_search

Advanced Tool Use (Anthropic)

Anthropic-specific advanced features:

type Tool struct {
    Name           string
    Description    string
    Parameters     ParameterSchema
    DeferLoading   *bool                    // Lazy tool definition loading
    AllowedCallers []string                 // Restrict which tools can call this
    InputExamples  []map[string]interface{} // Example inputs for the model
}