address reviewer feedback

Author: guimachiavelli

docs.json

@@ -165,17 +165,23 @@
                 "group": "AI-powered search",
                 "pages": [
                   "learn/ai_powered_search/getting_started_with_ai_search",
-                  "learn/ai_powered_search/conversational_search_with_chat",
                   "learn/ai_powered_search/configure_rest_embedder",
                   "learn/ai_powered_search/document_template_best_practices",
                   "learn/ai_powered_search/image_search_with_user_provided_embeddings",
                   "learn/ai_powered_search/search_with_user_provided_embeddings",
                   "learn/ai_powered_search/retrieve_related_search_results",
-                  "learn/ai_powered_search/chat_tooling_reference",
                   "learn/ai_powered_search/choose_an_embedder",
                   "learn/ai_powered_search/difference_full_text_ai_search"
                 ]
               },
+              {
+                "group": "Conversational search",
+                "pages": [
+                  "learn/ai_powered_search/getting_started_with_chat",
+                  "learn/ai_powered_search/chat_tooling_reference",
+                  "learn/ai_powered_search/conversational_search"
+                ]
+              },
               {
                 "group": "Self-hosted",
                 "pages": [

guides/ai/getting_started_with_chat.mdx

@@ -179,12 +179,10 @@ curl -N \
   }'
 ```
 
-Take particular note of the `tools` array. These settings ensure Meilisearch includes the relevant information in its database in the chat queries:
+Take particular note of the `tools` array. These settings are optional, but greatly improve user experience:
 
-- **`_meiliSearchProgress`**: Shows users what searches are being performed
-- **`_meiliSearchSources`**: Provides the actual documents used to generate responses
-
-If you do not include any tools in your request, the chat will only use the LLM's general knowledge and will not search your actual Meilisearch indexes.
+- **`_meiliSearchProgress`**: shows users what searches are being performed
+- **`_meiliSearchSources`**: displays the actual documents used to generate responses
 
 ## Build a chat interface using the OpenAI SDK
 
@@ -263,7 +261,7 @@ import OpenAI from 'openai';
 
 const client = new OpenAI({
   baseURL: 'http://localhost:7700/chats/my-assistant',
-  apiKey: 'OPENAI_API_KEY',
+  apiKey: 'MEILISEARCH_KEY',
 });
 
 try {
@@ -287,7 +285,7 @@ from openai import OpenAI
 
 client = OpenAI(
     base_url="http://localhost:7700/chats/my-assistant",
-    api_key="OPENAI_API_KEY"
+    api_key="MEILISEARCH_KEY"
 )
 
 try:

learn/ai_powered_search/chat_tooling_reference.md

@@ -6,17 +6,30 @@ description: An exhaustive reference of special chat tools supported by Meilisea
 When creating your conversational search agent, you may be able to extend the model's capabilities with a number of tools. This page lists Meilisearch-specific tools that may improve user experience.
 
 <Note>
-These special tools are handled internally by Meilisearch and are not forwarded to the LLM provider. They serve as a communication mechanism between Meilisearch and your application to provide enhanced user experience features.
+This is an experimental feature. Use the Meilisearch Cloud UI or the experimental features endpoint to activate it:
+
+```sh
+curl \
+  -X PATCH 'MEILISEARCH_URL/experimental-features/' \
+  -H 'Content-Type: application/json' \
+  --data-binary '{
+    "chatCompletions": true
+  }'
+```
 </Note>
 
 ## Meilisearch chat tools
 
 For the best user experience, configure all following tools.
 
-2. **Handle progress updates** by displaying search status to users during streaming
-3. **Append conversation messages** as requested to maintain context for future requests
-4. **Display source documents** to users for transparency and verification
-5. **Use the `call_id`** to associate progress updates with their corresponding source results
+1. **Handle progress updates** by displaying search status to users during streaming
+2. **Append conversation messages** as requested to maintain context for future requests
+3. **Display source documents** to users for transparency and verification
+4. **Use `call_id`** to associate progress updates with their corresponding source results
+
+<Note>
+These special tools are handled internally by Meilisearch and are not forwarded to the LLM provider. They serve as a communication mechanism between Meilisearch and your application to provide enhanced user experience features.
+</Note>
 
 ### `_meiliSearchProgress`
 

…arch/conversational_search_with_chat.mdx …powered_search/conversational_search.mdxlearn/ai_powered_search/conversational_search_with_chat.mdx renamed to learn/ai_powered_search/conversational_search.mdx learn/ai_powered_search/conversational_search_with_chat.mdx renamed to learn/ai_powered_search/conversational_search.mdx

@@ -1,5 +1,5 @@
 ---
-title: Conversational search with chat
+title: Conversational search
 sidebarTitle: Conversational search
 description: Learn how to implement AI-powered conversational search using Meilisearch's chat feature
 ---
@@ -17,8 +17,6 @@ curl \
     "chatCompletions": true
   }'
 ```
-
-When you enable the chat route for the first time, Meilisearch creates a new API key named "Default Chat API Key".
 </Note>
 
 ## What is conversational search?
