Update docs

Author: dlarocque

docs-devsite/ai.md

@@ -136,8 +136,8 @@ The Firebase AI Web SDK.
 |  [ToolConfig](./ai.toolconfig.md#toolconfig_interface) | Tool config. This config is shared for all tools provided in the request. |
 |  [URLContext](./ai.urlcontext.md#urlcontext_interface) | Specifies the URL Context configuration. |
 |  [URLContextMetadata](./ai.urlcontextmetadata.md#urlcontextmetadata_interface) | Metadata related to [URLContextTool](./ai.urlcontexttool.md#urlcontexttool_interface)<!-- -->. |
-|  [URLContextTool](./ai.urlcontexttool.md#urlcontexttool_interface) | A tool that allows you to provide additional context to the models in the form of URLs. By including URLs in your request, the Gemini model will access the content from those pages to inform and enhance its response. |
-|  [URLMetadata](./ai.urlmetadata.md#urlmetadata_interface) | Metadata for a URL that was used to provide context to the Gemini model. |
+|  [URLContextTool](./ai.urlcontexttool.md#urlcontexttool_interface) | 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. |
+|  [URLMetadata](./ai.urlmetadata.md#urlmetadata_interface) | Metadata for a single URL retrieved by the [URLContextTool](./ai.urlcontexttool.md#urlcontexttool_interface) tool. |
 |  [UsageMetadata](./ai.usagemetadata.md#usagemetadata_interface) | Usage metadata about a [GenerateContentResponse](./ai.generatecontentresponse.md#generatecontentresponse_interface)<!-- -->. |
 |  [VideoMetadata](./ai.videometadata.md#videometadata_interface) | Describes the input video content. |
 |  [VoiceConfig](./ai.voiceconfig.md#voiceconfig_interface) | <b><i>(Public Preview)</i></b> Configuration for the voice to used in speech synthesis. |
@@ -762,6 +762,8 @@ SchemaType: {
 
 The status of a URL retrieval.
 
+<b>URL\_RETRIEVAL\_STATUS\_UNSPECIFIED:</b> Unspecified retrieval status. <br/> <b>URL\_RETRIEVAL\_STATUS\_SUCCESS:</b> The URL retrieval was successful. <br/> <b>URL\_RETRIEVAL\_STATUS\_ERROR:</b> The URL retrieval failed. <br/> <b>URL\_RETRIEVAL\_STATUS\_PAYWALL:</b> The URL retrieval failed because the content is behind a paywall. <br/> <b>URL\_RETRIEVAL\_STATUS\_UNSAFE:</b> The URL retrieval failed because the content is unsafe. <br/>
+
 <b>Signature:</b>
 
 ```typescript
@@ -1070,7 +1072,7 @@ export type TypedSchema = IntegerSchema | NumberSchema | StringSchema | BooleanS
 
 The status of a URL retrieval.
 
-<b>URL\_RETRIEVAL\_STATUS\_UNSPECIFIED:</b> Unspecified retrieval status. <br/> <b>URL\_RETRIEVAL\_STATUS\_SUCCESS:</b> The URL retrieval was successful. <br/> <b>URL\_RETRIEVAL\_STATUS\_ERROR:</b> The URL retrieval failed due to an error. <br/> <b>URL\_RETRIEVAL\_STATUS\_PAYWALL:</b> The URL retrieval failed because the content is behind a paywall. <br/> <b>URL\_RETRIEVAL\_STATUS\_UNSAFE:</b> The URL retrieval failed because the content is unsafe. <br/>
+<b>URL\_RETRIEVAL\_STATUS\_UNSPECIFIED:</b> Unspecified retrieval status. <br/> <b>URL\_RETRIEVAL\_STATUS\_SUCCESS:</b> The URL retrieval was successful. <br/> <b>URL\_RETRIEVAL\_STATUS\_ERROR:</b> The URL retrieval failed. <br/> <b>URL\_RETRIEVAL\_STATUS\_PAYWALL:</b> The URL retrieval failed because the content is behind a paywall. <br/> <b>URL\_RETRIEVAL\_STATUS\_UNSAFE:</b> The URL retrieval failed because the content is unsafe. <br/>
 
 <b>Signature:</b>
 

docs-devsite/ai.urlcontext.md

@@ -12,8 +12,6 @@ https://github.com/firebase/firebase-js-sdk
 # URLContext interface
 Specifies the URL Context configuration.
 
-Currently, this is an empty object, but it's reserved for future configuration.
-
 <b>Signature:</b>
 
 ```typescript

docs-devsite/ai.urlcontextmetadata.md

@@ -22,11 +22,11 @@ export interface URLContextMetadata
 
 |  Property | Type | Description |
 |  --- | --- | --- |
-|  [urlMetadata](./ai.urlcontextmetadata.md#urlcontextmetadataurlmetadata) | [URLMetadata](./ai.urlmetadata.md#urlmetadata_interface)<!-- -->\[\] | List of URL metadata were used to provide context to the Gemini model. |
+|  [urlMetadata](./ai.urlcontextmetadata.md#urlcontextmetadataurlmetadata) | [URLMetadata](./ai.urlmetadata.md#urlmetadata_interface)<!-- -->\[\] | List of URL metadata used to provide context to the Gemini model. |
 
 ## URLContextMetadata.urlMetadata
 
-List of URL metadata were used to provide context to the Gemini model.
+List of URL metadata used to provide context to the Gemini model.
 
 <b>Signature:</b>
 

docs-devsite/ai.urlcontexttool.md

@@ -10,7 +10,7 @@ https://github.com/firebase/firebase-js-sdk
 {% endcomment %}
 
 # URLContextTool interface
-A tool that allows you to provide additional context to the models in the form of URLs. By including URLs in your request, the Gemini model will access the content from those pages to inform and enhance its response.
+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.
 
 <b>Signature:</b>
 

docs-devsite/ai.urlmetadata.md

@@ -10,7 +10,7 @@ https://github.com/firebase/firebase-js-sdk
 {% endcomment %}
 
 # URLMetadata interface
-Metadata for a URL that was used to provide context to the Gemini model.
+Metadata for a single URL retrieved by the [URLContextTool](./ai.urlcontexttool.md#urlcontexttool_interface) tool.
 
 <b>Signature:</b>
 

docs-devsite/ai.usagemetadata.md

@@ -27,8 +27,8 @@ export interface UsageMetadata
 |  [promptTokenCount](./ai.usagemetadata.md#usagemetadataprompttokencount) | number |  |
 |  [promptTokensDetails](./ai.usagemetadata.md#usagemetadataprompttokensdetails) | [ModalityTokenCount](./ai.modalitytokencount.md#modalitytokencount_interface)<!-- -->\[\] |  |
 |  [thoughtsTokenCount](./ai.usagemetadata.md#usagemetadatathoughtstokencount) | number | The number of tokens used by the model's internal "thinking" process. |
-|  [toolUsePromptTokenCount](./ai.usagemetadata.md#usagemetadatatooluseprompttokencount) | number | The number of tokens in the results from tool executions, which are provided back to the model as input. |
-|  [toolUsePromptTokensDetails](./ai.usagemetadata.md#usagemetadatatooluseprompttokensdetails) | [ModalityTokenCount](./ai.modalitytokencount.md#modalitytokencount_interface)<!-- -->\[\] | A list of tokens used by tools whose usage was triggered from a prompt, broken down by modality. |
+|  [toolUsePromptTokenCount](./ai.usagemetadata.md#usagemetadatatooluseprompttokencount) | number | The number of tokens used by tools. |
+|  [toolUsePromptTokensDetails](./ai.usagemetadata.md#usagemetadatatooluseprompttokensdetails) | [ModalityTokenCount](./ai.modalitytokencount.md#modalitytokencount_interface)<!-- -->\[\] | A list of tokens used by tools, broken down by modality. |
 |  [totalTokenCount](./ai.usagemetadata.md#usagemetadatatotaltokencount) | number |  |
 
 ## UsageMetadata.candidatesTokenCount
@@ -75,7 +75,7 @@ thoughtsTokenCount?: number;
 
 ## UsageMetadata.toolUsePromptTokenCount
 
-The number of tokens in the results from tool executions, which are provided back to the model as input.
+The number of tokens used by tools.
 
 <b>Signature:</b>
 
@@ -85,7 +85,7 @@ toolUsePromptTokenCount?: number;
 
 ## UsageMetadata.toolUsePromptTokensDetails
 
-A list of tokens used by tools whose usage was triggered from a prompt, broken down by modality.
+A list of tokens used by tools, broken down by modality.
 
 <b>Signature:</b>
 

packages/ai/src/requests/stream-reader.ts

@@ -198,8 +198,13 @@ export function aggregateResponses(
         // make sure that we don't overwrite the first value urlContextMetadata object with undefined.
         // FIXME: What happens if we receive a second, valid urlContextMetadata object?
         const urlContextMetadata = candidate.urlContextMetadata as unknown;
-        if (typeof urlContextMetadata === 'object' && urlContextMetadata !== null && Object.keys(urlContextMetadata).length > 0) {
-          aggregatedResponse.candidates[i].urlContextMetadata = urlContextMetadata as URLContextMetadata;
+        if (
+          typeof urlContextMetadata === 'object' &&
+          urlContextMetadata !== null &&
+          Object.keys(urlContextMetadata).length > 0
+        ) {
+          aggregatedResponse.candidates[i].urlContextMetadata =
+            urlContextMetadata as URLContextMetadata;
         }
 
         /**

packages/ai/src/types/requests.ts

@@ -321,9 +321,9 @@ export interface CodeExecutionTool {
 export interface GoogleSearch {}
 
 /**
- * A tool that allows you to provide additional context to the models in the form of URLs.
- * By including URLs in your request, the Gemini model will access the content from those pages
- * to inform and enhance its response.
+ * 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
  */
@@ -337,8 +337,6 @@ export interface URLContextTool {
 /**
  * Specifies the URL Context configuration.
  *
- * @remarks Currently, this is an empty object, but it's reserved for future configuration.
- *
  * @public
  */
 export interface URLContext {}

packages/ai/src/types/responses.ts

@@ -117,14 +117,13 @@ export interface UsageMetadata {
   thoughtsTokenCount?: number;
   totalTokenCount: number;
   /**
-   * The number of tokens in the results from tool executions, which are provided back to the
-   * model as input.
+   * The number of tokens used by tools.
    */
   toolUsePromptTokenCount?: number;
   promptTokensDetails?: ModalityTokenCount[];
   candidatesTokensDetails?: ModalityTokenCount[];
   /**
-   * A list of tokens used by tools whose usage was triggered from a prompt, broken down by modality.
+   * A list of tokens used by tools, broken down by modality.
    */
   toolUsePromptTokensDetails?: ModalityTokenCount[];
 }
@@ -366,13 +365,13 @@ export interface Segment {
  */
 export interface URLContextMetadata {
   /**
-   * List of URL metadata were used to provide context to the Gemini model.
+   * List of URL metadata used to provide context to the Gemini model.
    */
   urlMetadata: URLMetadata[];
 }
 
 /**
- * Metadata for a URL that was used to provide context to the Gemini model.
+ * Metadata for a single URL retrieved by the {@link URLContextTool} tool.
  *
  * @public
  */
@@ -390,6 +389,18 @@ export interface URLMetadata {
 /**
  * The status of a URL retrieval.
  *
+ * @remarks
+ * <b>URL_RETRIEVAL_STATUS_UNSPECIFIED:</b> Unspecified retrieval status.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_SUCCESS:</b> The URL retrieval was successful.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_ERROR:</b> The URL retrieval failed.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_PAYWALL:</b> The URL retrieval failed because the content is behind a paywall.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_UNSAFE:</b> The URL retrieval failed because the content is unsafe.
+ * <br/>
+ *
  * @public
  */
 export const URLRetrievalStatus = {
@@ -402,7 +413,7 @@ export const URLRetrievalStatus = {
    */
   URL_RETRIEVAL_STATUS_SUCCESS: 'URL_RETRIEVAL_STATUS_SUCCESS',
   /**
-   * The URL retrieval failed due to an error.
+   * The URL retrieval failed.
    */
   URL_RETRIEVAL_STATUS_ERROR: 'URL_RETRIEVAL_STATUS_ERROR',
   /**
@@ -423,7 +434,7 @@ export const URLRetrievalStatus = {
  * <br/>
  * <b>URL_RETRIEVAL_STATUS_SUCCESS:</b> The URL retrieval was successful.
  * <br/>
- * <b>URL_RETRIEVAL_STATUS_ERROR:</b> The URL retrieval failed due to an error.
+ * <b>URL_RETRIEVAL_STATUS_ERROR:</b> The URL retrieval failed.
  * <br/>
  * <b>URL_RETRIEVAL_STATUS_PAYWALL:</b> The URL retrieval failed because the content is behind a paywall.
  * <br/>