diff --git a/README.md b/README.md
index ef223413..82583b26 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@ Making pull requests less painful with an AI agent
CodiumAI `PR-Agent` is an open-source tool aiming to help developers review pull requests faster and more efficiently. It automatically analyzes the pull request and can provide several types of commands:
-‣ **Auto Description (`/describe`)**: Automatically generating [PR description](./docs/DESCRIBE.md) - title, type, summary, code walkthrough and labels.
+‣ **Auto Description [(`/describe`)](./docs/DESCRIBE.md)**: Automatically generating PR description - title, type, summary, code walkthrough and labels.
\
‣ **Auto Review (`/review`)**: [Adjustable feedback](https://github.com/Codium-ai/pr-agent/pull/229#issuecomment-1695022908) about the PR main theme, type, relevant tests, security issues, score, and various suggestions for the PR content.
\
@@ -27,7 +27,7 @@ CodiumAI `PR-Agent` is an open-source tool aiming to help developers review pull
\
‣ **Update Changelog (`/update_changelog`)**: Automatically updating the CHANGELOG.md file with the [PR changes](https://github.com/Codium-ai/pr-agent/pull/168#discussion_r1282077645).
\
-‣ **Find similar issue (`/similar_issue`)**: Automatically retrieves and presents [similar issues](https://github.com/Alibaba-MIIL/ASL/issues/107).
+‣ **Find similar issue [(`/similar_issue`)](./docs/SIMILAR_ISSUE.md)**: Automatically retrieves and presents similar issues
See the [usage guide](./Usage.md) for instructions how to run the different tools from [CLI](./Usage.md#working-from-a-local-repo-cli), or by [online usage](./Usage.md#online-usage), as well as additional details on optional commands and configurations.
diff --git a/Usage.md b/Usage.md
index 7f6fcb9b..f316ddaa 100644
--- a/Usage.md
+++ b/Usage.md
@@ -261,26 +261,4 @@ And use the following settings (you have to replace the values) in .secrets.toml
[azure_devops]
org = "https://dev.azure.com/YOUR_ORGANIZATION/"
pat = "YOUR_PAT_TOKEN"
-```
-
-#### Similar issue tool
-
-[Example usage](https://github.com/Alibaba-MIIL/ASL/issues/107)
-
-
-
-To enable usage of the '**similar issue**' tool, you need to set the following keys in `.secrets.toml` (or in the relevant environment variables):
-```
-[pinecone]
-api_key = "..."
-environment = "..."
-```
-These parameters can be obtained by registering to [Pinecone](https://app.pinecone.io/?sessionType=signup/).
-
-- To invoke the 'similar issue' tool from **CLI**, run:
-`python3 cli.py --issue_url=... similar_issue`
-
-- To invoke the 'similar' issue tool via online usage, [comment](https://github.com/Codium-ai/pr-agent/issues/178#issuecomment-1716934893) on a PR:
-`/similar_issue`
-
-- You can also enable the 'similar issue' tool to run automatically when a new issue is opened, by adding it to the [pr_commands list in the github_app section](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L66)
+```
\ No newline at end of file
diff --git a/docs/DESCRIBE.md b/docs/DESCRIBE.md
index 01bdb589..91bb1653 100644
--- a/docs/DESCRIBE.md
+++ b/docs/DESCRIBE.md
@@ -1,4 +1,4 @@
-## Describe
+# Describe Tool
The `describe` tool scans the PR code changes, and automatically generates PR description - title, type, summary, code walkthrough and labels.
It can ba invoked manually by commenting on any PR:
@@ -15,7 +15,7 @@ The `describe` tool can also be triggered automatically every time a new PR is o
### Configuration options
-Under the section 'pr_description', the [configuration file](pr_agent/settings/configuration.toml) contains options to customize the 'describe' tool:
+Under the section 'pr_description', the [configuration file](./../pr_agent/settings/configuration.toml) contains options to customize the 'describe' tool:
- `publish_labels`: if set to true, the tool will publish the labels to the PR. Default is true.
diff --git a/docs/SIMILAR_ISSUE.md b/docs/SIMILAR_ISSUE.md
new file mode 100644
index 00000000..a8289a35
--- /dev/null
+++ b/docs/SIMILAR_ISSUE.md
@@ -0,0 +1,29 @@
+# Similar Issue Tool
+The similar issue tool retrieves the most similar issues to the current issue:
+```
+/similar issue
+```
+
+
+
+
+
+Note that to perform retrieval, the `similar_issue` tool indexes all the repo previous issues (once).
+
+To enable usage of the '**similar issue**' tool, you need to set the following keys in `.secrets.toml` (or in the relevant environment variables):
+```
+[pinecone]
+api_key = "..."
+environment = "..."
+```
+These parameters can be obtained by registering to [Pinecone](https://app.pinecone.io/?sessionType=signup/).
+
+
+### How to use:
+- To invoke the 'similar issue' tool from **CLI**, run:
+`python3 cli.py --issue_url=... similar_issue`
+
+- To invoke the 'similar' issue tool via online usage, [comment](https://github.com/Codium-ai/pr-agent/issues/178#issuecomment-1716934893) on a PR:
+`/similar_issue`
+
+- You can also enable the 'similar issue' tool to run automatically when a new issue is opened, by adding it to the [pr_commands list in the github_app section](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L66)
diff --git a/pics/similar_issue.png b/pics/similar_issue.png
new file mode 100644
index 00000000..923fe97a
Binary files /dev/null and b/pics/similar_issue.png differ
diff --git a/pics/similar_issue_comment.png b/pics/similar_issue_comment.png
new file mode 100644
index 00000000..0e8d2efc
Binary files /dev/null and b/pics/similar_issue_comment.png differ
diff --git a/pics/similar_issue_original_issue.png b/pics/similar_issue_original_issue.png
new file mode 100644
index 00000000..b133a872
Binary files /dev/null and b/pics/similar_issue_original_issue.png differ
diff --git a/pics/similar_issue_tool.png b/pics/similar_issue_tool.png
deleted file mode 100644
index 4ec51c81..00000000
Binary files a/pics/similar_issue_tool.png and /dev/null differ