feat(java): create @CopilotTool and @Param annotations

[Copilot]

Introduces annotation-based tool definition support for the Java SDK via @CopilotTool and @Param in a new com.github.copilot.tool package.

Changes

• New @CopilotTool annotation — RUNTIME retention, METHOD target, marked @CopilotExperimental. Attributes: value() (description), name(), overridesBuiltInTool(), skipPermission(), defer().
• New @Param annotation — RUNTIME retention, PARAMETER target. Attributes: value() (description), name(), required(), defaultValue().
• ToolDefer.NONE — Added as new enum constant (empty string value) to serve as the annotation default for defer(), representing "no preference set".
• Module export — exports com.github.copilot.tool; added to module-info.java.
• Unit tests — Reflection-based verification of retention, targets, defaults, and end-to-end applicability on a sample annotated method.

Usage

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

Note: This task creates only the annotations — no processor logic, schema generation, or runtime scanning is included.

[github-actions]

Generated by SDK Consistency Review Agent for issue #1763 · sonnet46 1.6M

[Copilot]

Pull request overview

This PR adds a new annotation-based API surface to the Java SDK for defining tools via @CopilotTool (method-level) and @Param (parameter-level), and exports the new com.github.copilot.tool package from the Java module. It also introduces a ToolDefer.NONE enum constant intended as an annotation default, plus unit tests validating the annotations’ retention/targets/defaults via reflection.

Changes:

• Added @CopilotTool and @Param annotations under com.github.copilot.tool (runtime-retained) for future tool metadata discovery.
• Exported com.github.copilot.tool from module-info.java to make the annotations available to consumers.
• Added ToolDefer.NONE as an annotation sentinel and added unit tests for annotation metadata.

Show a summary per file

File	Description
java/src/test/java/com/github/copilot/tool/CopilotToolAnnotationTest.java	Adds reflection-based tests validating retention, targets, defaults, and sample usage of the new annotations.
java/src/main/java/module-info.java	Exports the new com.github.copilot.tool package.
java/src/main/java/com/github/copilot/tool/Param.java	Introduces @Param annotation for parameter metadata.
java/src/main/java/com/github/copilot/tool/CopilotTool.java	Introduces @CopilotTool annotation for tool methods (marked experimental).
java/src/main/java/com/github/copilot/rpc/ToolDefer.java	Adds ToolDefer.NONE and changes serialization behavior for the enum.

Copilot's findings

• Files reviewed: 5/5 changed files
• Comments generated: 5

[github-actions]

Cross-SDK Consistency Review ✅

This PR adds @CopilotTool and @Param annotations to the Java SDK. I reviewed the changes against the other five SDK implementations (Node.js, Python, Go, .NET, Rust).

Attribute parity — consistent with all SDKs

Attribute	Java (@CopilotTool)	Node.js (defineTool)	Python (@define_tool)	Go (Tool struct)	.NET (CopilotToolOptions)
description	value()	description	description	Description	via AIFunctionFactory
name	name()	first arg	first arg	Name	delegate name
overrides built-in	overridesBuiltInTool	overridesBuiltInTool	overrides_built_in_tool	OverridesBuiltInTool	OverridesBuiltInTool
skip permission	skipPermission	skipPermission	skip_permission	SkipPermission	SkipPermission
defer mode	defer (ToolDefer.AUTO/NEVER)	`defer: "auto"	"never"`	defer: Literal["auto","never"]	Defer ToolDefer

Parameter metadata — consistent approach

@Param is the Java-idiomatic equivalent of other SDKs' parameter description mechanisms: Python's pydantic.Field(description=...), .NET's [Description(...)], Go's struct-tag comments, and Rust's /// doc comments on schema fields. The required = true default aligns with all SDKs, where parameters without defaults are implicitly required.

ToolDefer.NONE sentinel — Java-specific and well-justified

Adding NONE("") as an annotation-default sentinel is a necessary Java limitation workaround (annotation attribute defaults cannot be null). The Javadoc on the constant is thorough and correctly warns against passing NONE to ToolDefinition factory methods. This pattern has no analog in other SDKs, but it is purely internal to the Java implementation and doesn't affect wire protocol consistency.

Two-phase implementation — noted for awareness

The other SDKs' ergonomic helpers (defineTool, @define_tool, CopilotTool.DefineTool, DefineTool) are fully functional today. This PR delivers only the annotation declarations; the scanner/processor/reflection logic that makes @CopilotTool actually work at runtime is deferred to a follow-up task (as explicitly stated in the PR description). This is a deliberate incremental approach and not a consistency concern, but reviewers should be aware that @CopilotTool annotated methods will not be discovered automatically until the processor is implemented.

Summary

No cross-SDK inconsistencies found. The new annotations are semantically aligned with the equivalent ergonomic APIs in all other SDKs, accounting for Java-specific language idioms.

Generated by SDK Consistency Review Agent for issue #1763 · sonnet46 1.3M · ◷