Start iterating on #1682 On branch edburns/1682-java-tool-ergonomics

[edburns]

new file: 1682-java-tool-ergonomics-prompts-remove-before-merge/20260615-prompts.md

[github-actions]

Cross-SDK Consistency Review ✅

This PR adds a Java E2E integration test (LowLevelToolDefinitionIT) and supporting YAML snapshot for the low-level tool definition APIs. I reviewed the APIs being exercised against all six SDK implementations.

APIs Verified Across All SDKs

Feature	Java (this PR)	Node.js	Python	Go	.NET	Rust
Custom tool definition	ToolDefinition.create()	defineTool()	@define_tool	DefineTool[T]()	CopilotTool.DefineTool()	define_tool()
Override built-in tool	ToolDefinition.createOverride()	overridesBuiltInTool: true	overrides_built_in_tool=True	Tool.OverridesBuiltInTool = true	CopilotToolOptions { OverridesBuiltInTool = true }	.with_overrides_built_in_tool(true)
Typed arg deserialization	invocation.getArgumentsAs(Class<T>)	Handler receives typed args: TArgs	Handler receives typed Pydantic model	Generic T via JSON round-trip	Method params via AIFunctionFactory reflection	serde_json::from_value(inv.arguments)
Raw map access	invocation.getArguments()	invocation.arguments: unknown	invocation.arguments: Any	inv.Arguments map[string]any	via context	inv.arguments: Value
ToolSet builder	new ToolSet().addCustom().addBuiltIn()	new ToolSet().addCustom().addBuiltIn()	ToolSet().add_custom().add_builtin()	NewToolSet().AddCustom().AddBuiltIn()	new ToolSet().AddCustom().AddBuiltIn()	ToolSet::new().add_custom().add_builtin()

All features tested in this PR already have consistent equivalents in every other SDK. No new APIs are being introduced that would require changes to other language implementations.

Minor Observations (not cross-SDK issues)

1. grepOverrideTool handler is never invoked in the snapshot: The test registers ToolDefinition.createOverride("grep", ...) and includes it in setTools(...), but test/snapshots/tools/low_level_tool_definition.yaml only replays set_current_phase and search_items being called — the grep override handler never executes during the test run. This means createOverride usage is exercised at the registration level, but the handler path itself isn't end-to-end tested. Consider either:

   • Adding a second prompt/conversation to the snapshot that triggers grep, or
   • Noting in a comment that the grep tool is registered to verify schema/registration, not handler invocation.

2. Planning files should be removed before merge: The directory 1682-java-tool-ergonomics-prompts-remove-before-merge/ is explicitly called out in the PR description as needing removal, and these files remain in the current commits.

3. PR is still marked as draft — flagging in case this review was triggered prematurely.

Overall the test is a good addition — it provides concrete coverage of the low-level tool definition ergonomics in Java and parallels the existing tool E2E tests in Go (tools_e2e_test.go tests OverridesBuiltInTool) and other SDKs.

Generated by SDK Consistency Review Agent for issue #1692 · sonnet46 3.2M · ◷