diff --git a/README.md b/README.md
index dc3fc99d..597a1583 100644
--- a/README.md
+++ b/README.md
@@ -23,7 +23,7 @@ CodiumAI `PR-Agent` is an open-source tool aiming to help developers review pull
 \
 ‣ **Question Answering (`/ask ...`)**: Answering [free-text questions](https://github.com/Codium-ai/pr-agent/pull/229#issuecomment-1695021332) about the PR.
 \
-‣ **Code Suggestions (`/improve`)**: [Committable code suggestions](https://github.com/Codium-ai/pr-agent/pull/229#discussion_r1306919276) for improving the PR.
+‣ **Code Suggestions ([`/improve`](./docs/IMPROVE.md))**: Committable code suggestions for improving the PR.
 \
 ‣ **Update Changelog (`/update_changelog`)**: Automatically updating the CHANGELOG.md file with the [PR changes](https://github.com/Codium-ai/pr-agent/pull/168#discussion_r1282077645).
 \
diff --git a/docs/DESCRIBE.md b/docs/DESCRIBE.md
index cb9d726c..1d09e71d 100644
--- a/docs/DESCRIBE.md
+++ b/docs/DESCRIBE.md
@@ -5,7 +5,7 @@ It can ba invoked manually by commenting on any PR:
 ```
 /describe
 ```
-
+For example:
 
 <img src=./../pics/describe_comment.png width="768">
 
diff --git a/docs/IMPROVE.md b/docs/IMPROVE.md
new file mode 100644
index 00000000..748fdaf8
--- /dev/null
+++ b/docs/IMPROVE.md
@@ -0,0 +1,34 @@
+# Describe Tool
+
+The `improve` tool scans the PR code changes, and automatically generate committable suggestions for improving the PR code.
+It can ba invoked manually by commenting on any PR:
+```
+/improve
+```
+For example:
+
+<kbd><img src=./../pics/improve_comment.png width="768"></kbd>
+<kbd><img src=./../pics/improve.png width="768"><kbd>
+
+The `improve` tool can also be triggered automatically every time a new PR is opened. See examples for automatic triggers for [GitHub App](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#github-app-automatic-tools) and [GitHub Action](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#working-with-github-action)
+
+An extended mode, which does not involve PR Compression and provides more comprehensive suggestions, can be invoked by commenting on any PR:
+```
+/improve --extended
+```
+Note that the extended mode divides the PR code changes into chunks, due to token limits, where each chunk is handled separately (multiple calls to GPT-4).
+Hence, the total number of suggestions is proportional to the number of chunks, i.e. the size of the PR.
+
+### Configuration options
+
+Under the section 'pr_code_suggestions', the [configuration file](./../pr_agent/settings/configuration.toml#L40) contains options to customize the 'improve' tool:
+
+- `num_code_suggestions`: number of code suggestions provided by the 'improve' tool. Default is 4.
+- `extra_instructions`: Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ...".
+- `rank_suggestions`: if set to true, the tool will rank the suggestions, based on importance. Default is false.
+
+#### params for '/improve --extended' mode
+- `num_code_suggestions_per_chunk`: number of code suggestions provided by the 'improve' tool, per chunk. Default is 8.
+- `rank_extended_suggestions`: if set to true, the tool will rank the suggestions, based on importance. Default is true.
+- `max_number_of_calls`: maximum number of chunks. Default is 5.
+- `final_clip_factor`: factor to remove suggestions with low confidence. Default is 0.9.
\ No newline at end of file
diff --git a/docs/REVIEW.md b/docs/REVIEW.md
index 3ca854b3..bf4c3e98 100644
--- a/docs/REVIEW.md
+++ b/docs/REVIEW.md
@@ -5,7 +5,7 @@ It can ba invoked manually by commenting on any PR:
 ```
 /review
 ```
-
+For example:
 
 <kbd><img src=./../pics/review_comment.png width="768"></kbd>
 <kbd><img src=./../pics/describe.png width="768"><kbd>
diff --git a/docs/SIMILAR_ISSUE.md b/docs/SIMILAR_ISSUE.md
index 2dc2ce7e..954109c6 100644
--- a/docs/SIMILAR_ISSUE.md
+++ b/docs/SIMILAR_ISSUE.md
@@ -4,6 +4,7 @@ It can ba invoked manually by commenting on any PR:
 ```
 /similar_issue
 ```
+For example:
 
 <img src=./../pics/similar_issue_original_issue.png width="768">
 <img src=./../pics/similar_issue_comment.png width="768">
diff --git a/pics/improve.png b/pics/improve.png
new file mode 100644
index 00000000..1442a63b
Binary files /dev/null and b/pics/improve.png differ
diff --git a/pics/improve_comment.png b/pics/improve_comment.png
new file mode 100644
index 00000000..3438a4ba
Binary files /dev/null and b/pics/improve_comment.png differ