Annotation Interface CopilotTool

@Documented
@Retention(RUNTIME)
@Target(METHOD)
@CopilotExperimental
public @interface CopilotTool

Marks a method as a Copilot tool. The annotated method will be exposed to the model as a callable tool during a session.

Example usage:

@CopilotTool("Get weather for a location")
public CompletableFuture<String> getWeather(
                @CopilotToolParam(value = "City name", required = true) String location) {
        return CompletableFuture.completedFuture("Sunny in " + location);
}

Since:

1.0.2

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static @interface	CopilotTool.MetadataEntry	A single metadata key/value pair.
static @interface	CopilotTool.MetadataFlag	A single named boolean flag within a CopilotTool.MetadataValue.flags() map.
static @interface	CopilotTool.MetadataValue	A metadata value.

Required Element Summary

Required Elements

Modifier and Type	Required Element	Description
String	value	Tool description (sent to the model).

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
ToolDefer	defer	Defer configuration for this tool.
CopilotTool.MetadataEntry[]	metadata	Opaque, host-defined metadata for this tool.
String	name	Tool name.
boolean	overridesBuiltInTool	Whether this tool overrides a built-in tool.
boolean	skipPermission	Whether to skip permission checks.

Element Details

value

String value

Tool description (sent to the model).

name

String name

Tool name. Defaults to method name converted to snake_case.

Default:

""

overridesBuiltInTool

boolean overridesBuiltInTool

Whether this tool overrides a built-in tool.

Default:

false

skipPermission

boolean skipPermission

Whether to skip permission checks.

Default:

false

defer

ToolDefer defer

Defer configuration for this tool.

Default:

NONE

metadata

CopilotTool.MetadataEntry[] metadata

Opaque, host-defined metadata for this tool. Keys are namespaced and not part of the stable public API; specific keys may be recognized to inform host-specific behavior.

Because annotation members cannot express arbitrary maps, this uses a deliberately shallow representation: each CopilotTool.MetadataEntry maps a string key to a single CopilotTool.MetadataValue that is either a boolean, a string, or a one-level map of named boolean flags. Numbers, arrays, and deeper nesting are not supported here; use the programmatic ToolDefinition.createWithMetadata(...) / ToolDefinition.metadata(...) API for richer values.

Example emitted shape:

Map.of("github.com/copilot:safeForTelemetry", Map.of("name", true, "inputsNames", false))

Default:

{}