# `LangChain.Message.ToolCall`
[🔗](https://github.com/brainlid/langchain/blob/v0.15.3/lib/message/tool_call.ex#L1)

Represents an LLM's request to use tool. It specifies the tool to execute and
may provide arguments for the tool to use.

## Example

    ToolCall.new!(%{
      call_id: "call_123",
      name: "give_greeting"
      arguments: %{"name" => "Howard"}
    })

# `t`
[🔗](https://github.com/brainlid/langchain/blob/v0.15.3/lib/message/tool_call.ex#L42)

```elixir
@type t() :: %LangChain.Message.ToolCall{
  arguments: term(),
  call_id: term(),
  display_text: term(),
  index: term(),
  metadata: term(),
  name: term(),
  status: term(),
  type: term()
}
```

# `arguments_as_map`
[🔗](https://github.com/brainlid/langchain/blob/v0.15.3/lib/message/tool_call.ex#L121)

```elixir
@spec arguments_as_map(t()) :: map()
```

Return the tool call's `arguments` as a map, suitable for serializing to a
provider API that expects a JSON object.

`arguments` are only parsed from a JSON string into a map by `complete/1` (via
`validate_and_parse_arguments/1`), which runs when a tool call reaches
`status: :complete`. A tool call that is serialized without going through that
path (e.g. a persisted/replayed `:incomplete` call, or one accumulated from a
truncated stream) can still hold a raw string. Passing that string to a
provider results in an API error like Anthropic's "Input should be an object".

This normalizes any shape into a map:

  * a map is returned unchanged
  * a JSON-object string is decoded
  * `nil`, an empty string, and undecodable/non-object strings become `%{}`

## Examples

    iex> LangChain.Message.ToolCall.arguments_as_map(%LangChain.Message.ToolCall{arguments: %{"a" => 1}})
    %{"a" => 1}

    iex> LangChain.Message.ToolCall.arguments_as_map(%LangChain.Message.ToolCall{arguments: ~s({"a":1})})
    %{"a" => 1}

    iex> LangChain.Message.ToolCall.arguments_as_map(%LangChain.Message.ToolCall{arguments: ""})
    %{}

    iex> LangChain.Message.ToolCall.arguments_as_map(%LangChain.Message.ToolCall{arguments: nil})
    %{}

# `complete`
[🔗](https://github.com/brainlid/langchain/blob/v0.15.3/lib/message/tool_call.ex#L79)

```elixir
@spec complete(t()) :: {:ok, t()} | {:error, Ecto.Changeset.t()}
```

Ensure the ToolCall's status is set to `:complete`. The process of completing
it parses the tool arguments, which may be invalid. Any problems parsing are
returned as a changeset error.

# `execution_status`
[🔗](https://github.com/brainlid/langchain/blob/v0.15.3/lib/message/tool_call.ex#L319)

```elixir
@spec execution_status(t(), String.t()) :: String.t()
```

Get the execution status from a ToolCall's metadata.

Returns the status string ("identified", "executing", "completed", "failed")
or the default value if not set.

# `merge`
[🔗](https://github.com/brainlid/langchain/blob/v0.15.3/lib/message/tool_call.ex#L184)

```elixir
@spec merge(nil | t(), t()) :: t()
```

The left side, or `primary`, is the ToolCall that is being accumulated. The
`call_part` is being merged into the `primary`.

Used to process streamed deltas where a single tool call can be split over
many smaller parts.

# `new`
[🔗](https://github.com/brainlid/langchain/blob/v0.15.3/lib/message/tool_call.ex#L51)

```elixir
@spec new(attrs :: map()) :: {:ok, t()} | {:error, Ecto.Changeset.t()}
```

Build a new ToolCall and return an `:ok`/`:error` tuple with the result.

# `new!`
[🔗](https://github.com/brainlid/langchain/blob/v0.15.3/lib/message/tool_call.ex#L63)

```elixir
@spec new!(attrs :: map()) :: t() | no_return()
```

Build a new ToolCall and return it or raise an error if invalid.

# `set_execution_status`
[🔗](https://github.com/brainlid/langchain/blob/v0.15.3/lib/message/tool_call.ex#L330)

```elixir
@spec set_execution_status(t(), String.t()) :: t()
```

Set the execution status on a ToolCall's metadata.

---

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