Add ADR-005: Ergonomic tool definition via annotation processor#1684
Merged
Conversation
Introduces an Architecture Decision Record documenting the plan to add a langchain4j-style annotation-on-method API for defining Copilot tools in Java. ## Problem The current `ToolDefinition.create()` API requires manually constructing JSON Schema parameter objects—verbose and error-prone compared to the ergonomic patterns available in other Java AI frameworks (langchain4j `@Tool`/`@P`, Spring AI `@Tool`/`@ToolParam`). ## Decision Adopt Option 3 (annotation-on-method) with a JSR 269 annotation processor: - `@CopilotTool` on methods defines tools; method name → tool name, Javadoc/annotation attribute → description. - `@Param` on parameters provides descriptions and constraints; the processor reads source-level parameter names at compile time, eliminating the need for the `-parameters` javac flag. - A compile-time annotation processor generates `ToolDefinition` instances and JSON Schema from annotated methods—no runtime reflection required. - The new API surface is gated behind `@CopilotExperimental` (ADR-004) until stabilized. - The existing `ToolDefinition.create()` / `CopilotTools.define()` APIs remain unchanged and fully supported. ## Scope This ADR captures the design decision only. Implementation will follow in a separate PR tracked by #1682. Related: #1682 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This was referenced Jun 18, 2026
This was referenced Jun 25, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Introduces an Architecture Decision Record documenting the plan to add a langchain4j-style annotation-on-method API for defining Copilot tools in Java.
Problem
The current
ToolDefinition.create()API requires manually constructing JSON Schema parameter objects—verbose and error-prone compared to the ergonomic patterns available in other Java AI frameworks (langchain4j@Tool/@P, Spring AI@Tool/@ToolParam).Decision
Adopt Option 3 (annotation-on-method) with a JSR 269 annotation processor:
@CopilotToolon methods defines tools; method name → tool name, Javadoc/annotation attribute → description.@Paramon parameters provides descriptions and constraints; the processor reads source-level parameter names at compile time, eliminating the need for the-parametersjavac flag.ToolDefinitioninstances and JSON Schema from annotated methods—no runtime reflection required.@CopilotExperimental(ADR-004) until stabilized.ToolDefinition.create()/CopilotTools.define()APIs remain unchanged and fully supported.Scope
This ADR captures the design decision only. Implementation will follow in a separate PR tracked by #1682.
Related: #1682