diff --git a/docs/src/modules/java/pages/agents.adoc b/docs/src/modules/java/pages/agents.adoc
index 18c358d93..0c216ff30 100644
--- a/docs/src/modules/java/pages/agents.adoc
+++ b/docs/src/modules/java/pages/agents.adoc
@@ -73,9 +73,9 @@ Each model provider may have different settings. Available model providers are:
 
 * `openai` - link:_attachments/api/akka/javasdk/agent/ModelProvider.OpenAi.html[`ModelProvider.OpenAi`]
 * `anthropic` - link:_attachments/api/akka/javasdk/agent/ModelProvider.Anthropic.html[`ModelProvider.Anthropic`]
-* `googleai-gemini` - Google's Gemini
-* `local-ai` - Local LLMs
-* `ollama` - Servers hosting **ollama** models
+* `googleai-gemini` -  link:_attachments/api/akka/javasdk/agent/ModelProvider.GoogleAIGemini.html[`ModelProvider.GoogleAIGemini`]
+* `local-ai` - link:_attachments/api/akka/javasdk/agent/ModelProvider.LocalAI.html[`ModelProvider.LocalAI`]
+* `ollama` - link:_attachments/api/akka/javasdk/agent/ModelProvider.Ollama.html[`ModelProvider.Ollama`]
 
 It is also possible to plug in a custom model by implementing the link:_attachments/api/akka/javasdk/agent/ModelProvider.Custom.html[`ModelProvider.Custom`] interface and use it with `ModelProvider.custom`.
 
@@ -324,13 +324,15 @@ Anything "current" is beyond the capabilities of an LLM, so the model response w
 
 Here's a sample `getWeather` tool function.
 
+
 [source,java]
+.{sample-base-url}/multi-agent/src/main/java/demo/multiagent/application/agents/WeatherAgent.java[WeatherAgent.java]
 ----
-@FunctionTool(description = "Returns the weather forecast for a given city.")
-private String getWeather(@Description("A location or city name.") String location) {
-    return weatherService.getWeather(location);
-}
+include::example$multi-agent/src/main/java/demo/multiagent/application/agents/WeatherAgent.java[tag=weather-tool]
 ----
+<1> Annotate the method with `@FunctionTool` and give a clear description of what it provides.
+<2> Parameters can be clarified with the `@Description` annotation.
+<3> Implementation calls an external weather service.
 
 == Use ComponentClient in an Agent
 
diff --git a/samples/multi-agent/src/main/java/demo/multiagent/application/agents/WeatherAgent.java b/samples/multi-agent/src/main/java/demo/multiagent/application/agents/WeatherAgent.java
index 9b9f00e8a..876029fe0 100644
--- a/samples/multi-agent/src/main/java/demo/multiagent/application/agents/WeatherAgent.java
+++ b/samples/multi-agent/src/main/java/demo/multiagent/application/agents/WeatherAgent.java
@@ -51,17 +51,19 @@ public Agent.Effect<AgentResponse> query(String message) {
   }
 
 
-  @FunctionTool(description = "Returns the weather forecast for a given city.")
+  // tag::weather-tool[]
+  @FunctionTool(description = "Returns the weather forecast for a given city.") // <1>
   private String getWeather(
-      @Description("A location or city name.") String location,
+      @Description("A location or city name.") String location, // <2>
       @Description("Forecast for a given date, in yyyy-MM-dd format. Leave empty to use current date.") String date) {
     var forecastDate = date;
     if (date == null || date.isBlank()) {
       forecastDate = LocalDateTime.now().format(DateTimeFormatter.ISO_LOCAL_DATE);
     }
 
-    return weatherService.getWeather(location, forecastDate);
+    return weatherService.getWeather(location, forecastDate); // <3>
   }
+  // end::weather-tool[]
 
   @FunctionTool(description = "Return current date in yyyy-MM-dd format")
   private String getCurrentDate() {