# `ClaudeAgentSDK.Tool`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/tool.ex#L1)

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: `"is_error"` - Boolean indicating error state

# `__before_compile__`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/tool.ex#L66)
*macro* 

Collects all defined tools and makes them discoverable.

# `__using__`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/tool.ex#L53)
*macro* 

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

# `deftool`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/tool.ex#L148)
*macro* 

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

# `deftool`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/tool.ex#L98)
*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`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/tool.ex#L171)

```elixir
@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", ...}]

# `simple_schema`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/tool.ex#L278)

```elixir
@spec simple_schema(keyword() | [atom()] | map()) :: map()
```

Creates a simple JSON Schema for common tool patterns.

This helper reduces boilerplate when defining tools with straightforward
input requirements. It supports several input formats for flexibility.

## Input Formats

### List of atoms (all string, all required)

    simple_schema([:name, :path])
    # => %{type: "object", properties: %{name: %{type: "string"}, path: %{type: "string"}}, required: ["name", "path"]}

### Keyword list with types

    simple_schema(name: :string, count: :number, enabled: :boolean)
    # => %{type: "object", properties: %{...}, required: ["name", "count", "enabled"]}

### Keyword list with descriptions

    simple_schema(name: {:string, "User's full name"}, age: {:number, "Age in years"})
    # => Adds description field to each property

### Optional fields

    simple_schema(name: :string, email: {:string, optional: true})
    # => "name" is required, "email" is not

### Map syntax (Python parity)

    simple_schema(%{a: :float, b: :float})
    # => %{"type" => "object", "properties" => %{"a" => %{"type" => "number"}, ...}, "required" => ["a", "b"]}

    simple_schema(%{"name" => String, "age" => Integer})
    # => Supports module types (String, Integer, Float) for Python parity

## Supported Types

- `:string` or `String` - String type
- `:number` or `:float` or `Float` - Number type (float or int)
- `:integer` or `Integer` - Integer type
- `:boolean` - Boolean type
- `:array` - Array type
- `:object` - Object type

## Examples

    # Simple tool with two required string fields
    deftool :create_file, "Create a file", Tool.simple_schema([:path, :content]) do
      def execute(%{"path" => path, "content" => content}) do
        File.write!(path, content)
        {:ok, %{"content" => [%{"type" => "text", "text" => "Created #{path}"}]}}
      end
    end

    # Tool with mixed types
    deftool :search, "Search files",
      Tool.simple_schema(query: :string, max_results: {:integer, optional: true}) do
      def execute(%{"query" => query} = args) do
        max = Map.get(args, "max_results", 10)
        # ... search logic
      end
    end

    # Python-style map syntax
    deftool :add, "Add two numbers", Tool.simple_schema(%{a: :float, b: :float}) do
      def execute(%{"a" => a, "b" => b}) do
        {:ok, %{"content" => [%{"type" => "text", "text" => "Result: #{a + b}"}]}}
      end
    end

# `valid_schema?`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/tool.ex#L199)

```elixir
@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

---

*Consult [api-reference.md](api-reference.md) for complete listing*