# Class Tool

java.lang.Object
com.codename1.ai.Tool

public final class Tool extends Object

A function the model can call. `parametersJsonSchema` is a raw JSON-Schema string; each provider wraps it differently on the wire (OpenAI `{type:"function",function:{...}}`, Anthropic `{name,description,input_schema}`, Gemini `functionDeclarations`), but the inner schema shape is the same across all of them, so we hand it through as a string and let the provider client wrap.

##### Linking a tool to its executor

Pass an optional `ToolHandler` at construction time and the matching `ToolCall` can dispatch through it without the caller having to match names by hand:

    Tool weather = new Tool(
        "get_weather",
        "Returns the current weather for a location",
        "{\"type\":\"object\",\"properties\":{" +
           "\"location\":{\"type\":\"string\"}}," +
           "\"required\":[\"location\"]}",
        argumentsJson -> {
            Map args = JSONParser.parseJSON(argumentsJson);
            return "{\"temp\":21,\"city\":\""
                    + JSONParser.getString(args, "location") + "\"}";
        });

    // Later, when the model returns a ToolCall:
    for (ToolCall call : response.getToolCalls()) {
        String resultJson = call.execute(Arrays.asList(weather));
        conversation.add(ChatMessage.toolResult(call.getId(), resultJson));
    }

The handler is optional -- a `Tool` constructed without one is a pure description for the model, and the caller can dispatch however they like via the raw `ToolCall.getName()` / `ToolCall.getArgumentsJson()` accessors.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Tool(String name, String description, String parametersJsonSchema)`
  Creates a description-only tool for manual dispatch.
  `Tool(String name, String description, String parametersJsonSchema, ToolHandler handler)`
  Creates a tool definition with an application executor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `String`
  `getDescription()`
  `ToolHandler`
  `getHandler()`
  The optional executor wired up by the constructor.
  `String`
  `getName()`
  `String`
  `getParametersJsonSchema()`
  `String`
  `invoke(String argumentsJson)`
  Invokes the handler with the given arguments JSON.

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### Tool

    public Tool(String name, String description, String parametersJsonSchema)
    Creates a description-only tool for manual dispatch.
    Parameters:
      `name` - provider-visible function name
      `description` - guidance that helps the model choose the tool
      `parametersJsonSchema` - JSON Schema for accepted arguments

  - ### Tool

    public Tool(String name, String description, String parametersJsonSchema, ToolHandler handler)
    Creates a tool definition with an application executor.
    Parameters:
      `name` - provider-visible function name
      `description` - guidance that helps the model choose the tool
      `parametersJsonSchema` - JSON Schema for accepted arguments
      `handler` - executor called by `invoke(String)`, or `null`

- ## Method Details

  - ### getName

    public String getName()
    Returns:
      provider-visible function name

  - ### getDescription

    public String getDescription()
    Returns:
      description used by the model to decide when to call the tool

  - ### getParametersJsonSchema

    public String getParametersJsonSchema()
    Returns:
      JSON Schema describing accepted function arguments

  - ### getHandler

    public ToolHandler getHandler()
    The optional executor wired up by the constructor. Returns `null` for description-only tools.
    Returns:
      registered executor, or `null`

  - ### invoke

    public String invoke(String argumentsJson) throws Exception
    Invokes the handler with the given arguments JSON. Throws `IllegalStateException` when no handler was registered.
    Parameters:
      `argumentsJson` - model-generated arguments
    Returns:
      handler result encoded as JSON
    Throws:
      `Exception` - when the handler rejects or cannot execute the call