diff --git a/docs/docs/tools/describe.md b/docs/docs/tools/describe.md
index 50d927a8..62a7eb34 100644
--- a/docs/docs/tools/describe.md
+++ b/docs/docs/tools/describe.md
@@ -18,7 +18,7 @@ After ~30 seconds, the tool will generate a description for the PR:
 
 ![Describe New](https://codium.ai/images/pr_agent/describe_new.png){width=512}
 
-If you want to edit [configurations](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L46), add the relevant ones to the command:
+If you want to edit [configurations](#configuration-options), add the relevant ones to the command:
 ```
 /describe --pr_description.some_config1=... --pr_description.some_config2=...
 ```
@@ -36,10 +36,9 @@ pr_commands = [
 [pr_description]
 publish_labels = ...
 ...
-
 ```
 
-- The `pr_commands` lists commands that will be executed on every PR.
+- The `pr_commands` lists commands that will be executed automatically when a PR is opened.
 - The `[pr_description]` section contains the configurations for the `describe` tool you want to edit.
 
 
diff --git a/docs/docs/tools/review.md b/docs/docs/tools/review.md
index c5681bb4..9ba34b69 100644
--- a/docs/docs/tools/review.md
+++ b/docs/docs/tools/review.md
@@ -4,22 +4,47 @@ The tool can be triggered automatically every time a new PR is [opened](../usage
 ```
 /review
 ```
-For example:
+
+## Example usage
+
+### Manual invocation
+
+Invoke the tool manually by commenting `/review` on any PR:
 
 ![review comment](https://codium.ai/images/pr_agent/review_comment.png){width=512}
 
+After ~30 seconds, the tool will generate a review for the PR:
+
 ![review](https://codium.ai/images/pr_agent/review3.png){width=512}
 
+If you want to edit [configurations](#configuration-options), add the relevant ones to the command:
+```
+/review --pr_reviewer.some_config1=... --pr_reviewer.some_config2=...
+```
+
+### Automatic invocation
+
+To run the `review` automatically when a PR is opened, define in a [configuration file](https://pr-agent-docs.codium.ai/usage-guide/configuration_options/#wiki-configuration-file):
+```
+[github_app]
+pr_commands = [
+    "/review",
+    ...
+]
+
+[pr_reviewer]
+publish_labels = ...
+...
+```
+
+- The `pr_commands` lists commands that will be executed automatically when a PR is opened.
+- The `[pr_reviewer]` section contains the configurations for the `review` tool you want to edit.
+
 
 ## Configuration options
 
 ### General configurations
 
-To edit [configurations](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L19)  related to the review tool (`pr_reviewer` section), use the following template:
-```
-/review --pr_reviewer.some_config1=... --pr_reviewer.some_config2=...
-```
-
 !!! example "General options"
     - `num_code_suggestions`: number of code suggestions provided by the 'review' tool. For manual comments, default is 4. For [PR-Agent app](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L142) auto tools, default is 0, meaning no code suggestions will be provided by the review tool, unless you manually edit `pr_commands`.
     - `inline_code_comments`: if set to true, the tool will publish the code suggestions as comments on the code diff. Default is false.