docs: [OpenAI] Minor fix - version of latest tool features in javadoc (#443)

* Improve javadoc and corrected version

* minor fix

* Formatting

* formatting

* Paraphrase

---------

Co-authored-by: Roshin Rajan Panackal <[email protected]>
Co-authored-by: SAP Cloud SDK Bot <[email protected]>

Author: rpanackal

foundation-models/openai/src/main/java/com/sap/ai/sdk/foundationmodels/openai/OpenAiChatCompletionRequest.java

@@ -123,13 +123,18 @@ public class OpenAiChatCompletionRequest {
   /** Response format for the completion. */
   @Nullable CreateChatCompletionRequestAllOfResponseFormat responseFormat;
 
-  /** List of tools that the model may invoke during the completion. */
+  /**
+   * Tools the model may invoke during chat completion (metadata only).
+   *
+   * <p>Use {@link #withToolsExecutable} for registering executable tools.
+   */
   @Nullable List<ChatCompletionTool> tools;
 
   /**
-   * List of tools that are executable at runtime of the application.
+   * Tools the model may invoke during chat completion that are also executable at application
+   * runtime.
    *
-   * @since 1.7.0
+   * @since 1.8.0
    */
   @Getter(value = AccessLevel.PACKAGE)
   @Nullable

foundation-models/openai/src/main/java/com/sap/ai/sdk/foundationmodels/openai/OpenAiChatCompletionResponse.java

@@ -108,6 +108,7 @@ public OpenAiAssistantMessage getMessage() {
    *
    * @return the list of tool messages that were serialized for the computed results. Empty list if
    *     no tools were called.
+   * @since 1.8.0
    */
   @Nonnull
   public List<OpenAiToolMessage> executeTools() {

foundation-models/openai/src/main/java/com/sap/ai/sdk/foundationmodels/openai/OpenAiTool.java

@@ -39,7 +39,7 @@
  * function's request structure.
  *
  * @see <a href="https://platform.openai.com/docs/guides/gpt/function-calling"/>OpenAI Function
- * @since 1.7.0
+ * @since 1.8.0
  */
 @Slf4j
 @Beta
@@ -157,8 +157,9 @@ private static SchemaGenerator createSchemaGenerator() {
   }
 
   /**
-   * Executes the given tool calls with the provided tools and returns the results as a list of
-   * {@link OpenAiToolMessage} containing execution results encoded as JSON string.
+   * Executes each tool call found in the specified assistant message using the provided tools.
+   * Returns a list of {@link OpenAiToolMessage} objects, each containing the execution result
+   * encoded as a JSON string.
    *
    * @param tools the list of tools to execute
    * @param msg the assistant message containing a list of tool calls with arguments
@@ -179,8 +180,8 @@ static List<OpenAiToolMessage> execute(
   }
 
   /**
-   * Executes the given tool calls with the provided tools and returns the results as a list of
-   * {@link OpenAiToolMessage} containing execution results encoded as JSON string.
+   * Executes each tool call found in the specified assistant message using the provided tools.
+   * Returns a map that links each executed tool call to its corresponding result.
    *
    * @param tools the list of tools to execute
    * @param msg the assistant message containing a list of tool calls with arguments