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:

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.

ToolDefinition

defer(ToolDefer value)

Returns a copy with the defer mode set.

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 <T1,T2,R> ToolDefinition

from(String name, String description, Param<T1> p1, Param<T2> p2, BiFunction<T1,T2,R> handler)

Creates a tool definition with a two-argument synchronous handler.

static <T1,R> ToolDefinition

from(String name, String description, Param<T1> p1, Function<T1,R> handler)

Creates a tool definition with a one-argument synchronous handler.

static <R> ToolDefinition

from(String name, String description, Supplier<R> handler)

Creates a tool definition with a zero-argument synchronous handler.

static <T1,T2,R> ToolDefinition

fromAsync(String name, String description, Param<T1> p1, Param<T2> p2, BiFunction<T1, T2, CompletableFuture<R>> handler)

Creates a tool definition with a two-argument asynchronous handler.

static <T1,R> ToolDefinition

fromAsync(String name, String description, Param<T1> p1, Function<T1, CompletableFuture<R>> handler)

Creates a tool definition with a one-argument asynchronous handler.

static <R> ToolDefinition

fromAsync(String name, String description, Supplier<CompletableFuture<R>> handler)

Creates a tool definition with a zero-argument asynchronous handler.

static <T1,R> ToolDefinition

fromAsyncWithToolInvocation(String name, String description, Param<T1> p1, BiFunction<T1, ToolInvocation, CompletableFuture<R>> handler)

Creates a tool definition with a one-argument asynchronous handler that also receives the ToolInvocation context.

static <R> ToolDefinition

fromAsyncWithToolInvocation(String name, String description, Function<ToolInvocation, CompletableFuture<R>> handler)

Creates a tool definition with a zero-argument asynchronous handler that receives the ToolInvocation context.

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.

static <T1,R> ToolDefinition

fromWithToolInvocation(String name, String description, Param<T1> p1, BiFunction<T1, ToolInvocation, R> handler)

Creates a tool definition with a one-argument synchronous handler that also receives the ToolInvocation context.

static <R> ToolDefinition

fromWithToolInvocation(String name, String description, Function<ToolInvocation, R> handler)

Creates a tool definition with a zero-argument synchronous handler that receives the ToolInvocation context.

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.

ToolDefinition

overridesBuiltInTool(boolean value)

Returns a copy with the overridesBuiltInTool flag set.

Object

parameters()

Returns the value of the parameters record component.

Boolean

skipPermission()

Returns the value of the skipPermission record component.

ToolDefinition

skipPermission(boolean value)

Returns a copy with the skipPermission flag set.

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.6
- 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.6
- overridesBuiltInTool
  
  @CopilotExperimental public ToolDefinition overridesBuiltInTool(boolean value)
  
  Returns a copy with the overridesBuiltInTool flag set.
  
  Parameters:
  
  value - true to indicate this tool intentionally overrides a built-in CLI tool with the same name
  
  Returns:
  
  a new ToolDefinition with the flag applied
  
  Since:
  
  1.0.6
- skipPermission
  
  @CopilotExperimental public ToolDefinition skipPermission(boolean value)
  
  Returns a copy with the skipPermission flag set.
  
  Parameters:
  
  value - true to skip the permission request for this tool invocation
  
  Returns:
  
  a new ToolDefinition with the flag applied
  
  Since:
  
  1.0.6
- defer
  
  @CopilotExperimental public ToolDefinition defer(ToolDefer value)
  
  Returns a copy with the defer mode set.
  
  Parameters:
  
  value - the deferral mode; use ToolDefer.AUTO to allow deferral or ToolDefer.NEVER to force the tool to always be pre-loaded
  
  Returns:
  
  a new ToolDefinition with the defer mode applied
  
  Since:
  
  1.0.6
- from
  @CopilotExperimental public static <R> ToolDefinition from(String name, String description, Supplier<R> handler)
  
  Creates a tool definition with a zero-argument synchronous handler.
  The handler is a Supplier that returns the tool result.
  Example
  
  ToolDefinition ping = ToolDefinition.from("ping", "Returns a simple pong response", () -> "pong");
  
  Type Parameters:
  
  R - the return type of the handler
  
  Parameters:
  
  name - the unique name of the tool (must not be blank)
  
  description - a description of what the tool does (must not be blank)
  
  handler - the zero-argument sync handler
  
  Returns:
  
  a new tool definition
  
  Throws:
  
  IllegalArgumentException - if name or description is blank, or if handler is null
  
  Since:
  
  1.0.6
