docs: improve tool descriptions for AI clarity

Enhanced all 9 tool descriptions with:
- Clear priority guidance (USE FIRST, ONLY when, etc.)
- What each tool returns (source code, snippets, structured list, etc.)
- Supported languages for each tool (Go, PHP, Python, HTML)
- When to use search_code vs hybrid_search
- Redirect from search_docs to search_code for code queries

Key improvements:
- search_code: "USE FIRST", "Better than hybrid_search for exploration"
- hybrid_search: "ONLY when you need EXACT matches", "Use when search_code misses"
- list_package_exports: "Returns structured list: symbol names, types, signatures"
- get_code_context: "Any text file" (not just code)
- index_workspace: "USUALLY AUTOMATIC", "Call after git pull/branch switch"

Updated: Go source, README.md, llms.txt, llms-full.txt (3 lists)

Author: doITmagic

README.md

@@ -493,15 +493,15 @@ The `-skip-build` flag skips binary compilation and only updates IDE configurati
 
 | Tool | What it does | When to use |
 | --- | --- | --- |
-| `search_code` | Semantic code search - finds functions, classes, methods by meaning. Returns complete code with file path and line numbers. **Supports Go, PHP, Python.** | **Use FIRST** when exploring unfamiliar code or answering "how does X work?" questions. |
-| `hybrid_search` | Combined keyword + semantic search for exact matches plus context. | When you need **EXACT matches** (variable names, error messages, constants) plus semantic context. |
-| `get_function_details` | Returns **COMPLETE** function/method code with signature, parameters, return types, and full body. | When you know the exact function name and need to see or modify its implementation. |
-| `find_type_definition` | Returns complete class/struct/interface with all fields, methods, and inheritance chain. | When you need to understand a data model or see what methods a type has. |
-| `find_implementations` | Shows all callers and implementations of a function/method/interface. | **Before refactoring** to understand impact, or to find usage examples of an API. |
-| `list_package_exports` | Lists all public functions, classes, types in a package/module. **Works for Go, PHP, Python.** | To explore an unfamiliar package or find the right function to call. |
-| `search_docs` | Semantic search in Markdown documentation (README, guides, API docs). | For project setup, architecture decisions, or usage examples. **Not for code.** |
-| `get_code_context` | Reads specific lines from a file with surrounding context. | When you have file path + line numbers (from search results or errors) and need the actual code. |
-| `index_workspace` | Index/reindex the codebase. **Usually automatic.** | Only if search returns "workspace not indexed" or after major code changes. |
+| `search_code` | Semantic search by MEANING. Returns complete source code with file:line. **Go, PHP, Python, HTML.** | **USE FIRST** for exploration. Better than hybrid_search for general queries. |
+| `hybrid_search` | Keyword + semantic for **EXACT matches**. Returns code with file:line + metadata. **Go, PHP, Python, HTML.** | **ONLY** when you need exact identifiers (variable names, error messages). Use search_code first. |
+| `get_function_details` | Returns **COMPLETE** function source: signature, params, return types, body. **Go, PHP, Python.** | When you know the exact function name and need full implementation. |
+| `find_type_definition` | Returns complete type source with fields, methods, inheritance. **Go, PHP, Python.** | To understand a data model or see what methods a type has. |
+| `find_implementations` | Lists all callers/usages with code snippets + file:line. **Go, PHP, Python.** | **Before refactoring** to understand impact, or to find usage examples. |
+| `list_package_exports` | Returns structured list: symbol names, types, signatures. **Go, PHP, Python.** | To explore unfamiliar packages or find the right function to call. |
+| `search_docs` | Returns doc snippets with file paths. **Markdown only.** | For setup, architecture, examples. **Not for code** - use search_code instead. |
+| `get_code_context` | Returns code snippet with configurable context lines. **Any text file.** | When you have file:line (from search/errors) and need surrounding code. |
+| `index_workspace` | Reindex codebase. **USUALLY AUTOMATIC.** **Go, PHP, Python, HTML.** | Only if "workspace not indexed" error or after git pull/branch switch. |
 
 **All tools require a `file_path` parameter** so that RagCode can determine the correct workspace.
 

internal/tools/find_implementations.go

