Add breaking changes to 1.0 M8 upgrade notes regarding chatclient tool calling

Author: markpollack

spring-ai-docs/src/main/antora/modules/ROOT/pages/upgrade-notes.adoc

@@ -25,30 +25,80 @@ For details, refer to:
 - xref:upgrade-notes.adoc#common-package-changes[Common Package Changes]
 - xref:upgrade-notes.adoc#common-module-structure[Common Module Structure]
 
-[[automating-upgrading-using-ai]]
-=== Automating upgrading using AI
+[[upgrading-to-1-0-0-m8]]
+== Upgrading to 1.0.0-M8
 
-You can automate the upgrade process to 1.0.0-SNAPSHOT using the Claude Code CLI tool with a provided prompt. The prompt will guide the AI to perform the following tasks:
+You can automate the upgrade process to 1.0.0-M8 using an OpenRewrite recipe.
+This recipe helps apply many of the necessary code changes for this version.
+Find the recipe and usage instructions at https://github.com/arconia-io/arconia-migrations/blob/main/docs/spring-ai.md[Arconia Spring AI Migrations].
 
-1. Update the Spring AI BOM version to 1.0.0-SNAPSHOT
-2. Ensure all required repositories exist in your build configuration
-3. Update Spring AI artifact IDs according to the new naming patterns
+=== Breaking Changes
+When upgrading from Spring AI 1.0 M7 to 1.0 M8, users who previously registered tool callbacks are encountering breaking changes that cause tool calling functionality to silently fail. This is specifically impacting code that used the deprecated `tools()` method.
 
-To use this automation:
+==== Example
 
-1. Download the https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview[Claude Code CLI tool]
-2. Copy the prompt from the https://github.com/spring-projects/spring-ai/blob/main/src/prompts/update-to-snapshot.txt[update-to-snapshot.txt] file
-3. Paste the prompt into the Claude Code CLI
-4. The AI will analyze your project and make the necessary changes
+Here's an example of code that worked in M7 but no longer functions as expected in M8:
 
-This approach can save time and reduce the chance of errors when upgrading multiple projects or complex codebases.
+[source,java]
+----
+// Old code in M7 - no longer works correctly in M8
+chatClient.prompt("What day is tomorrow?")
+    .tools(toolCallback)
+    .call()
+    .content();
+----
+
+==== How to Adapt Your Code
+
+To fix this issue when upgrading to M8, you need to update your code to use the new `toolCallbacks()` method:
+
+[source,java]
+----
+// Updated code for M8
+chatClient.prompt("What day is tomorrow?")
+    .toolCallbacks(toolCallback)
+    .call()
+    .content();
+----
+
+==== Why This Change Was Made
+
+The Spring AI team renamed the overloaded `tools()` methods to improve clarity and prevent ambiguity in method dispatching. The previous API design led to confusion when the Java compiler needed to select between multiple overloaded methods based on parameter types.
+
+==== Method Mapping from M7 to M8
+
+Here's how the old methods map to their new counterparts:
+
+1. `tools(String... toolNames)` → `toolNames(String... toolNames)`
+- Use when referring to tools registered elsewhere (e.g., via `@Bean` with `@Description`)
+
+2. `tools(ToolCallback... toolCallbacks)` → `toolCallbacks(ToolCallback... toolCallbacks)`
+- Use for inline tool callback registration
+
+3. `tools(List<ToolCallback> toolCallbacks)` → `toolCallbacks(List<ToolCallback> toolCallbacks)`
+- Use when you have a collection of tool callbacks
+
+4. `tools(ToolCallbackProvider... toolCallbackProviders)` → `toolCallbacks(ToolCallbackProvider... toolCallbackProviders)`
+- Use for objects implementing the `ToolCallbackProvider` interface
+
+5. `tools(Object... toolObjects)` remains unchanged
+- Use only for objects with methods annotated with `@Tool`
+
+==== Improved Error Handling
+
+In the https://github.com/spring-projects/spring-ai/pull/2964[this PR now merged (spring-projects/spring-ai#2964)], the `tools(Object... toolObjects)` method will now throw an exception when no `@Tool` methods are found on the provided objects, rather than silently failing. This helps developers identify migration issues immediately.
+
+==== Migration Summary
+
+If you're upgrading from M7 to M8:
+
+1. Replace all calls to `.tools(toolCallback)` with `.toolCallbacks(toolCallback)`
+2. Replace all calls to `.tools(toolCallbackProvider)` with `.toolCallbacks(toolCallbackProvider)`
+3. Replace all calls to `.tools("toolName")` with `.toolNames("toolName")`
+
+These changes will ensure your tool calling functionality continues to work correctly after upgrading to Spring AI 1.0 M8.
 
-[[upgrading-to-1-0-0-m8]]
-== Upgrading to 1.0.0-M8
 
-You can automate the upgrade process to 1.0.0-M8 using an OpenRewrite recipe.
-This recipe helps apply many of the necessary code changes for this version.
-Find the recipe and usage instructions at https://github.com/arconia-io/arconia-migrations/blob/main/docs/spring-ai.md[Arconia Spring AI Migrations].
 
 === Chat Client