## Example usage

docs/docs/tools/analyze.md

@@ -9,6 +9,7 @@ It can be invoked manually by commenting on any PR:
 ```
 
 ## Example usage
+
 An example result:
 
 ![Analyze 1](https://codium.ai/images/pr_agent/analyze_1.png){width=750}

docs/docs/tools/ci_feedback.md

@@ -8,6 +8,8 @@ The tool analyzes the failed checks and provides several feedbacks:
 - Failure summary
 - Relevant error logs
 
+## Example usage
+
 ![Failed Check 1](https://www.codium.ai/images/pr_agent/failed_check1.png){width=768}
 
 →

docs/docs/tools/custom_labels.md

@@ -5,7 +5,8 @@ It can be invoked manually by commenting on any PR:
 ```
 /generate_labels
 ```
-For example:
+
+## Example usage
 
 If we wish to add detect changes to SQL queries in a given PR, we can add the following custom label along with its description:
 

docs/docs/tools/custom_suggestions.md

@@ -1,13 +1,18 @@
 ## Overview
-The `custom_suggestions` tool scans the PR code changes, and automatically generates custom suggestions for improving the PR code.
-It shares similarities with the `improve` tool, but with one main difference: the `custom_suggestions` tool will only propose suggestions that follow specific guidelines defined by the prompt in: `pr_custom_suggestions.prompt` configuration.
+The `custom_suggestions` tool scans the PR code changes, and automatically generates suggestions for improving the PR code.
+It shares similarities with the `improve` tool, but with one main difference: the `custom_suggestions` tool will **only propose suggestions that follow specific guidelines defined by the prompt** in: `pr_custom_suggestions.prompt` configuration.
 
 The tool can be triggered [automatically](../usage-guide/automations_and_usage.md#github-app-automatic-tools-when-a-new-pr-is-opened) every time a new PR is opened, or can be invoked manually by commenting on a PR.
 
 When commenting, use the following template:
 
 ```
-/custom_suggestions --pr_custom_suggestions.prompt="The suggestions should focus only on the following:\n-...\n-...\n-..."
+/custom_suggestions --pr_custom_suggestions.prompt="
+The suggestions should focus only on the following:
+- ...
+- ...
+
+"
 ```
 
 With a [configuration file](../usage-guide/automations_and_usage.md#github-app), use the following template:
@@ -18,17 +23,16 @@ prompt="""\
 The suggestions should focus only on the following:
 -...
 -...
--...
+
 """
 ```
-Using a configuration file is recommended, since it allows to use multi-line instructions.
 
-Don't forget - with this tool, you are the prompter. Be specific, clear, and concise in the instructions. Specify relevant aspects that you want the model to focus on. \
+Remember - with this tool, you are the prompter. Be specific, clear, and concise in the instructions. Specify relevant aspects that you want the model to focus on. \
 You might benefit from several trial-and-error iterations, until you get the correct prompt for your use case.
 
 ## Example usage
 
-Here is an example of a possible prompt:
+Here is an example of a possible prompt, defined in the configuration file:
 ```
 [pr_custom_suggestions]
 prompt="""\
@@ -39,12 +43,13 @@ The suggestions should focus only on the following:
 """
 ``` 
 
-The instructions above are just an example. We want to emphasize that the prompt should be specific and clear, and be tailored to the needs of your project.
+(The instructions above are just an example. We want to emphasize that the prompt should be specific and clear, and be tailored to the needs of your project)
 
 Results obtained with the prompt above:
 