@@ -50,12 +48,14 @@ This approach bridges the gap between traditional search and modern AI experienc
 ## When to use chat completions vs traditional search
 
 ### Use conversational search when:
+
 - Users need direct answers to specific questions
 - Content is informational (documentation, knowledge bases, FAQs)
 - Users benefit from follow-up questions
 - Natural language interaction improves user experience
 
 ### Use traditional search when:
+
 - Users need to browse multiple options
 - Results require comparison (e-commerce products, listings)
 - Exact matching is critical
@@ -68,7 +68,7 @@ The chat completions feature implements a complete Retrieval Augmented Generatio
 1. **Query understanding**: automatically transforms questions into search parameters
 2. **Hybrid retrieval**: combines keyword and semantic search for better relevancy
 3. **Answer generation**: uses your chosen LLM to generate responses
-4. **Context management**: maintains conversation history automatically
+4. **Context management**: maintains conversation history by constantly pushing the full conversation to the dedicated tool
 
 ### Alternative: MCP integration
 

reference/api/chats.mdx

@@ -19,15 +19,13 @@ curl \
     "chatCompletions": true
   }'
 ```
-
-When you enable the chat route for the first time, Meilisearch creates a new API key named "Default Chat API Key".
 </Note>
 
 ## Authorization
 
 When working with a secure Meilisearch instance, Use an API key with access to both the `search` and `chatCompletions` actions, such as the default chat API key.
 
-Chat queries only search indexes its API key can access. The default chat API key has access to all indexes.
+Chat queries only search indexes its API key can access. The default chat API key has access to all indexes. To limit chat access to specific indexes, you must either create a new key, or [generate a tenant token](/learn/security/generate_tenant_token_sdk) from the default chat API key.
 
 ## Chat workspace object
 
@@ -154,7 +152,7 @@ Retrieve the current settings for a chat workspace.
 
 #### Response: `200 OK`
 
-Returns the settings object without the `apiKey` field.
+Returns the settings object. For security reasons, the `apiKey` field is obfuscated.
 
 ```json
 {
@@ -172,7 +170,7 @@ Returns the settings object without the `apiKey` field.
 ```bash cURL
 curl \
   -X GET 'http://localhost:7700/chats/WORKSPACE_UID/settings' \
-  -H 'Authorization: Bearer MASTER_KEY'
+  -H 'Authorization: Bearer MEILISEARCH_KEY'
 ```
 
 </CodeGroup>
@@ -209,7 +207,7 @@ If the workspace does not exist, querying this endpoint will create it.
 ```json
 {
   "source": "openAi",
-  "apiKey": "OPEN_AI_SECURITY_KEY",
+  "apiKey": "OPEN_AI_API_KEY",
   "prompts": {
     "system": "DEFAULT CHAT INSTRUCTIONS"
   }
@@ -229,7 +227,7 @@ Returns the updated settings object. `apiKey` is write-only and will not be retu
 ```bash openAi
 curl \
   -X PATCH 'http://localhost:7700/chats/customer-support/settings' \
-  -H 'Authorization: Bearer MASTER_KEY' \
+  -H 'Authorization: Bearer MEILISEARCH_KEY' \
   -H 'Content-Type: application/json' \
   --data-binary '{
     "source": "openAi",
@@ -243,7 +241,7 @@ curl \
 ```bash azureOpenAi
 curl \
   -X PATCH 'http://localhost:7700/chats/customer-support/settings' \
-  -H 'Authorization: Bearer MASTER_KEY' \
+  -H 'Authorization: Bearer MEILISEARCH_KEY' \
   -H 'Content-Type: application/json' \
   --data-binary '{
     "source": "azureOpenAi",
@@ -261,7 +259,7 @@ curl \
 ```bash mistral
 curl \
   -X PATCH 'http://localhost:7700/chats/customer-support/settings' \
-  -H 'Authorization: Bearer MASTER_KEY' \
+  -H 'Authorization: Bearer MEILISEARCH_KEY' \
   -H 'Content-Type: application/json' \
   --data-binary '{
     "source": "mistral",
@@ -275,7 +273,7 @@ curl \
 ```bash gemini
 curl \
   -X PATCH 'http://localhost:7700/chats/customer-support/settings' \
-  -H 'Authorization: Bearer MASTER_KEY' \
+  -H 'Authorization: Bearer MEILISEARCH_KEY' \
   -H 'Content-Type: application/json' \
   --data-binary '{
     "source": "gemini",
@@ -289,7 +287,7 @@ curl \
 ```bash vLlm
 curl \
   -X PATCH 'http://localhost:7700/chats/customer-support/settings' \
-  -H 'Authorization: Bearer MASTER_KEY' \
+  -H 'Authorization: Bearer MEILISEARCH_KEY' \
   -H 'Content-Type: application/json' \
   --data-binary '{
     "source": "vLlm",
@@ -334,7 +332,7 @@ Returns the settings object without the `apiKey` field.
 ```bash cURL
 curl \
   -X DELETE 'http://localhost:7700/chats/customer-support/settings' \
-  -H 'Authorization: Bearer MASTER_KEY'
+  -H 'Authorization: Bearer MEILISEARCH_KEY'
 ```
 
 </CodeGroup>