# `ToolCall.Coerce`

Runtime normalisation of decoded JSON arguments into the value domains that
typespecs promise.

Two mismatches motivate this module:

  * JSON Schema `integer` accepts `1.0`, while Elixir `integer()` does not.
    Integral floats are truncated.
  * JSON has no atoms, so `:enum` values arrive as strings and are mapped
    back to atoms.

JSON strings are Unicode; invalid UTF-8 binaries are rejected with
`{:invalid_utf8, value}` so a bad provider payload never raises out of
`ToolCall.run/3`.

Patterns must already be compiled into `ToolCall.IR.Type.pattern_regex`.
Hand-built types can be prepared with `ToolCall.Typespec.validate_type!/1`.

See `docs/number-handling.md`.

# `coerce`

```elixir
@spec coerce(ToolCall.IR.Type.t(), term(), ToolCall.IR.Param.wire()) ::
  {:ok, term()} | {:error, term()}
```

# `param`

```elixir
@spec param(ToolCall.IR.Param.t(), term()) :: {:ok, term()} | {:error, term()}
```

---

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