diff --git a/docs/docs/tools/improve.md b/docs/docs/tools/improve.md
index b2203b7a..c473ba7b 100644
--- a/docs/docs/tools/improve.md
+++ b/docs/docs/tools/improve.md
@@ -157,6 +157,13 @@ Tips for writing an effective `best_practices.md` file:
   - AI models may not process effectively very long documents
   - Long files tend to contain generic guidelines already known to AI
 
+To control the number of best practices suggestions generated by the `improve` tool, give the following configuration:
+
+```toml
+[best_practices]
+num_best_practice_suggestions = 2
+```
+
 #### Local and global best practices
 
 By default, Qodo Merge will look for a local `best_practices.md` in the root of the relevant local repo.
@@ -238,6 +245,11 @@ extra_instructions = ""
 max_patterns = 5                   
 ```
 
+### Multiple best practices sources
+
+The `improve` tool will combine best practices from all available sources - global configuration, local configuration, and auto-generated files - to provide you with comprehensive recommendations.
+
+
 ### Combining 'extra instructions' and 'best practices'
 
 > `💎 feature`