# `PhoenixKit.API.ControlFields`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v2.64.1/lib/phoenix_kit/api/control_fields.ex#L1)

The fields the executor adds to the input of a write tool: modules never declare them.
`idempotency_key` is left out for a write tool that cannot replay (see below).

  * `dry_run` (boolean) - run the handler without side effects and return the
    preview; never creates a code or an approval.
  * `confirm_token` (string) - the one-time code of a dangerous operation, sent
    with the same arguments as the preview call.
  * `idempotency_key` (string, 16 to 128 characters of `[A-Za-z0-9_-]`) - makes a
    retry safe. REST clients may send it as the `Idempotency-Key` header instead.

A read tool has none of them, so a request that sends one gets `422`, never a
silent ignore. A write tool that cannot replay (`:replay` of `PhoenixKit.API.Tool`
is `false`) has no `idempotency_key`; the `Idempotency-Key` header is ignored on it,
as on a read tool.

# `names`

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

The names of the control fields.

# `properties`

```elixir
@spec properties(PhoenixKit.API.Tool.t()) :: map()
```

The JSON Schema properties the executor adds to `tool`'s input (`%{}` for a read tool).

# `replay_tool?`

```elixir
@spec replay_tool?(PhoenixKit.API.Tool.t()) :: boolean()
```

Whether `tool` takes an `idempotency_key`: a write tool that has not given up replay
(`:replay` of `PhoenixKit.API.Tool`).

# `split`

```elixir
@spec split(map()) :: {map(), map()}
```

Splits a request body into the control fields and the tool's own input.

# `write_tool?`

```elixir
@spec write_tool?(PhoenixKit.API.Tool.t()) :: boolean()
```

Whether `tool` writes: its annotations do not say `read_only: true`. The only
definition of "write tool" in the flow.

---

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