s

docs/DESCRIBE.md

@@ -1,6 +1,15 @@
 # Describe Tool
+## Table of Contents
+- [Overview](#overview)
+  - [Handle custom labels from the Repo's labels page :gem:](#handle-custom-labels-from-the-repos-labels-page-gem)
+  - [Configuration options](#configuration-options)
+  - [Markers template](#markers-template)
+- [Usage Tips](#usage-tips)
+  - [Automation](#automation)
+  - [Custom labels](#custom-labels)
 
-The `describe` tool scans the PR code changes, and can automatically generate PR description - title, type, summary, walkthrough and labels.
+## Overview
+The `describe` tool scans the PR code changes, and generates a description for the PR - title, type, summary, walkthrough and labels.
 
 The tool can be triggered automatically every time a new PR is [opened](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#github-app-automatic-tools), or it can be invoked manually by commenting on any PR:
 ```
@@ -81,22 +90,25 @@ The marker `pr_agent:type` will be replaced with the PR type, `pr_agent:summary`
 
 <kbd><img src=https://codium.ai/images/pr_agent/describe_markers_after.png width="768"></kbd>
 
-##### Configuration params:
+**Configuration params:**
 
 - `use_description_markers`: if set to true, the tool will use markers template. It replaces every marker of the form `pr_agent:marker_name` with the relevant content. Default is false.
 - `include_generated_by_header`: if set to true, the tool will add a dedicated header: 'Generated by PR Agent at ...' to any automatic content. Default is true.
 
 
 ## Usage Tips
+### Automation
 - When you first install the app, the [default mode](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#github-app-automatic-tools) for the describe tool is:
 ```
-pr_commands = ["describe --pr_description.add_original_user_description=true --pr_description.keep_original_user_title=true", ...]
+pr_commands = ["describe --pr_description.add_original_user_description=true 
+                         --pr_description.keep_original_user_title=true", ...]
 ```
 meaning the `describe` tool will run automatically on every PR, will keep the original title, and will add the original user description above the generated description. <br> This default is quite conservative, and strikes a good balance between automation and control:
 If you want more automation, just give the PR a title, and the tool will auto-write a full description; If you want more control, you can add a detailed description, and the tool will add the complementary description below it.
 - For maximal automation, you can change the default mode to:
 ```
-pr_commands = ["describe --pr_description.add_original_user_description=false --pr_description.keep_original_user_title=true", ...]
+pr_commands = ["describe --pr_description.add_original_user_description=false 
+                         --pr_description.keep_original_user_title=true", ...]
 ```
 so the title will be auto-generated as well.
 - Markers are an alternative way to control the generated description, to give maximal control to the user. If you set:
@@ -110,3 +122,17 @@ the tool will replace every marker of the form `pr_agent:marker_name` in the PR
 
 Note that when markers are enabled, if the original PR description does not contain any markers, the tool will not alter the description at all.
 
+### Custom labels
+The default labels of the describe tool are quite generic, since they are meant to be used in any repo. The default labels are: [`Bug fix`, `Tests`, `Enhancement`, `Documentation`, `Other`].
+
+If you specify custom labels in the repo's labels page, you can get tailored labels for your repo and use cases.
+Examples for custom labels:
+- `Main topic:performence` -  pr_agent:The main topic of this PR is performance
+- `New endpoint` -  pr_agent:A new endpoint was added in this PR
+- `SQL query` -  pr_agent:A new SQL query was added in this PR
+- `Dockerfile changes` - pr_agent:The PR contains changes in the Dockerfile
+- ...
+
+The list above is eclectic, and aims to give an idea of different possibilities. Define the custom labels that are relevant for your repo and use cases.
+Note that Labels are not mutually exclusive, so you can add multiple label categories.
+Make sure to provide detailed well-phrased description for each label, so the tool will know when to suggest it.