diff --git a/Microsoft.Azure.Cosmos/src/CosmosClient.cs b/Microsoft.Azure.Cosmos/src/CosmosClient.cs
index d4fe7dcb9b..d622e9ddcb 100644
--- a/Microsoft.Azure.Cosmos/src/CosmosClient.cs
+++ b/Microsoft.Azure.Cosmos/src/CosmosClient.cs
@@ -92,6 +92,9 @@ namespace Microsoft.Azure.Cosmos
/// ]]>
///
///
+ ///
+ /// The returned not-initialized reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls
+ ///
///
///
/// Performance Tips
@@ -179,6 +182,9 @@ protected CosmosClient()
/// ]]>
///
///
+ ///
+ /// The returned reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls.
+ ///
///
///
/// Performance Tips
@@ -221,6 +227,9 @@ public CosmosClient(
/// ]]>
///
///
+ ///
+ /// The returned reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls.
+ ///
///
///
/// Performance Tips
@@ -274,7 +283,10 @@ public CosmosClient(
///
/// Performance Tips
/// Diagnose and troubleshoot issues
- /// AzureKeyCredential enables changing/updating master-key/ResourceToken whle CosmosClient is still in use.
+ ///
+ /// AzureKeyCredential enables changing/updating master-key/ResourceToken whle CosmosClient is still in use.
+ /// The returned reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls.
+ ///
public CosmosClient(
string accountEndpoint,
AzureKeyCredential authKeyOrResourceTokenCredential,
@@ -292,6 +304,9 @@ public CosmosClient(
/// of the application which enables efficient connection management and performance. Please refer to the
/// performance guide.
///
+ ///
+ /// The returned reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls.
+ ///
/// The cosmos service endpoint to use.
/// The token to provide AAD token for authorization.
/// (Optional) client options
@@ -368,6 +383,9 @@ internal CosmosClient(
/// ]]>
///
///
+ ///
+ /// The returned reference doesn't guarantee credentials or connectivity validations because initialization doesn't make any network calls.
+ ///
public static async Task CreateAndInitializeAsync(string accountEndpoint,
string authKeyOrResourceToken,
IReadOnlyList<(string databaseId, string containerId)> containers,
diff --git a/Microsoft.Azure.Cosmos/src/Fluent/CosmosClientBuilder.cs b/Microsoft.Azure.Cosmos/src/Fluent/CosmosClientBuilder.cs
index 692d5b498a..8b72bfffa4 100644
--- a/Microsoft.Azure.Cosmos/src/Fluent/CosmosClientBuilder.cs
+++ b/Microsoft.Azure.Cosmos/src/Fluent/CosmosClientBuilder.cs
@@ -167,9 +167,13 @@ public CosmosClientBuilder(
///
/// A method to create the cosmos client
+ /// CosmosClient is thread-safe. Its recommended to maintain a single instance of CosmosClient per lifetime
+ /// of the application which enables efficient connection management and performance. Please refer to the
+ /// performance guide.
///
///
/// Setting this property after sending any request won't have any effect.
+ /// The returned reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls.
///
/// An instance of .
public CosmosClient Build()
@@ -191,6 +195,11 @@ public CosmosClient Build()
///
/// A method to create the cosmos client and initialize the provided containers.
+ /// In addition to that it initializes the client with containers provided i.e The SDK warms up the caches and
+ /// connections before the first call to the service is made. Use this to obtain lower latency while startup of your application.
+ /// CosmosClient is thread-safe. Its recommended to maintain a single instance of CosmosClient per lifetime
+ /// of the application which enables efficient connection management and performance. Please refer to the
+ /// performance guide.
///
/// Containers to be initialized identified by it's database name and container name.
/// (Optional) Cancellation Token
@@ -214,9 +223,13 @@ public Task BuildAndInitializeAsync(IReadOnlyList<(string database
///
/// A method to create the cosmos client
+ /// CosmosClient is thread-safe. Its recommended to maintain a single instance of CosmosClient per lifetime
+ /// of the application which enables efficient connection management and performance. Please refer to the
+ /// performance guide.
///
///
/// Setting this property after sending any request won't have any effect.
+ /// The returned reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls.
///
internal virtual CosmosClient Build(DocumentClient documentClient)
{