@@ -38,7 +38,7 @@ func (t *FindImplementationsTool) Name() string {
 }
 
 func (t *FindImplementationsTool) Description() string {
-	return "Find where a function/method/interface is USED - shows all callers and implementations. Use to understand impact before refactoring, or to find examples of how to use an API. Returns code snippets with file locations."
+	return "Find where a function/method/interface is USED - shows all callers and implementations. Use to understand impact before refactoring, or to find usage examples. Returns list of code snippets with file paths and line numbers. Works for Go, PHP, Python."
 }
 
 func (t *FindImplementationsTool) Execute(ctx context.Context, args map[string]interface{}) (string, error) {

internal/tools/find_type_definition.go

@@ -40,7 +40,7 @@ func (t *FindTypeDefinitionTool) Name() string {
 }
 
 func (t *FindTypeDefinitionTool) Description() string {
-	return "Find class/struct/interface definition - returns the complete type with all fields, methods, and inheritance. Use when you need to understand a data model or see what methods a type has. Works for Go structs/interfaces, PHP classes, Python classes."
+	return "Find class/struct/interface definition - returns complete type source code with all fields, methods, and inheritance chain. Use when you need to understand a data model or see what methods a type has. Returns the full type definition ready to read. Works for Go structs/interfaces, PHP classes, Python classes."
 }
 
 func (t *FindTypeDefinitionTool) Execute(ctx context.Context, args map[string]interface{}) (string, error) {

internal/tools/get_code_context.go

@@ -21,7 +21,7 @@ func (t *GetCodeContextTool) Name() string {
 }
 
 func (t *GetCodeContextTool) Description() string {
-	return "Read specific lines from a file with context - use when you have a file path and line numbers (e.g., from search results or error messages) and need to see the actual code. Returns the exact code snippet with surrounding lines."
+	return "Read specific lines from a file with surrounding context - use when you have a file path and line numbers (e.g., from search results or error messages). Returns the exact code snippet with configurable context lines before/after. Works for any text file (Go, PHP, Python, HTML, config files, etc.)."
 }
 
 func (t *GetCodeContextTool) Execute(ctx context.Context, args map[string]interface{}) (string, error) {

internal/tools/get_function_details.go

@@ -40,7 +40,7 @@ func (t *GetFunctionDetailsTool) Name() string {
 }
 
 func (t *GetFunctionDetailsTool) Description() string {
-	return "Get COMPLETE function/method code - returns the full implementation with signature, parameters, return types, and body. Use when you know the exact function name and need to see or modify its code. Works for Go, PHP, Python."
+	return "Get COMPLETE function/method source code - returns full implementation with signature, parameters, return types, and body. Use when you know the exact function name. Returns the entire function ready to read or modify. Works for Go, PHP, Python."
 }
 
 func (t *GetFunctionDetailsTool) Execute(ctx context.Context, args map[string]interface{}) (string, error) {

internal/tools/hybrid_search.go

@@ -39,7 +39,7 @@ func (t *HybridSearchTool) Name() string { return "hybrid_search" }
 
 // Description provides a description for the tool.
 func (t *HybridSearchTool) Description() string {
-	return "Combined keyword + semantic search - use when you need EXACT matches (variable names, error messages) plus semantic context. Better than search_code when you have specific identifiers to find. Returns complete code with metadata."
+	return "Combined keyword + semantic search - use ONLY when you need EXACT matches (variable names, error messages, specific identifiers). Returns complete source code with file path, line numbers, and metadata. Use search_code FIRST for general exploration; use this when search_code misses exact terms. Supports Go, PHP, Python, HTML."
 }
 
 type hybridScore struct {

internal/tools/index_workspace.go

@@ -29,7 +29,7 @@ func (t *IndexWorkspaceTool) Name() string {
 
 // Description returns the tool description
 func (t *IndexWorkspaceTool) Description() string {
-	return "Index/reindex the codebase for search - usually automatic, but call this if search returns 'workspace not indexed' or after major code changes. Analyzes all Go, PHP, Python files and stores them for semantic search."
+	return "Index/reindex the codebase for search - USUALLY AUTOMATIC on first search. Call manually only if search returns 'workspace not indexed' or after major code changes (git pull, branch switch). Analyzes Go, PHP, Python, HTML files and stores vectors for semantic search."
 }
 
 // Execute indexes the workspace

internal/tools/list_package_exports.go

@@ -42,7 +42,7 @@ func (t *ListPackageExportsTool) Name() string {
 }
 
 func (t *ListPackageExportsTool) Description() string {
-	return "List all public functions, classes, and types in a package/module - gives you an overview of what's available. Use to explore an unfamiliar package or find the right function to call. Works for Go packages, PHP namespaces, Python modules."
+	return "List all public functions, classes, and types in a package/module. Returns a structured list with symbol names, types, and signatures. Use to explore an unfamiliar package or find the right function to call. Works for Go packages, PHP namespaces, Python modules."
 }
 
 func (t *ListPackageExportsTool) Execute(ctx context.Context, args map[string]interface{}) (string, error) {

internal/tools/search_docs.go

@@ -36,7 +36,7 @@ func (t *SearchDocsTool) Name() string {
 
 // Description returns the tool description
 func (t *SearchDocsTool) Description() string {
-	return "Search project documentation (README, guides, API docs) - use when you need to understand project setup, architecture decisions, or usage examples. Searches Markdown files only, not code."
+	return "Search project documentation (README, guides, API docs) - use when you need to understand project setup, architecture decisions, or usage examples. Returns relevant documentation snippets with file paths. Searches Markdown files ONLY, not code - use search_code for code."
 }
 
 // Execute executes a search in the docs index

internal/tools/search_local_index.go

@@ -43,7 +43,7 @@ func (t *SearchLocalIndexTool) Name() string {
 
 // Description returns the tool description
 func (t *SearchLocalIndexTool) Description() string {
-	return "Semantic code search - finds functions, classes, and methods by meaning, not just keywords. Returns complete code with file path and line numbers. Use this FIRST when exploring unfamiliar code or answering questions about how something works. Supports Go, PHP, Python."
+	return "Semantic code search - finds functions, classes, and methods by MEANING, not just keywords. USE THIS FIRST when exploring unfamiliar code. Returns complete source code with file path and line numbers. Better than hybrid_search for general exploration; use hybrid_search only when you need EXACT identifier matches. Supports Go, PHP, Python, HTML."
 }
 
 // Execute executes a search in the local index