@type execute_fn() :: (agent_id :: String.t(), id :: String.t(), args :: map() ->
                   {:ok, String.t()}
                   | {:ok, String.t(), %{ui: ui_content()}}
                   | {:error, String.t()})

The function invoked when the LLM requests this tool.

Receives the calling agent_id, the tool call id (an opaque string from the provider, used to correlate results), and args (the JSON-decoded arguments map).

Returns one of:

• {:ok, result} — the common case. result is placed directly into the model's context as tool result text.
• {:ok, result, %{ui: ui_content()}} — same, plus a UI side effect invisible to the model. The third element is a map, not a keyword list. The %{ui: ...} wrapper is stripped before the text reaches the LLM — see Planck.Agent's tool-result handling.
• {:error, reason} — reason is placed into the model's context the same way result would be.

All text values must be strings. Exceptions and exit signals are caught by the agent and converted to error strings automatically.

@type t() :: %Planck.Agent.Tool{
  description: String.t(),
  execute_fn: execute_fn(),
  name: String.t(),
  parameters: map(),
  widget: module() | nil
}

A fully-specified tool: schema fields understood by the LLM plus the execute_fn that runs when the model calls it.

• :name — identifier the model uses to call the tool; must be unique within an agent's tool set
• :description — natural-language description sent to the model; quality here directly affects how reliably the model uses the tool
• :parameters — JSON Schema object describing the accepted arguments
• :execute_fn — the function called with the agent id, tool call id, and decoded args
• :widget — optional module implementing Planck.Agent.Widget, pairing this tool with a UI widget. nil for most tools. See Planck.Agent.Sidecar.list_widgets/0, which derives the sidecar's widget list from tools that set this field.

@type ui_content() ::
  %{kind: :text, text: String.t()}
  | %{kind: :widget, label: String.t(), widget: String.t(), data: term()}

A UI side effect attached to a tool result — see execute_fn's 3-element return form. Deliberately not just "the widget to open": what shows up in the chat transcript to represent this side effect is a different thing from what the widget itself contains (Planck.Agent.Widget.render/1), and not every UI side effect involves a widget at all.

• %{kind: :text, text: text} — a UI-only note shown in the chat, invisible to the LLM, no widget involved.
• %{kind: :widget, label: label, widget: widget_id, data: data} — a button in the chat labeled label (sidecar-authored and human-readable — the tool decides what invites the click; the widget decides what's inside once opened). widget_id names a Planck.Agent.Widget (its id/0, paired via a Planck.Agent.Tool's :widget field). data is an opaque initial snapshot for that widget's first paint, avoiding a round-trip through render/1 to open it — optional, may be nil.