diff --git a/docs/DESCRIBE.md b/docs/DESCRIBE.md
index b08f563c..da33c344 100644
--- a/docs/DESCRIBE.md
+++ b/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`
-##### 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.
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.
\ No newline at end of file