docs: reorganize tool calling documentation and add observability details

- Update Observability section with details about tool calling observability support
- Move "Migrating to ToolCallback API" guide from Tool Calling section to Upgrade Notes
- Update Observability section with details about tool calling observability support

Related to #3230

Signed-off-by: Christian Tzolov <[email protected]>

Author: tzolov

spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc

@@ -51,6 +51,7 @@
 ***** xref:api/embeddings/vertexai-embeddings-text.adoc[Text Embedding]
 ***** xref:api/embeddings/vertexai-embeddings-multimodal.adoc[Multimodal Embedding]
 **** xref:api/embeddings/zhipuai-embeddings.adoc[ZhiPu AI]
+
 *** xref:api/imageclient.adoc[Image Models]
 **** xref:api/image/azure-openai-image.adoc[Azure OpenAI]
 **** xref:api/image/openai-image.adoc[OpenAI]
@@ -73,7 +74,6 @@
 ** xref:api/chat-memory.adoc[Chat Memory]
 
 ** xref:api/tools.adoc[Tool Calling]
-*** xref:api/tools-migration.adoc[Migrating to ToolCallback API]
 
 ** xref:api/mcp/mcp-overview.adoc[Model Context Protocol (MCP)]
 *** xref:api/mcp/mcp-client-boot-starter-docs.adoc[MCP Client Boot Starters]
@@ -122,3 +122,4 @@
 // * xref:contribution-guidelines.adoc[Contribution Guidelines]
 
 * xref:upgrade-notes.adoc[]
+** xref:api/tools-migration.adoc[Migrating FunctionCallback to ToolCallback API]

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/tools.adoc

@@ -14,6 +14,8 @@ Spring AI provides convenient APIs to define tools, resolve tool call requests f
 
 NOTE: Check the xref:api/chat/comparison.adoc[Chat Model Comparisons] to see which AI models support tool calling invocation.
 
+TIP: Follow the guide to migrate from the deprecated xref:api/tools-migration.adoc[FunctionCallback to ToolCallback API].
+
 == Quick Start
 
 Let's see how to start using tool calling in Spring AI. We'll implement two simple tools: one for information retrieval and one for taking action. The information retrieval tool will be used to get the current date and time in the user's time zone. The action tool will be used to set an alarm for a specified time.
@@ -1253,7 +1255,9 @@ The `ToolCallbackResolver` is used internally by the `ToolCallingManager` to res
 
 == Observability
 
-Instrumentation for the tool calling is on its way. For now, you can use the logging feature to track the tool calling operations.
+Tool calling includes observability support with spring.ai.tool observations that measure completion time and propagate tracing information. See xref:observability/index.adoc#_tool_calling[Tool Calling Observability].
+
+Optionally, Spring AI can export tool call arguments and results as span attributes, disabled by default for sensitivity reasons. Details: xref:observability/index.adoc#_tool_call_arguments_and_result_data[Tool Call Arguments and Result Data].
 
 === Logging