diff --git a/CONFIGURATION.md b/CONFIGURATION.md
index 320ddedf..162a51d3 100644
--- a/CONFIGURATION.md
+++ b/CONFIGURATION.md
@@ -2,18 +2,33 @@
 
 The different tools and sub-tools used by CodiumAI PR-Agent are adjustable via the **[configuration file](pr_agent/settings/configuration.toml)**
 
+Options that are available in the configuration file can be specified at run time when calling actions. Two examples:
+```
+- /review --pr_reviewer.extra_instructions="focus on the file: ..."
+- /describe --pr_description.add_original_user_description=false -pr_description.extra_instructions="make sure to mention: ..."
+```
+
 ### Working from CLI
 When running from source (CLI), your local configuration file will be initially used.
 
-Example for invoking the 'review' tools via the CLI: 
+Examples for invoking the different tools via the CLI:
 
 ```
-python cli.py --pr-url=<pr_url>  review
+- **Review**:       python cli.py --pr_url=<pr_url>  review
+- **Describe**:     python cli.py --pr_url=<pr_url>  describe
+- **Improve**:      python cli.py --pr_url=<pr_url>  improve
+- **Ask**:          python cli.py --pr_url=<pr_url>  ask "Write me a poem about this PR"
+- **Reflect**:      python cli.py --pr_url=<pr_url>  reflect
+- **Update Changelog**:      python cli.py --pr_url=<pr_url>  update_changelog
 ```
-In addition to general configurations, the 'review' tool will use parameters from the `[pr_reviewer]` section (every tool has a dedicated section in the configuration file).
 
-Note that you can print results locally, without publishing them, by setting in `configuration.toml`:
+"<pr_url>" is the url of the relevant PR (for example: https://github.com/Codium-ai/pr-agent/pull/50).
 
+Notes:
+
+(1) In addition to general configurations, each tool has its own configurations. For example, the 'review' tool will use parameters from the `[pr_reviewer]` section.
+
+(2) You can print results locally, without publishing them, by setting in `configuration.toml`:
 ```
 [config]
 publish_output=true
diff --git a/README.md b/README.md
index c236c8fa..cbf13970 100644
--- a/README.md
+++ b/README.md
@@ -118,29 +118,21 @@ CodiumAI `PR-Agent` is an open-source tool aiming to help developers review pull
 |       | Multiple models support |   :white_check_mark:    |   :white_check_mark:    |   :white_check_mark:       | :white_check_mark: |   :white_check_mark:       |
 |       | Incremental PR Review |   :white_check_mark:    |      |      |      |      |
 
-Examples for invoking the different tools via the CLI:
-- **Review**:       python cli.py --pr_url=<pr_url>  review
-- **Describe**:     python cli.py --pr_url=<pr_url>  describe
-- **Improve**:      python cli.py --pr_url=<pr_url>  improve
-- **Ask**:          python cli.py --pr_url=<pr_url>  ask "Write me a poem about this PR"
-- **Reflect**:      python cli.py --pr_url=<pr_url>  reflect
-- **Update Changelog**:      python cli.py --pr_url=<pr_url>  update_changelog
-
-"<pr_url>" is the url of the relevant PR (for example: https://github.com/Codium-ai/pr-agent/pull/50).
-
-In the [configuration](./CONFIGURATION.md) file you can select your git provider (GitHub, Gitlab, Bitbucket), and further configure the different tools.
-Options that are available in the configuration file can be specified at run time when calling actions. Two examples:
-- /review --pr_reviewer.extra_instructions="focus on the file: ..."
-- /describe --pr_description.add_original_user_description=false -pr_description.extra_instructions="make sure to mention: ..."
+Review the [configuration](./CONFIGURATION.md) section for instruction how to use the different tools,  select the relevant git provider (GitHub, Gitlab, Bitbucket,...), and adjust the configuration file to your needs.
 
 ## Try it now
 
 Try GPT-4 powered PR-Agent on your public GitHub repository for free. Just mention `@CodiumAI-Agent` and add the desired command in any PR comment! The agent will generate a response based on your command.
+For example, add a comment:
+```
+@CodiumAI-Agent /review
+```
+And the agent will respond with a review of your PR
 
 ![Review generation process](https://www.codium.ai/images/demo-2.gif)
 
-To set up your own PR-Agent, see the [Installation](#installation) section
 
+To set up your own PR-Agent, see the [Installation](#installation) section below.
 ---
 
 ## Installation