# `OzMcp.Structs.Tool`
[🔗](https://github.com/oz-elixir/oz_mcp/blob/v0.9.0/lib/oz_mcp/structs/tool.ex#L1)

Helper module used to build `Tool` structure.

_(MCP protocol: 2025-11-25)_

## Short example:

```elixir
%Tool{}
  |> Tool.name("get_date")
  |> Tool.title("Get the current date (new)")
  |> Tool.description("Get the current date formatted as %d/%m/%Y")
  |> Tool.build()
```

Result:

```elixir
%{
  name: "get_date",
  description: "Get the current date formatted as %d/%m/%Y",
  title: "Get the current date (new)",
  inputSchema: %{type: "object", properties: %{}}
}
```

## Long example:

```elixir
%Tool{}
  |> Tool.name("get_date")
  |> Tool.title("Get the current date")
  |> Tool.description("Get the current date formatted as %d/%m/%Y")
  |> Tool.execution(
    %ToolExecution{}
    |> ToolExecution.task_support(:forbidden)
  )
  |> Tool.icons([
    %Icon{}
    |> Icon.src("https://img.com/icon.png")
    |> Icon.mime_type("image/png")
    |> Icon.sizes(["16x16"])
  ])
  |> Tool._meta(%{
    id: "472",
    md5: "154173f63ed5380419b649e66173e148"
  })
  |> Tool.build()
```

Result:

```elixir
%{
  name: "get_date",
  description: "Get the current date formatted as %d/%m/%Y",
  title: "Get the current date",
  execution: %{taskSupport: :forbidden},
  icons: [
    %{
      src: "https://img.com/icon.png",
      sizes: ["16x16"],
      mimeType: "image/png"
    }
  ],
  _meta: %{id: "472", md5: "154173f63ed5380419b649e66173e148"},
  inputSchema: %{type: "object", properties: %{}}
}
```

The `required_scopes` field holds the scopes that a principal must hold to
use the tool. OzMcp uses them for the check of `tools/call` and for the
filter of `tools/list`. They are never sent to the client.

Specification: [Tool](https://modelcontextprotocol.io/specification/2025-11-25/schema#tool)

## Fields

| Field | Setter | Type | Required |
|---|---|---|---|
| `name` | `name/2` | string | yes |
| `title` | `title/2` | string | no |
| `description` | `description/2` | string | no |
| `inputSchema` | `input_schema/2` | map | yes |
| `outputSchema` | `output_schema/2` | map | no |
| `_meta` | `_meta/2` | map | no |
| `icons` | `icons/2` | list of `t:OzMcp.Structs.Icon.t/0` | no |
| `execution` | `execution/2` | `t:OzMcp.Structs.ToolExecution.t/0` | no |
| `annotations` | `annotations/2` | `t:OzMcp.Structs.ToolAnnotations.t/0` | no |
| `required_scopes` | `required_scopes/2` | list of scopes, never sent | no |
| `extras` | `extras/2` | map | no |

# `t`

```elixir
@type t() :: %OzMcp.Structs.Tool{
  _meta: map() | nil,
  annotations: OzMcp.Structs.ToolAnnotations.t() | nil,
  description: String.t() | nil,
  execution: OzMcp.Structs.ToolExecution.t() | nil,
  extras: map() | nil,
  icons: [OzMcp.Structs.Icon.t()] | nil,
  inputSchema: map(),
  name: String.t(),
  outputSchema: map() | nil,
  required_scopes: [String.t()],
  title: String.t() | nil
}
```

# `annotations`

```elixir
@spec annotations(t(), OzMcp.Structs.ToolAnnotations.t() | nil) :: t()
```

# `build`

```elixir
@spec build(t()) :: map()
```

# `description`

```elixir
@spec description(t(), String.t() | nil) :: t()
```

# `execution`

```elixir
@spec execution(t(), OzMcp.Structs.ToolExecution.t() | nil) :: t()
```

# `extras`

```elixir
@spec extras(t(), map() | nil) :: t()
```

# `icons`

```elixir
@spec icons(t(), [OzMcp.Structs.Icon.t()] | nil) :: t()
```

# `input_schema`

```elixir
@spec input_schema(t(), map()) :: t()
```

# `name`

```elixir
@spec name(t(), String.t()) :: t()
```

# `output_schema`

```elixir
@spec output_schema(t(), map() | nil) :: t()
```

# `required_scopes`

```elixir
@spec required_scopes(t(), [String.t()]) :: t()
```

# `title`

```elixir
@spec title(t(), String.t() | nil) :: t()
```

---

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