# Class ToolCall

java.lang.Object
com.codename1.ai.ToolCall

public final class ToolCall extends Object

A tool/function invocation produced by the model. The `id` round- trips the call back to a `ToolResultPart` so the provider can match the result to the original request. `argumentsJson` is the raw JSON string the model produced -- parse it with `JSONParser` if you need the structured fields.

Use `execute(List)` to dispatch to the matching `Tool` handler from the request's tool list. See the `Tool` class javadoc for the full pattern.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ToolCall(String id, String name, String argumentsJson)`
  Creates a normalized model tool call.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `String`
  `execute(List<Tool> tools)`
  Finds the `Tool` whose name matches this call and invokes its `ToolHandler` with this call's `argumentsJson`.
  `Tool`
  `findTool(List<Tool> tools)`
  Looks up the matching `Tool` without invoking it.
  `String`
  `getArgumentsJson()`
  `String`
  `getId()`
  `String`
  `getName()`

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### ToolCall

    public ToolCall(String id, String name, String argumentsJson)
    Creates a normalized model tool call.
    Parameters:
      `id` - provider id used to associate the result
      `name` - requested tool name
      `argumentsJson` - model-generated JSON arguments; `null` becomes `{}`

- ## Method Details

  - ### getId

    public String getId()
    Returns:
      provider id used to associate the eventual tool result

  - ### getName

    public String getName()
    Returns:
      requested tool name

  - ### getArgumentsJson

    public String getArgumentsJson()
    Returns:
      model-generated arguments encoded as JSON

  - ### execute

    public String execute(List<Tool> tools) throws Exception

    Finds the `Tool` whose name matches this call and invokes its `ToolHandler` with this call's `argumentsJson`. Returns the JSON result the handler produced. Apps typically wrap that in a `ChatMessage.toolResult(String, String)` and append it to the conversation before the next chat turn.

    Throws `IllegalArgumentException` when no tool in `tools` has a matching name, or `IllegalStateException` when the matching tool has no handler registered.

    Parameters:
      `tools` - definitions offered with the request
    Returns:
      handler result encoded as JSON
    Throws:
      `Exception` - when lookup or application execution fails

  - ### findTool

    public Tool findTool(List<Tool> tools)
    Looks up the matching `Tool` without invoking it. Useful when the caller wants to dispatch by hand but still benefit from the name-matching plumbing.
    Parameters:
      `tools` - candidate definitions, or `null`
    Returns:
      matching definition, or `null`