# `MingaAgent.Tool.Spec`
[🔗](https://github.com/jsmestad/minga/blob/main/lib/minga_agent/tool/spec.ex#L1)

Specification for an agent tool.

Wraps the metadata needed to register, discover, and execute a tool in
the `MingaAgent.Tool.Registry`. Unlike `ReqLLM.Tool` (which is
provider-facing and tied to the LLM request lifecycle), `Spec` is the
internal, registry-facing representation that adds category, approval
level, and extensibility metadata.

## Fields

| Field              | Type               | Description                                    |
|--------------------|--------------------|------------------------------------------------|
| `name`             | `String.t()`       | Unique tool identifier (e.g., `"read_file"`)   |
| `description`      | `String.t()`       | Human-readable description for the LLM         |
| `parameter_schema` | `map()`            | JSON Schema for the tool's parameters          |
| `callback`         | `(map() -> term())` | Function that executes the tool                |
| `category`         | `atom()`           | Grouping: `:filesystem`, `:git`, `:lsp`, etc.  |
| `approval_level`   | `atom()`           | `:auto`, `:ask`, or `:deny`                    |
| `metadata`         | `map()`            | Extensible bag for future fields               |

# `approval_level`

```elixir
@type approval_level() :: :auto | :ask | :deny
```

Approval level for tool execution.

# `category`

```elixir
@type category() :: :filesystem | :git | :lsp | :shell | :memory | :agent | :custom
```

Tool category for grouping and filtering.

# `t`

```elixir
@type t() :: %MingaAgent.Tool.Spec{
  approval_level: approval_level(),
  callback: (map() -> term()),
  category: category(),
  description: String.t(),
  metadata: map(),
  name: String.t(),
  parameter_schema: map()
}
```

A tool specification.

# `new`

```elixir
@spec new(keyword()) :: {:ok, t()} | {:error, String.t()}
```

Creates a new tool spec from a keyword list.

Required keys: `:name`, `:description`, `:parameter_schema`, `:callback`.
Optional keys: `:category` (default `:custom`), `:approval_level`
(default `:auto`), `:metadata` (default `%{}`).

# `new!`

```elixir
@spec new!(keyword()) :: t()
```

Creates a new tool spec, raising on validation failure.

---

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