- from
  @CopilotExperimental public static <T1,R> ToolDefinition from(String name, String description, Param<T1> p1, Function<T1,R> handler)
  
  Creates a tool definition with a one-argument synchronous handler.
  Example
  
  ToolDefinition greet = ToolDefinition.from("greet", "Greets a user by name", Param.of(String.class, "name", "The user's name"), name -> "Hello, " + name + "!");
  
  Type Parameters:
  
  T1 - the type of the first parameter
  
  R - the return type of the handler
  
  Parameters:
  
  name - the unique name of the tool (must not be blank)
  
  description - a description of what the tool does (must not be blank)
  
  p1 - the first parameter descriptor
  
  handler - the one-argument sync handler
  
  Returns:
  
  a new tool definition
  
  Throws:
  
  IllegalArgumentException - if validation fails
  
  Since:
  
  1.0.6
- from
  @CopilotExperimental public static <T1,T2,R> ToolDefinition from(String name, String description, Param<T1> p1, Param<T2> p2, BiFunction<T1,T2,R> handler)
  
  Creates a tool definition with a two-argument synchronous handler.
  Example
  
  ToolDefinition add = ToolDefinition.from("add", "Adds two integers", Param.of(Integer.class, "a", "First number"), Param.of(Integer.class, "b", "Second number"), (a, b) -> a + b);
  
  Type Parameters:
  
  T1 - the type of the first parameter
  
  T2 - the type of the second parameter
  
  R - the return type of the handler
  
  Parameters:
  
  name - the unique name of the tool (must not be blank)
  
  description - a description of what the tool does (must not be blank)
  
  p1 - the first parameter descriptor
  
  p2 - the second parameter descriptor
  
  handler - the two-argument sync handler
  
  Returns:
  
  a new tool definition
  
  Throws:
  
  IllegalArgumentException - if validation fails
  
  Since:
  
  1.0.6
- fromAsync
  @CopilotExperimental public static <R> ToolDefinition fromAsync(String name, String description, Supplier<CompletableFuture<R>> handler)
  
  Creates a tool definition with a zero-argument asynchronous handler.
  The handler is a Supplier returning a CompletableFuture.
  Example
  
  ToolDefinition ping = ToolDefinition.fromAsync("ping", "Returns a pong response asynchronously", () -> CompletableFuture.completedFuture("pong"));
  
  Type Parameters:
  
  R - the return type wrapped in CompletableFuture
  
  Parameters:
  
  name - the unique name of the tool (must not be blank)
  
  description - a description of what the tool does (must not be blank)
  
  handler - the zero-argument async handler
  
  Returns:
  
  a new tool definition
  
  Throws:
  
  IllegalArgumentException - if validation fails
  
  Since:
  
  1.0.6
- fromAsync
  @CopilotExperimental public static <T1,R> ToolDefinition fromAsync(String name, String description, Param<T1> p1, Function<T1, CompletableFuture<R>> handler)
  
  Creates a tool definition with a one-argument asynchronous handler.
  Example
  
  ToolDefinition greet = ToolDefinition.fromAsync("greet_async", "Greets a user by name asynchronously", Param.of(String.class, "name", "The user's name"), name -> CompletableFuture.completedFuture("Hello, " + name + "!"));
  
  Type Parameters:
  
  T1 - the type of the first parameter
  
  R - the return type wrapped in CompletableFuture
  
  Parameters:
  
  name - the unique name of the tool (must not be blank)
  
  description - a description of what the tool does (must not be blank)
  
  p1 - the first parameter descriptor
  
  handler - the one-argument async handler
  
  Returns:
  
  a new tool definition
  
  Throws:
  
  IllegalArgumentException - if validation fails
  
  Since:
  
  1.0.6
- fromAsync
  
  @CopilotExperimental public static <T1,T2,R> ToolDefinition fromAsync(String name, String description, Param<T1> p1, Param<T2> p2, BiFunction<T1, T2, CompletableFuture<R>> handler)
  
  Creates a tool definition with a two-argument asynchronous handler.
  
  Type Parameters:
  
  T1 - the type of the first parameter
  
  T2 - the type of the second parameter
  
  R - the return type wrapped in CompletableFuture
  
  Parameters:
  
  name - the unique name of the tool (must not be blank)
  
  description - a description of what the tool does (must not be blank)
  
  p1 - the first parameter descriptor
  
  p2 - the second parameter descriptor
  
  handler - the two-argument async handler
  
  Returns:
  
  a new tool definition
  
  Throws:
  
  IllegalArgumentException - if validation fails
  
  Since:
  
  1.0.6
