docs(tool): update DocQLTool schema description and params

Revise and expand the DocQLTool schema documentation for clearer usage instructions, smart search guidance, advanced query examples, and detailed parameter descriptions.

Author: phodal

mpp-core/src/commonMain/kotlin/cc/unitmesh/agent/tool/impl/DocQLTool.kt

@@ -56,37 +56,94 @@ data class DocQLParams(
 
 object DocQLSchema : DeclarativeToolSchema(
     description = """
-        **Use this tool FIRST** when the user asks about:
-        - Project architecture, design, or structure ("How does X work?")
-        - Where specific functionality is implemented ("Where is authentication handled?")
-        - Code or documentation search ("Find classes related to Y")
+        Executes a DocQL query against available documents (both in-memory and indexed).
         
-        ## Usage
-        Just provide a keyword: `{"query": "authentication"}` → Auto-searches classes, functions, and docs
+        ## SMART SEARCH (Recommended)
+        Simply provide a keyword or phrase, and the tool will automatically:
+        1. Search for Classes and Functions matching the keyword (High Priority)
+        2. Search for Headings and Content matching the keyword (Medium Priority)
+        3. Rerank results to show the most relevant code and documentation first.
+        4. 如果用户使用的语言搜索不到结果，可以从用户的语言编码方式来搜索，比如拼音搜索、拼音编写、英语等。
         
-        **Advanced**: Use DocQL queries for precise results:
-        - Code: `$.code.class("UserService")` or `$.code.function("login")`
-        - Docs: `$.content.heading("Architecture")` or `$.toc[*]`
+        **Example:** `{"query": "Auth"}` -> Finds `AuthService` class, `authenticate` function, and "Authentication" sections.
+        
+        ## ADVANCED: DIRECT DOCQL QUERIES
+        For precise control, use standard DocQL syntax (starts with `$.`):
+        
+        ### 1. Document Queries ($.content.*, $.toc[*])
+        **For:** Markdown, text files, documentation (.md, .txt, README)
+        **Examples:**
+        - $.content.heading("keyword") - Find sections by heading
+        - $.content.chunks() - Get all content chunks
+        - $.toc[*] - Get table of contents
+        
+        ### 2. Code Queries ($.code.*)
+        **For:** Source code files (.kt, .java, .py, .js, .ts, .go, .rs, .cs)
+        **Parser:** TreeSitter-based with full code structure
+        **Examples:**
+        - $.code.class("ClassName") - Find class with full source code
+        - $.code.function("functionName") - Find function/method with implementation
+        - $.code.classes[*] - List all classes
+        - $.code.functions[*] - List all functions/methods
+        
+        ## Parameters
+        - **query** (required): The keyword (Smart Search) or DocQL query string (Advanced)
+        - **documentPath** (optional): Target specific document by path
+        - **maxResults** (optional): Limit results (default: 20)
+        - **secondaryKeyword** (optional): Additional keyword for filtering when results are too many
+        
+        ## Multi-Level Keyword Strategy
+        The tool automatically expands keywords when needed:
+        - **Level 1**: Original query + phrase variations (e.g., "base64 encoding" → "base64 encoder")
+        - **Level 2**: Component words (e.g., "base64", "encoding")
+        - **Level 3**: Stem variants (e.g., "encode", "encoded", "encoder")
+        
+        If you provide a **secondaryKeyword**, it will be used to filter Level 1 results when too many.
     """.trimIndent(),
     properties = mapOf(
         "query" to string(
-            description = "Keyword for smart search, or DocQL query ($.code.*, $.content.*). Examples: \"MCP\", \"$.code.class(\\\"AuthService\\\")\"",
+            description = "The keyword to search for (Smart Search) or a specific DocQL query (e.g., '$.content.heading(\"Introduction\")').",
             required = true
         ),
         "documentPath" to string(
-            description = "Target specific document (e.g., 'README.md'). Omit to search all.",
+            description = """
+                The path of the document to query (e.g., 'design-system-color.md').
+                Use this to target specific documents when their names match your keywords.
+                Check the available documents list and match keywords before querying.
+                If omitted, searches all registered documents.
+            """.trimIndent(),
             required = false
         ),
         "maxResults" to integer(
-            description = "Max results (default: 20)",
+            description = """
+                Maximum number of results to return. Default is 20.
+                Use lower values for quick overview, higher values for comprehensive search.
+                Note: Very high values may exceed context limits for large result sets.
+            """.trimIndent(),
             required = false
         ),
         "secondaryKeyword" to string(
-            description = "Additional filter keyword when too many results",
+            description = """
+                Optional secondary keyword for multi-level filtering.
+                When the primary query returns too many results (>50), the secondary keyword
+                is used to filter and prioritize the most relevant results.
+                
+                Example: query="Auth", secondaryKeyword="Service" 
+                  → Finds AuthService, AuthenticationService with higher priority
+            """.trimIndent(),
             required = false
         ),
         "rerankerType" to string(
-            description = "Reranker: 'heuristic' (default, fast), 'llm_metadata' (uses AI model, smarter but costs tokens), 'hybrid' (balanced)",
+            description = """
+                Reranker algorithm to use for ordering results.
+                
+                Options:
+                - "heuristic" (default): Fast BM25 + type + name matching. Best for quick searches.
+                - "rrf_composite": RRF fusion with composite scoring. Better for multi-source results.
+                - "llm_metadata": LLM-based intelligent reranking using document metadata.
+                  Considers file paths, headings, modification time, references. Slower but smarter.
+                - "hybrid": Heuristic pre-filter + LLM rerank. Balance of speed and quality.
+            """.trimIndent(),
             required = false
         )
     )