ClaudeAgentSDK.Tool (claude_agent_sdk v0.6.9)

Tool definition macro for creating in-process MCP tools.

Provides the deftool macro for defining tools that can be used with create_sdk_mcp_server/2 to create SDK-based MCP servers without subprocess overhead.

Usage

defmodule MyTools do
  use ClaudeAgentSDK.Tool

  deftool :calculator,
          "Performs basic calculations",
          %{
            type: "object",
            properties: %{
              expression: %{type: "string"}
            },
            required: ["expression"]
          } do
    def execute(%{"expression" => expr}) do
      result = eval_expression(expr)
      {:ok, %{"content" => [%{"type" => "text", "text" => "Result: #{result}"}]}}
    end

    defp eval_expression(expr) do
      # Implementation
    end
  end
end

Tool Metadata

Each tool defined with deftool creates a module with:

__tool_metadata__/0 - Returns tool metadata
execute/1 - Executes the tool with given input

Input/Output Format

Tools receive input as a map matching the input_schema and return:

{:ok, result} - Success with result map
{:error, reason} - Error with reason string

Result map should contain:

"content" - List of content blocks (text, image, etc.)
Optional: "isError" - Boolean indicating error state

Summary

Functions

__before_compile__(env)

Collects all defined tools and makes them discoverable.

__using__(opts)

When used, defines the deftool macro in the calling module.

deftool(name, description, list)

Shorthand for deftool with minimal schema (just type: object).

deftool(name, description, input_schema, list)

Defines a tool with name, description, and input schema.

list_tools(module)

Lists all tools defined in a module.

valid_schema?(schema)

Validates a JSON schema map.

Functions

__before_compile__(env)

(macro)

Collects all defined tools and makes them discoverable.

using(opts)

(macro)

When used, defines the deftool macro in the calling module.

deftool(name, description, list)

(macro)

Shorthand for deftool with minimal schema (just type: object).

deftool(name, description, input_schema, list)

(macro)

Defines a tool with name, description, and input schema.

Parameters

name - Atom tool name (e.g., :calculator)
description - String description of what the tool does
input_schema - JSON Schema map defining expected input
do_block - Block containing execute/1 function definition

Examples

deftool :add, "Add two numbers", %{
  type: "object",
  properties: %{a: %{type: "number"}, b: %{type: "number"}},
  required: ["a", "b"]
} do
  def execute(%{"a" => a, "b" => b}) do
    {:ok, %{"content" => [%{"type" => "text", "text" => "Result: #{a + b}"}]}}
  end
end

list_tools(module)

@spec list_tools(module()) :: [map()]

Lists all tools defined in a module.

Parameters

module - The module that used ClaudeAgentSDK.Tool

Returns

List of tool metadata maps.

Examples

iex> ClaudeAgentSDK.Tool.list_tools(MyTools)
[%{name: :calculator, description: "Performs calculations", ...}]

valid_schema?(schema)

@spec valid_schema?(map()) :: boolean()

Validates a JSON schema map.

Parameters

schema - JSON Schema map

Returns

Boolean indicating if schema is valid.

Examples

iex> ClaudeAgentSDK.Tool.valid_schema?(%{type: "object"})
true

iex> ClaudeAgentSDK.Tool.valid_schema?(%{})
false