- fromWithToolInvocation
  @CopilotExperimental public static <R> ToolDefinition fromWithToolInvocation(String name, String description, Function<ToolInvocation, R> handler)
  
  Creates a tool definition with a zero-argument synchronous handler that receives the ToolInvocation context.
  Example
  
  ToolDefinition sessionInfo = ToolDefinition.fromWithToolInvocation("session_info", "Return the current session id", invocation -> "sessionId=" + invocation.getSessionId());
  
  Type Parameters:
  
  R - the return type of the handler
  
  Parameters:
  
  name - the unique name of the tool (must not be blank)
  
  description - a description of what the tool does (must not be blank)
  
  handler - a function accepting the ToolInvocation context
  
  Returns:
  
  a new tool definition
  
  Throws:
  
  IllegalArgumentException - if validation fails
  
  Since:
  
  1.0.6
- fromWithToolInvocation
  @CopilotExperimental public static <T1,R> ToolDefinition fromWithToolInvocation(String name, String description, Param<T1> p1, BiFunction<T1, ToolInvocation, R> handler)
  
  Creates a tool definition with a one-argument synchronous handler that also receives the ToolInvocation context.
  Example
  
  ToolDefinition reportPhase = ToolDefinition.fromWithToolInvocation("report_phase", "Report the current phase along with invocation context", Param.of(String.class, "phase", "Current phase"), (phase, invocation) -> "phase=" + phase + ", toolCallId=" + invocation.getToolCallId());
  
  Type Parameters:
  
  T1 - the type of the first parameter
  
  R - the return type of the handler
  
  Parameters:
  
  name - the unique name of the tool (must not be blank)
  
  description - a description of what the tool does (must not be blank)
  
  p1 - the first parameter descriptor
  
  handler - a function accepting the typed argument and the ToolInvocation context
  
  Returns:
  
  a new tool definition
  
  Throws:
  
  IllegalArgumentException - if validation fails
  
  Since:
  
  1.0.6
- fromAsyncWithToolInvocation
  @CopilotExperimental public static <R> ToolDefinition fromAsyncWithToolInvocation(String name, String description, Function<ToolInvocation, CompletableFuture<R>> handler)
  
  Creates a tool definition with a zero-argument asynchronous handler that receives the ToolInvocation context.
  Example
  
  ToolDefinition sessionInfo = ToolDefinition.fromAsyncWithToolInvocation("session_info_async", "Return the current session id asynchronously", invocation -> CompletableFuture.completedFuture("sessionId=" + invocation.getSessionId()));
  
  Type Parameters:
  
  R - the return type wrapped in CompletableFuture
  
  Parameters:
  
  name - the unique name of the tool (must not be blank)
  
  description - a description of what the tool does (must not be blank)
  
  handler - a function accepting the ToolInvocation context, returning a CompletableFuture
  
  Returns:
  
  a new tool definition
  
  Throws:
  
  IllegalArgumentException - if validation fails
  
  Since:
  
  1.0.6
- fromAsyncWithToolInvocation
  @CopilotExperimental public static <T1,R> ToolDefinition fromAsyncWithToolInvocation(String name, String description, Param<T1> p1, BiFunction<T1, ToolInvocation, CompletableFuture<R>> handler)
  
  Creates a tool definition with a one-argument asynchronous handler that also receives the ToolInvocation context.
  Example
  
  ToolDefinition reportPhase = ToolDefinition.fromAsyncWithToolInvocation("report_phase_async", "Report the current phase with invocation context asynchronously", Param.of(String.class, "phase", "The current phase"), (phase, invocation) -> CompletableFuture .completedFuture("phase=" + phase + ", toolCallId=" + invocation.getToolCallId()));
  
  Type Parameters:
  
  T1 - the type of the first parameter
  
  R - the return type wrapped in CompletableFuture
  
  Parameters:
  
  name - the unique name of the tool (must not be blank)
  
  description - a description of what the tool does (must not be blank)
  
  p1 - the first parameter descriptor
  
  handler - a function accepting the typed argument and the ToolInvocation context, returning a CompletableFuture
  
  Returns:
  
  a new tool definition
  
  Throws:
  
  IllegalArgumentException - if validation fails
  
  Since:
  
  1.0.6
- 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

Record Class ToolDefinition

Example Usage

Constructor Summary

Method Summary

Methods inherited from class Object

Constructor Details

ToolDefinition

Method Details

create

createOverride

createSkipPermission

createWithDefer

fromObject

fromClass

overridesBuiltInTool

skipPermission

defer

from

Example

from

Example

from

Example

fromAsync

Example

fromAsync

Example

fromAsync

fromWithToolInvocation

Example

fromWithToolInvocation

Example

fromAsyncWithToolInvocation

Example

fromAsyncWithToolInvocation

Example

toString

hashCode

equals

name

description

parameters

handler

overridesBuiltInTool

skipPermission

defer