anthropic/tool

Tool definition types for the Anthropic Messages API

This module defines types for tool definitions following the Anthropic schema. Tools allow Claude to call external functions and receive results.

Example

import anthropic/types/tool.{tool_name, Tool, InputSchema}
import gleam/option.{None, Some}

let assert Ok(name) = tool_name("get_weather")
let weather_tool = Tool(
  name: name,
  description: Some("Get the current weather for a location"),
  input_schema: InputSchema(
    schema_type: "object",
    properties: Some([
      #("location", PropertySchema(
        property_type: "string",
        description: Some("City and state, e.g. 'San Francisco, CA'"),
        enum_values: None,
      )),
    ]),
    required: Some(["location"]),
  ),
)

Types

InputSchema

</>

Schema defining the input parameters for a tool

pub type InputSchema {
  InputSchema(
    schema_type: String,
    properties: option.Option(List(#(String, PropertySchema))),
    required: option.Option(List(String)),
  )
}

Constructors

InputSchema(
  schema_type: String,
  properties: option.Option(List(#(String, PropertySchema))),
  required: option.Option(List(String)),
)

Arguments

schema_type: Always “object” for Anthropic tools
properties: Property definitions for the input object
required: List of required property names

PropertySchema

</>

Schema for a single property in a tool’s input

pub type PropertySchema {
  PropertySchema(
    property_type: String,
    description: option.Option(String),
    enum_values: option.Option(List(String)),
    items: option.Option(PropertySchema),
    properties: option.Option(List(#(String, PropertySchema))),
    required: option.Option(List(String)),
  )
}

Constructors

```
PropertySchema(
  property_type: String,
  description: option.Option(String),
  enum_values: option.Option(List(String)),
  items: option.Option(PropertySchema),
  properties: option.Option(List(#(String, PropertySchema))),
  required: option.Option(List(String)),
)
```
Arguments

property_type

The JSON type of the property (e.g., “string”, “number”, “boolean”, “array”, “object”)

description

Human-readable description of the property

enum_values

If this is an enum, the allowed values

items

For array types, the schema of items

properties

For object types, nested properties

required

For object types, which nested properties are required

Tool

</>

A tool definition that can be provided to Claude

pub type Tool {
  Tool(
    name: ToolName,
    description: option.Option(String),
    input_schema: InputSchema,
  )
}

Constructors

```
Tool(
  name: ToolName,
  description: option.Option(String),
  input_schema: InputSchema,
)
```
Arguments

name

The validated name of the tool

description

Human-readable description of what the tool does

input_schema

JSON Schema defining the tool’s input parameters

ToolCall

</>

Represents a tool call extracted from a response

pub type ToolCall {
  ToolCall(id: String, name: String, input: String)
}

Constructors

```
ToolCall(id: String, name: String, input: String)
```
Arguments

id

Unique identifier for this tool call

name

Name of the tool being called

input

JSON string of input arguments

ToolChoice

</>

Specifies how Claude should choose which tool to use

pub type ToolChoice {
  Auto
  Any
  SpecificTool(name: String)
  NoTool
}

Constructors

```
Auto
```
Claude decides whether to use a tool and which one
```
Any
```
Claude must use one of the provided tools
```
SpecificTool(name: String)
```
Claude must use the specified tool (by name)
```
NoTool
```
Claude should not use any tools (respond directly)

ToolName

opaque </>

A validated tool name that conforms to Anthropic’s requirements.

Tool names must match the regex pattern ^[a-zA-Z0-9_-]{1,64}$:

Only alphanumeric characters, underscores, and hyphens
Between 1 and 64 characters in length

Use tool_name() to create a validated ToolName, or tool_name_unchecked() for cases where you trust the input (e.g., constants or API responses).

pub opaque type ToolName

ToolNameError

</>

Error when creating a ToolName

pub type ToolNameError {
  EmptyToolName
  InvalidToolNameCharacters(name: String)
  ToolNameTooLong(name: String, length: Int)
}

Constructors

```
EmptyToolName
```
Tool name is empty
```
InvalidToolNameCharacters(name: String)
```
Tool name contains invalid characters (must match ^[a-zA-Z0-9_-]+$)
```
ToolNameTooLong(name: String, length: Int)
```
Tool name exceeds maximum length of 64 characters

ToolResult

</>

Represents the result of executing a tool

pub type ToolResult {
  ToolSuccess(tool_use_id: String, content: String)
  ToolFailure(tool_use_id: String, error: String)
}

Constructors

```
ToolSuccess(tool_use_id: String, content: String)
```
Successful tool execution

Arguments

tool_use_id

ID of the tool call this responds to

content

The result content
```
ToolFailure(tool_use_id: String, error: String)
```
Failed tool execution

Arguments

tool_use_id

ID of the tool call this responds to

error

Error message

Values

array_property

</>

pub fn array_property(
  description: option.Option(String),
  item_schema: PropertySchema,
) -> PropertySchema

Create an array property schema

empty_input_schema

</>

pub fn empty_input_schema() -> InputSchema

Create an empty input schema (for tools with no parameters)

enum_property

</>

pub fn enum_property(
  description: option.Option(String),
  values: List(String),
) -> PropertySchema

Create an enum property schema

input_schema

</>

pub fn input_schema(
  properties: List(#(String, PropertySchema)),
  required: List(String),
) -> InputSchema

Create an input schema with properties

input_schema_to_json

</>

pub fn input_schema_to_json(schema: InputSchema) -> json.Json

Encode an InputSchema to JSON

is_tool_success

</>

pub fn is_tool_success(result: ToolResult) -> Bool

Check if a tool result is successful

object_property

</>

pub fn object_property(
  description: option.Option(String),
  properties: List(#(String, PropertySchema)),
  required: List(String),
) -> PropertySchema

Create an object property schema with nested properties

property

</>

pub fn property(property_type: String) -> PropertySchema

Create a simple property schema with just a type

property_schema_to_json

</>

pub fn property_schema_to_json(
  schema: PropertySchema,
) -> json.Json

Encode a PropertySchema to JSON

property_with_description

</>

pub fn property_with_description(
  property_type: String,
  description: String,
) -> PropertySchema

Create a property schema with type and description

tool_choice_to_json

</>

pub fn tool_choice_to_json(choice: ToolChoice) -> json.Json

Encode a ToolChoice to JSON

tool_name

</>

pub fn tool_name(raw: String) -> Result(ToolName, ToolNameError)

Create a validated tool name.

Returns Ok(ToolName) if the name matches Anthropic’s requirements:

Non-empty
Only alphanumeric characters, underscores, and hyphens
Maximum 64 characters

Examples

tool_name("get_weather")  // Ok(ToolName)
tool_name("my-tool-123")  // Ok(ToolName)
tool_name("")             // Error(EmptyToolName)
tool_name("has spaces")   // Error(InvalidToolNameCharacters(...))

tool_name_error_to_string

</>

pub fn tool_name_error_to_string(error: ToolNameError) -> String

Convert a ToolNameError to a human-readable string.

tool_name_to_string

</>

pub fn tool_name_to_string(name: ToolName) -> String

Get the raw string value from a ToolName.

Use this when you need to serialize the name to JSON or display it.

tool_name_unchecked

</>

pub fn tool_name_unchecked(raw: String) -> ToolName

Create a ToolName without validation.

Use this only when you trust the input, such as:

Compile-time constants
Values received from the Anthropic API
Values already validated elsewhere

For user input or untrusted sources, use tool_name() instead.

tool_result_id

</>

pub fn tool_result_id(result: ToolResult) -> String

Get the tool_use_id from a ToolResult

tool_to_json

</>

pub fn tool_to_json(t: Tool) -> json.Json

Encode a Tool to JSON

tool_to_json_string

</>

pub fn tool_to_json_string(t: Tool) -> String

Convert a tool to a JSON string

tools_to_json

</>

pub fn tools_to_json(tools: List(Tool)) -> json.Json

Encode a list of tools to JSON