[AI] API docs for URLContext (#15341)

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: paulb777

FirebaseAI/Sources/GenerateContentResponse.swift

@@ -26,7 +26,7 @@ public struct GenerateContentResponse: Sendable {
     /// The total number of tokens across the generated response candidates.
     public let candidatesTokenCount: Int
 
-    /// The number of tokens present in tool-use prompt(s).
+    /// The number of tokens used by tools.
     public let toolUsePromptTokenCount: Int
 
     /// The number of tokens used by the model's internal "thinking" process.
@@ -42,13 +42,14 @@ public struct GenerateContentResponse: Sendable {
     /// The total number of tokens in both the request and response.
     public let totalTokenCount: Int
 
-    /// The breakdown, by modality, of how many tokens are consumed by the prompt
+    /// The breakdown, by modality, of how many tokens are consumed by the prompt.
     public let promptTokensDetails: [ModalityTokenCount]
 
     /// The breakdown, by modality, of how many tokens are consumed by the candidates
     public let candidatesTokensDetails: [ModalityTokenCount]
 
-    /// List of modalities that were processed for tool-use request inputs.
+    /// The breakdown, by modality, of how many tokens were consumed by the tools used to process
+    /// the request.
     public let toolUsePromptTokensDetails: [ModalityTokenCount]
   }
 

FirebaseAI/Sources/Tool.swift

@@ -131,6 +131,11 @@ public struct Tool: Sendable {
     return self.init(googleSearch: googleSearch)
   }
 
+  /// Creates a tool that allows you to provide additional context to the models in the form of
+  /// public web URLs.
+  ///
+  /// By including URLs in your request, the Gemini model will access the content from those pages
+  /// to inform and enhance its response.
   public static func urlContext() -> Tool {
     return self.init(urlContext: URLContext())
   }

FirebaseAI/Sources/Types/Public/URLContextMetadata.swift

@@ -15,7 +15,7 @@
 /// Metadata related to the ``Tool/urlContext()`` tool.
 @available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
 public struct URLContextMetadata: Sendable, Hashable {
-  /// List of URL context.
+  /// List of URL metadata used to provide context to the Gemini model.
   public let urlMetadata: [URLMetadata]
 }
 

FirebaseAI/Sources/Types/Public/URLMetadata.swift

@@ -14,7 +14,7 @@
 
 import Foundation
 
-/// Context of a single URL retrieval.
+/// Metadata for a single URL retrieved by the ``Tool/urlContext()`` tool.
 @available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
 public struct URLMetadata: Sendable, Hashable {
   /// Status of the URL retrieval.
@@ -27,19 +27,19 @@ public struct URLMetadata: Sendable, Hashable {
       case unsafe = "URL_RETRIEVAL_STATUS_UNSAFE"
     }
 
-    /// Internal only - default value.
+    /// Internal only - Unspecified retrieval status.
     static let unspecified = URLRetrievalStatus(kind: .unspecified)
 
-    /// URL retrieval succeeded.
+    /// The URL retrieval was successful.
     public static let success = URLRetrievalStatus(kind: .success)
 
-    /// URL retrieval failed due to an error.
+    /// The URL retrieval failed.
     public static let error = URLRetrievalStatus(kind: .error)
 
-    /// URL retrieval failed failed because the content is behind paywall.
+    /// The URL retrieval failed because the content is behind a paywall.
     public static let paywall = URLRetrievalStatus(kind: .paywall)
 
-    /// URL retrieval failed because the content is unsafe.
+    /// The URL retrieval failed because the content is unsafe.
     public static let unsafe = URLRetrievalStatus(kind: .unsafe)
 
     /// Returns the raw string representation of the `URLRetrievalStatus` value.
@@ -49,7 +49,7 @@ public struct URLMetadata: Sendable, Hashable {
       AILog.MessageCode.urlMetadataUnrecognizedURLRetrievalStatus
   }
 
-  /// The URL retrieved by the ``Tool/urlContext()`` tool.
+  /// The retrieved URL.
   public let retrievedURL: URL?
 
   /// The status of the URL retrieval.