feat: improve tool descriptions to motivate AI usage

Updated all 9 tool descriptions to be more actionable and informative:

- search_code: Now explains it's semantic search, returns complete code, 
  and should be used FIRST when exploring code
- hybrid_search: Clarifies when to use (exact matches + context)
- get_function_details: Emphasizes COMPLETE code with body
- find_type_definition: Mentions inheritance and all fields/methods
- find_implementations: Explains use case (impact analysis, usage examples)
- list_package_exports: Now mentions all supported languages
- search_docs: Clarifies it's for documentation, not code
- get_code_context: Explains use case (file path + line numbers)
- index_workspace: Clarifies it's usually automatic

Each description now:
1. Explains WHAT the tool returns
2. Explains WHEN to use it
3. Lists supported languages where applicable

Author: doITmagic

internal/tools/find_implementations.go

@@ -38,7 +38,7 @@ func (t *FindImplementationsTool) Name() string {
 }
 
 func (t *FindImplementationsTool) Description() string {
-	return "Find implementations, usages, or references to a function, method, or interface"
+	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."
 }
 
 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 complete type definition (struct or interface) including fields, methods, and code body"
+	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."
 }
 
 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 code from a specific file location with surrounding context lines"
+	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."
 }
 
 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 details about a function or method including signature, parameters, return values, and code body"
+	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."
 }
 
 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 "Performs hybrid lexical plus semantic search over the indexed codebase"
+	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."
 }
 
 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 "Indexes a workspace to enable code search. Call this when you receive a message that the workspace is not yet indexed. Requires file_path parameter to detect the workspace."
+	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."
 }
 
 // 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 exported functions, types, and constants from a Go package"
+	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."
 }
 
 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 "Searches the project documentation (Markdown) for relevant information"
+	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."
 }
 
 // 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 "Searches the local vector database for relevant documents"
+	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."
 }
 
 // Execute executes a search in the local index