Record Class ToolDefinition

java.lang.Object

java.lang.Record

com.github.copilot.rpc.ToolDefinition

Record Components:

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

overridesBuiltInTool - when true, indicates that this tool intentionally overrides a built-in CLI tool with the same name; null or false means the tool is purely custom

skipPermission - when true, the CLI skips the permission request for this tool invocation; null or false uses normal permission handling

defer - controls whether the tool may be deferred (loaded lazily via tool search) rather than always pre-loaded; null lets the runtime decide

public record ToolDefinition(String name, String description, Object parameters, ToolHandler handler, Boolean overridesBuiltInTool, Boolean skipPermission, ToolDefer defer)
extends Record

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:

• SessionConfig.setTools(java.util.List)
• ToolHandler

Constructor Summary

Constructors

Constructor	Description
ToolDefinition(String name, String description, Object parameters, ToolHandler handler, Boolean overridesBuiltInTool, Boolean skipPermission, ToolDefer defer)	Creates an instance of a ToolDefinition record class.

Method Summary

Modifier and Type	Method	Description
static ToolDefinition	create(String name, String description, Map<String,Object> schema, ToolHandler handler)	Creates a tool definition with a JSON schema for parameters.
static ToolDefinition	createOverride(String name, String description, Map<String,Object> schema, ToolHandler handler)	Creates a tool definition that overrides a built-in CLI tool.
static ToolDefinition	createSkipPermission(String name, String description, Map<String,Object> schema, ToolHandler handler)	Creates a tool definition that skips the permission request.
static ToolDefinition	createWithDefer(String name, String description, Map<String,Object> schema, ToolHandler handler, ToolDefer defer)	Creates a tool definition with an explicit deferral mode.
ToolDefer	defer()	Returns the value of the defer record component.
String	description()	Returns the value of the description record component.
final boolean	equals(Object o)	Indicates whether some other object is "equal to" this one.
static List<ToolDefinition>	fromClass(Class<?> clazz)	Discovers tool definitions from a class with static @CopilotTool-annotated methods.
static List<ToolDefinition>	fromObject(Object instance)	Discovers tool definitions from an object whose methods are annotated with @CopilotTool.
ToolHandler	handler()	Returns the value of the handler record component.
final int	hashCode()	Returns a hash code value for this object.
String	name()	Returns the value of the name record component.
Boolean	overridesBuiltInTool()	Returns the value of the overridesBuiltInTool record component.
Object	parameters()	Returns the value of the parameters record component.
Boolean	skipPermission()	Returns the value of the skipPermission record component.
final String	toString()	Returns a string representation of this record class.

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Details

ToolDefinition

public ToolDefinition(String name,
 String description,
 Object parameters,
 ToolHandler handler,
 Boolean overridesBuiltInTool,
 Boolean skipPermission,
 ToolDefer defer)

Creates an instance of a ToolDefinition record class.

Parameters:

name - the value for the name record component

description - the value for the description record component

parameters - the value for the parameters record component

handler - the value for the handler record component

overridesBuiltInTool - the value for the overridesBuiltInTool record component

skipPermission - the value for the skipPermission record component

defer - the value for the defer record component

Method Details

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

createOverride

public static ToolDefinition createOverride(String name,
 String description,
 Map<String,Object> schema,
 ToolHandler handler)

Creates a tool definition that overrides a built-in CLI tool.

Use this factory method when you want your custom tool to replace a built-in tool (e.g., grep, read_file) with the same name. Setting overridesBuiltInTool to true signals to the CLI that this is intentional.

Parameters:

name - the name of the built-in tool to override

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 with the override flag set

Since:

1.0.11

createSkipPermission

public static ToolDefinition createSkipPermission(String name,
 String description,
 Map<String,Object> schema,
 ToolHandler handler)

Creates a tool definition that skips the permission request.

Use this factory method when the tool is safe to invoke without user permission confirmation. Setting skipPermission to true signals to the CLI that no permission check is needed.

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 with permission skipping enabled

Since:

1.0.0

createWithDefer

public static ToolDefinition createWithDefer(String name,
 String description,
 Map<String,Object> schema,
 ToolHandler handler,
 ToolDefer defer)

Creates a tool definition with an explicit deferral mode.

Use this factory method to control whether the tool may be deferred (loaded lazily via tool search) rather than always pre-loaded. Pass ToolDefer.AUTO to allow deferral and ToolDefer.NEVER to force the tool to always be pre-loaded.

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

defer - the deferral mode for the tool

Returns:

a new tool definition with the deferral mode set

Since:

1.0.0

fromObject

@CopilotExperimental
public static List<ToolDefinition> fromObject(Object instance)

Discovers tool definitions from an object whose methods are annotated with @CopilotTool. Requires that the CopilotToolProcessor annotation processor ran at compile time (generating the $$CopilotToolMeta companion class).

Parameters:

instance - the object containing @CopilotTool-annotated methods

Returns:

list of tool definitions with working invocation handlers

Throws:

IllegalStateException - if the generated $$CopilotToolMeta class is not found (annotation processor did not run)

Since:

1.0.2

fromClass

@CopilotExperimental
public static List<ToolDefinition> fromClass(Class<?> clazz)

Discovers tool definitions from a class with static @CopilotTool-annotated methods. Requires that the CopilotToolProcessor annotation processor ran at compile time (generating the $$CopilotToolMeta companion class).

Parameters:

clazz - the class containing static @CopilotTool-annotated methods

Returns:

list of tool definitions with working invocation handlers

Throws:

IllegalStateException - if the generated $$CopilotToolMeta class is not found (annotation processor did not run)

Since:

1.0.2

toString

public final String toString()

Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.

Specified by:

toString in class Record

Returns:

a string representation of this object

hashCode

public final int hashCode()

Returns a hash code value for this object. The value is derived from the hash code of each of the record components.

Specified by:

hashCode in class Record

Returns:

a hash code value for this object

equals

public final boolean equals(Object o)

Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with Objects::equals(Object,Object).

Specified by:

equals in class Record

Parameters:

o - the object with which to compare

Returns:

true if this object is the same as the o argument; false otherwise.

name

public String name()

Returns the value of the name record component.

Returns:

the value of the name record component

description

public String description()

Returns the value of the description record component.

Returns:

the value of the description record component

parameters

public Object parameters()

Returns the value of the parameters record component.

Returns:

the value of the parameters record component

handler

public ToolHandler handler()

Returns the value of the handler record component.

Returns:

the value of the handler record component

overridesBuiltInTool

public Boolean overridesBuiltInTool()

Returns the value of the overridesBuiltInTool record component.

Returns:

the value of the overridesBuiltInTool record component

skipPermission

public Boolean skipPermission()

Returns the value of the skipPermission record component.

Returns:

the value of the skipPermission record component

defer

public ToolDefer defer()

Returns the value of the defer record component.

Returns:

the value of the defer record component