-![Custom suggestions prompt](https://codium.ai/images/pr_agent/custom_suggestions_prompt.png){width=512}
-→
+[//]: # (![Custom suggestions prompt](https://codium.ai/images/pr_agent/custom_suggestions_prompt.png){width=512})
+
+[//]: # (→)
 ![Custom suggestions results](https://codium.ai/images/pr_agent/custom_suggestions_result.png){width=768}
 
 ## Configuration options

docs/docs/tools/documentation.md

@@ -5,20 +5,29 @@ It can be invoked manually by commenting on any PR:
 ```
 /add_docs
 ```
-For example:
+
+## Example usage
+
+Invoke the tool manually by commenting `/add_docs` on any PR:
 
 ![Docs command](https://codium.ai/images/pr_agent/docs_command.png){width=768}
 
+The tool will generate documentation for all the components that changed in the PR:
+
 ![Docs component](https://codium.ai/images/pr_agent/docs_components.png){width=768}
 
 ![Docs single component](https://codium.ai/images/pr_agent/docs_single_component.png){width=768}
 
+You can state a name of a specific component in the PR to get documentation only for that component:
+```
+/add_docs component_name
+```
+
 ## Configuration options
  - `docs_style`: The exact style of the documentation (for python docstring). you can choose between: `google`, `numpy`, `sphinx`, `restructuredtext`, `plain`. Default is `sphinx`.
  - `extra_instructions`: Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ...".
 
 **Notes**
 
 - Language that are currently fully supported: Python, Java, C++, JavaScript, TypeScript, C#.
-- For languages that are not fully supported, the tool will suggest documentation only for new components in the PR.
-- A previous version of the tool, that offered support only for new components, was deprecated.
+- This tool can also be triggered interactively by using the [`analyze`](./analyze.md) tool.

docs/docs/tools/improve.md

@@ -56,7 +56,7 @@ num_code_suggestions = ...
  - `num_code_suggestions`: number of code suggestions provided by the 'improve' tool. Default is 4 for CLI, 0 for auto tools.
  - `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.
- - `summarize`: if set to true, the tool will display the suggestions in a single comment. Default is true.
+ - `commitable_code_suggestions`: if set to true, the tool will display the suggestions as commitable code comments. Default is false.
  - `persistent_comment`: if set to true, the improve comment will be persistent, meaning that every new improve request will edit the previous one. Default is false.
  - `enable_help_text`: if set to true, the tool will display a help text in the comment. Default is true.
 

docs/docs/tools/improve_component.md

@@ -8,14 +8,19 @@ it can be invoked manually by commenting on any PR:
 To get a list of the components that changed in the PR and choose the relevant component interactively, use the [`analyze`](./analyze.md) tool.
 
 
-Example result:
+## Example usage
+
+Invoke the tool manually by commenting `/improve_component` on any PR:
 
 ![improve_component1](https://codium.ai/images/pr_agent/improve_component1.png){width=768}
 
+The tool will generate code suggestions for the selected component (if no component is stated, it will generate code suggestions for the largest component):
+
 ![improve_component2](https://codium.ai/images/pr_agent/improve_component2.png){width=768}
 
 **Notes**
 - Language that are currently supported by the tool: Python, Java, C++, JavaScript, TypeScript, C#.
+- This tool can also be triggered interactively by using the [`analyze`](./analyze.md) tool.
 
 ## Configuration options
 - `num_code_suggestions`: number of code suggestions to provide. Default is 4

docs/docs/tools/similar_issues.md

@@ -4,7 +4,9 @@ It can be invoked manually by commenting on any PR:
 ```
 /similar_issue
 ```
-For example:
+
+
+## Example usage
 
 ![similar_issue_original_issue](https://codium.ai/images/pr_agent/similar_issue_original_issue.png){width=768}
 

docs/docs/tools/test.md

@@ -7,17 +7,23 @@ It can be invoked manually by commenting on any PR:
 where 'component_name' is the name of a specific component in the PR.
 To get a list of the components that changed in the PR and choose the relevant component interactively, use the [`analyze`](./analyze.md) tool.
 
+## Example usage
 
-An example [result](https://github.com/Codium-ai/pr-agent/pull/598#issuecomment-1913679429):
+Invoke the tool manually by commenting `/test` on any PR:
 
 ![test1](https://codium.ai/images/pr_agent/test1.png){width=704}
 
+The tool will generate tests for the selected component (if no component is stated, it will generate tests for largest component):
+
 ![test2](https://codium.ai/images/pr_agent/test2.png){width=768}
 
 ![test3](https://codium.ai/images/pr_agent/test3.png){width=768}
 
+(Example taken from [here](https://github.com/Codium-ai/pr-agent/pull/598#issuecomment-1913679429)):
+
 **Notes**
 - Language that are currently supported by the tool: Python, Java, C++, JavaScript, TypeScript, C#.
+- This tool can also be triggered interactively by using the [`analyze`](./analyze.md) tool.
 
 
 ## Configuration options

docs/docs/tools/update_changelog.md

@@ -4,15 +4,16 @@ It can be invoked manually by commenting on any PR:
 ```
 /update_changelog
 ```
-For example:
+
+## Example usage
 
 ![update_changelog_comment](https://codium.ai/images/pr_agent/update_changelog_comment.png){width=768}
 
 ![update_changelog](https://codium.ai/images/pr_agent/update_changelog.png){width=768}
 
 ## Configuration options
 
-Under the section 'pr_update_changelog', the [configuration file](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L50) contains options to customize the 'update changelog' tool:
+Under the section `pr_update_changelog`, the [configuration file](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L50) contains options to customize the 'update changelog' tool:
 
 - `push_changelog_changes`: whether to push the changes to CHANGELOG.md, or just print them. Default is false (print only).
 - `extra_instructions`: Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ...