Edburns/1810 java tool ergonomics tool as lambda seeking review

[edburns]

Fixes: #1894

ADR-006: Inline tool definition with lambdas

Context and problem statement

ADR-005 introduced an ergonomic Java tools API based on @CopilotTool method annotations, @CopilotToolParam parameter annotations, and ToolDefinition.fromObject(...) for reflection-based tool registration. That model works well when teams define tools as methods on a class.

The next ergonomics goal is an inline style comparable to C# CopilotTool.DefineTool(...), where developers can define a tool at the call site without creating a separate tool container class.

For this decision, we evaluated two alternatives:

• Method-reference registration (ToolDefinition.from(tools::setCurrentPhase))
• Inline lambda registration (ToolDefinition.from(..., phase -> ...))

The key factor is metadata quality: tool name, description, parameter names, parameter descriptions, required/default semantics, and schema stability.

Considered options

Option 1: Method-reference API

Example:

ToolDefinition setPhase = ToolDefinition.from(tools::setCurrentPhase);

In this model, metadata is sourced from existing method-level annotations (@CopilotTool, @Param) on the referenced method.

Advantages:

• Closest Java analog to C# method-group ergonomics
• High-quality metadata with minimal additional API surface
• Reuses ADR-005 metadata and invocation behavior directly

Drawbacks:

• Not truly inline: still requires a declared method (and usually annotations) elsewhere
• Does not solve the "define the whole tool at the call site" use case
• Method-reference resolution adds runtime/reflection complexity

Option 2: Inline lambda API with explicit metadata

Example:

ToolDefinition setPhase = ToolDefinition.from(
        "set_current_phase",
        "Sets the current phase of the agent",
        Param.of(String.class, "phase", "The phase to transition to"),
        (String phase) -> {
            currentPhase = phase;
            return "Phase set to " + phase;
        });

In this model, handler logic is inline, and metadata is provided explicitly through Param.of(...) parameter definitions.

Advantages:

• True inline authoring at the session construction site
• No dependence on lambda parameter-name reflection or -parameters
• Deterministic metadata and schema generation
• Independent from annotation processing and generated companion classes

Drawbacks:

• Slightly more verbose than method-reference style because metadata is explicit
• Introduces new public API types for parameter definitions and typed lambda overloads
• Requires careful API design to stay concise for common one-parameter tools

Decision outcome

Chosen: Option 2 for ADR-006 scope — inline lambda API with explicit metadata.

Rationale:

1. The primary requirement for this ADR is inline definition. Option 2 satisfies it directly; Option 1 does not.
2. Metadata quality is the critical requirement. Option 2 keeps metadata explicit and stable, instead of relying on fragile lambda introspection.
3. Option 2 can ship independently of method-reference support and without changes to annotation processing.
4. Option 2 preserves behavior parity with existing tool execution by delegating to ToolDefinition construction and current invocation semantics.

Option 1 remains valuable and can be added independently as a separate ergonomic layer. It is not blocked by this decision.

Design constraints and non-goals

Constraints for the inline lambda API:

• Require explicit tool name and description.
• Require explicit parameter metadata (at minimum name and type, with optional description/required/default).
• Support both sync and async handlers (R and CompletableFuture<R>).
• Keep result semantics aligned with existing behavior (String passthrough, void maps to "Success", non-string objects serialized to JSON).
• Keep override/permission/defer flags available through options, consistent with existing ToolDefinition fields.

Non-goals for this ADR:

• Replacing @CopilotTool/fromObject APIs.
• Defining method-reference registration behavior in detail.
• Introducing compile-time code generation for lambda metadata.

Consequences

The SDK now provides an explicit inline path for developers who prefer to keep tool declarations at session creation while preserving high-quality schema metadata. Implemented API families include:

• ToolDefinition.from(name, description, [params...], handler) — sync handlers
• ToolDefinition.fromAsync(name, description, [params...], asyncHandler) — async handlers returning CompletableFuture<R>
• ToolDefinition.fromWithToolInvocation(...) — sync with ToolInvocation context injection
• ToolDefinition.fromAsyncWithToolInvocation(...) — async with ToolInvocation context injection

Parameter metadata is defined using Param.of(type, name, description) for required parameters and Param.of(type, name, description, required, defaultValue) for optional parameters with defaults.

Fluent option modifiers (.skipPermission(boolean), .defer(ToolDefer), .overridesBuiltInTool(boolean)) allow post-construction customization.

The annotation-driven API from ADR-005 remains the recommended path for larger tool surfaces where co-locating metadata with method implementations improves maintainability. For usage examples and complete API coverage, see the Java SDK README.

Related work items

• Java: Ergonomics: Defining tools #1682
• Java: Implement @CopilotTool ergonomics #1792
• [Java] @CopilotTool ergonomics: Define tool with lambda #1810

[Copilot]

Pull request overview

This PR adds a new experimental Java “inline tool definition” API so callers can define Copilot tools at the call site using typed lambdas while providing explicit, stable metadata (tool name/description + parameter metadata), aligning with ADR-006’s decision to avoid fragile lambda introspection.

Changes:

• Introduces com.github.copilot.tool.Param<T> for runtime parameter metadata (name/type/description/required/default).
• Adds ToolDefinition.from* lambda factories (sync/async and ToolInvocation-injecting variants) plus fluent copy-style option modifiers (skipPermission, defer, overridesBuiltInTool).
• Adds unit tests, an E2E integration test, and documentation/ADR updates describing the new API.

Show a summary per file

File	Description
java/src/main/java/com/github/copilot/rpc/ToolDefinition.java	Adds lambda-based tool factory overloads, result formatting, argument coercion, schema generation, and fluent option modifiers.
java/src/main/java/com/github/copilot/tool/Param.java	New public experimental parameter-metadata type for inline lambda tools.
java/src/main/java/com/github/copilot/tool/ParamSchema.java	New internal helper intended to map Param → JSON Schema (currently appears unused).
java/src/main/java/com/github/copilot/tool/ParamCoercion.java	New internal helper intended to coerce args/defaults using ObjectMapper (currently appears unused).
java/src/test/java/com/github/copilot/tool/ParamTest.java	Unit tests covering Param validation and immutability behavior.
java/src/test/java/com/github/copilot/rpc/ToolDefinitionLambdaTest.java	Unit tests covering lambda-tool factories, schema/default semantics, modifiers, coercion, and result formatting.
java/src/test/java/com/github/copilot/e2e/ErgonomicToolDefinitionIT.java	Adds an E2E scenario exercising the lambda-defined tool path.
java/README.md	Documents the new inline lambda tool API and links ADR-006.
java/docs/adr/adr-006-tool-definition-inline.md	Adds ADR-006 documenting the decision and constraints for inline tool definition with lambdas.
1810-java-tool-ergonomics-tool-as-lambda-remove-before-merge/20260628-prompts.md	Adds iteration/prompt log artifact (directory name indicates it should not be merged).
1810-java-tool-ergonomics-tool-as-lambda-remove-before-merge/20260626-prompts.md	Adds iteration/prompt log artifact (directory name indicates it should not be merged).
1810-java-tool-ergonomics-tool-as-lambda-remove-before-merge/1810-ignorance-reduction-for-implementation-plan.md	Adds planning artifact for issue #1810 (directory name indicates it should not be merged).

Review details

• Files reviewed: 9/9 changed files
• Comments generated: 2
• Review effort level: Low

[github-actions]

Cross-SDK Consistency Review ✅

This PR adds inline lambda-style tool definitions to the Java SDK, achieving parity with all other language implementations. No consistency gaps were found.

SDK Tool Definition API Map

SDK	Inline Lambda API
Java (this PR)	ToolDefinition.from(name, desc, params..., handler) / fromAsync(...)
.NET	CopilotTool.DefineTool(delegate, CopilotToolOptions)
Node.js	defineTool(name, { description, parameters, handler, ... })
Python	@define_tool(...) / define_tool(name, description=..., handler=..., params_type=...)
Go	DefineTool[T, U](name, description, handler)
Rust	define_tool(name, description, handler) (derive feature)

All six SDKs now provide an inline closure/lambda/delegate style for tool definition. ✅

Shared Options — All Consistent

The three tool options also exist across all SDKs (using language-idiomatic naming):

Concept	Java	.NET	Node.js	Python	Go	Rust
Override built-in	.overridesBuiltInTool(bool)	OverridesBuiltInTool	overridesBuiltInTool	overrides_built_in_tool	OverridesBuiltInTool	overrides_built_in_tool
Skip permission	.skipPermission(bool)	SkipPermission	skipPermission	skip_permission	SkipPermission	skip_permission
Defer mode	.defer(ToolDefer)	Defer (Auto/Never)	defer ("auto"/"never")	defer ("auto"/"never")	Defer (ToolDeferAuto/ToolDeferNever)	field on Tool struct

The Java ToolDefer.AUTO / ToolDefer.NEVER enum values follow Java idiom and wire-serialize to the same "auto" / "never" string values used by the other SDKs — consistent. ✅

This PR closes the last gap in the inline tool definition feature surface across all language SDKs.

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