Package com.github.copilot.sdk.json

Class ToolDefinition

java.lang.Object
com.github.copilot.sdk.json.ToolDefinition
public class ToolDefinition extends Object
Defines a tool that can be invoked by the AI assistant.

Tools extend the assistant's capabilities by allowing it to call back into your application to perform actions or retrieve information. Each tool has a name, description, parameter schema, and a handler function that executes when the tool is invoked.

Example Usage


 // Define a record for your tool's arguments
 record WeatherArgs(String location) {
 }

 var tool = ToolDefinition.create("get_weather", "Get the current weather for a location",
 		Map.of("type", "object", "properties",
 				Map.of("location", Map.of("type", "string", "description", "City name")), "required",
 				List.of("location")),
 		invocation -> {
 			// Type-safe access with records (recommended)
 			WeatherArgs args = invocation.getArgumentsAs(WeatherArgs.class);
 			return CompletableFuture.completedFuture(getWeatherData(args.location()));

 			// Or use Map-based access
 			// Map<String, Object> args = invocation.getArguments();
 			// String location = (String) args.get("location");
 		});
Since:
1.0.0
See Also:

  • Constructor Details

    • ToolDefinition

      public ToolDefinition()
      Creates an empty tool definition.

      Use the setter methods to configure the tool.

    • ToolDefinition

      public ToolDefinition(String name, String description, Object parameters, ToolHandler handler)
      Creates a tool definition with all properties.
      Parameters:
      name - the unique name of the tool
      description - a description of what the tool does
      parameters - the JSON Schema defining the tool's parameters
      handler - the handler function to execute when invoked

  • Method Details

    • getName

      public String getName()
      Gets the tool name.
      Returns:
      the unique name of the tool

    • setName

      public ToolDefinition setName(String name)
      Sets the tool name.

      The name should be unique within a session and follow naming conventions similar to function names (e.g., "get_user", "search_files").

      Parameters:
      name - the unique name of the tool
      Returns:
      this tool definition for method chaining

    • getDescription

      public String getDescription()
      Gets the tool description.
      Returns:
      the description of what the tool does

    • setDescription

      public ToolDefinition setDescription(String description)
      Sets the tool description.

      The description helps the AI understand when and how to use the tool. Be clear and specific about the tool's purpose and any constraints.

      Parameters:
      description - the description of what the tool does
      Returns:
      this tool definition for method chaining

    • getParameters

      public Object getParameters()
      Gets the parameter schema.
      Returns:
      the JSON Schema for the tool's parameters

    • setParameters

      public ToolDefinition setParameters(Object parameters)
      Sets the parameter schema.

      The schema should follow JSON Schema format and define the structure of arguments the tool accepts. This is typically a Map with "type", "properties", and "required" fields.

      Parameters:
      parameters - the JSON Schema for the tool's parameters
      Returns:
      this tool definition for method chaining

    • getHandler

      public ToolHandler getHandler()
      Gets the tool handler.
      Returns:
      the handler function that executes when the tool is invoked

    • setHandler

      public ToolDefinition setHandler(ToolHandler handler)
      Sets the tool handler.

      The handler is called when the assistant invokes this tool. It receives a ToolInvocation with the arguments and should return a CompletableFuture with the result.

      Parameters:
      handler - the handler function
      Returns:
      this tool definition for method chaining
      See Also:

    • create

      public static ToolDefinition create(String name, String description, Map<String,Object> schema, ToolHandler handler)
      Creates a tool definition with a JSON schema for parameters.

      This is a convenience factory method for creating tools with a Map-based parameter schema.

      Parameters:
      name - the unique name of the tool
      description - a description of what the tool does
      schema - the JSON Schema as a Map
      handler - the handler function to execute when invoked
      Returns:
      a new tool definition