@spec args_json(t()) :: String.t()

Extract the arguments JSON string from a ToolCall.

@spec args_map(
  t(),
  keyword()
) :: map() | nil

Extract and decode the arguments as a map from a ToolCall. Returns nil if decoding fails.

@spec builtin?(t() | map()) :: boolean()

Returns true when the ToolCall (or tool-call-shaped map) represents a server-side builtin invocation. Handles both OpenAI-shaped wrappers and bare maps: unwraps a nested :function map when present.

Prefer this over flagged_builtin?/1 whenever you have a %ToolCall{} or a map that may carry the OpenAI function: nesting.

@spec execute(t(), [ReqLLM.Tool.t()], keyword()) ::
  {:ok, term()} | {:error, term() | resolution()}

Executes one resolved application tool call.

The callback is invoked only when resolve/3 returns :valid. Invalid, unknown, provider-executed, and provider-native calls return {:error, resolution} without invoking any callback. Successful and failed callback values retain the existing ReqLLM.Tool.execute/2 contract.

@spec find_args([t()], String.t(), keyword()) :: map() | nil

Find the first tool call matching the given name and return its decoded arguments. Returns nil if no match found or if arguments cannot be decoded.

@spec flagged_builtin?(any()) :: boolean()

Returns true when the given map carries a truthy :builtin? (or "builtin?") flag directly on it. Does not unwrap a nested :function map — use it for chunk metadata or raw tool-call shapes that don't have the OpenAI function nesting.

For structured %ToolCall{} or OpenAI-wrapped maps, prefer builtin?/1.

@spec from_map(
  t() | map(),
  keyword()
) :: %{id: String.t(), name: String.t(), arguments: map()}

Normalize a map or ToolCall to the standard %{id, name, arguments} format.

Accepts ToolCall structs or plain maps with atom/string keys. Arguments are decoded from JSON if provided as a string.

Examples

iex> ToolCall.from_map(%{"id" => "call_123", "name" => "get_weather", "arguments" => ~s({"location":"Paris"})})
%{id: "call_123", name: "get_weather", arguments: %{"location" => "Paris"}}

iex> tc = ToolCall.new("call_456", "get_time", "{}")
iex> ToolCall.from_map(tc)
%{id: "call_456", name: "get_time", arguments: %{}}

@spec matches_name?(t(), String.t()) :: boolean()

Check if a ToolCall matches the given function name.

@spec metadata(term()) :: map()

Returns metadata attached to a tool call or tool-call-shaped map.

@spec name(t()) :: String.t()

Extract the function name from a ToolCall.

@spec new(String.t() | nil, String.t(), String.t()) :: t()

Create a new ToolCall with OpenAI-compatible structure.

Parameters

• id - Unique identifier (generates "call_<uuid>" if nil)
• name - Function name
• arguments_json - Arguments as JSON-encoded string

Examples

ToolCall.new("call_123", "get_weather", ~s({"location":"SF"}))
ToolCall.new(nil, "get_time", "{}")

@spec new_builtin(String.t() | nil, String.t(), String.t()) :: t()

Create a ToolCall representing a server-side builtin invocation that the provider executed on the model's behalf (e.g. OpenAI Responses API web_search_call, file_search_call).

These calls are exposed in message.tool_calls for inspection and observability — the OTel GenAI bridge surfaces them as tool_call parts in gen_ai.output.messages. They are not replayable: the provider already executed them, and the OpenAI Responses request schema rejects them in input. Request encoders, finish_reason derivation, and tool call ID sanitisers must skip entries where builtin?(tc) is true.

arguments_json should be a JSON-encoded string capturing whatever per-call payload the provider returned (action, query, result URLs, etc.).

@spec provider_native?(t() | map()) :: boolean()

Returns true when local tool-call metadata marks a call as provider-native.

Provider adapters can attach the non-wire marker with put_metadata(call, %{provider_native: provider}), where provider may be an atom, string, map, or true. A false or nil marker is ignored.

Provider-executed builtins use the separate builtin?/1 marker.

@spec put_builtin_flag(map(), boolean()) :: map()

Sets :builtin? => true on map when flag is true; otherwise returns map unchanged. Used by stream/response builders that propagate the builtin marker onto plain tool-call maps before they reach new_builtin/3.

@spec put_metadata(t(), map()) :: t()

Attaches metadata to a ToolCall without changing provider wire encoding.

@spec resolve(t(), [ReqLLM.Tool.t()], keyword()) :: resolution()

Resolves a tool call against application tools without invoking a callback.

The returned map always preserves the original call, raw JSON arguments, and metadata. Application calls are :valid, :invalid, or :unknown. Provider-executed builtins and calls carrying provider-native metadata are returned as :provider_executed or :provider_native and are never treated as application callbacks.

JSON repair follows args_map/2 and can be disabled with json_repair: false.

Returns the Zoi schema for this module

@spec to_map(
  t(),
  keyword()
) :: %{id: String.t(), name: String.t(), arguments: map()}

Convert a ToolCall to a flat map with decoded arguments.

Returns a map with :id, :name, and :arguments keys. Arguments are decoded from JSON; returns empty map if decoding fails.

Examples

iex> tc = ToolCall.new("call_123", "get_weather", ~s({"location":"Paris"}))
iex> ToolCall.to_map(tc)
%{id: "call_123", name: "get_weather", arguments: %{"location" => "Paris"}}

iex> tc = ToolCall.new("call_456", "get_time", "{}")
iex> ToolCall.to_map(tc)
%{id: "call_456", name: "get_time", arguments: %{}}