feat(llm): try to improve tool and tool calling, part 1

Author: perfectra1n

apps/server/src/services/llm/pipeline/stages/tool_calling_stage.ts

@@ -483,28 +483,52 @@ export class ToolCallingStage extends BasePipelineStage<ToolExecutionInput, { re
         log.info(`Follow-up needed: ${needsFollowUp}`);
         log.info(`Reasoning: ${hasToolResults ? 'Has tool results to process' : 'No tool results'} ${hasErrors ? ', contains errors' : ''} ${hasEmptyResults ? ', contains empty results' : ''}`);
 
-        // Add a system message with hints for empty results
-        if (hasEmptyResults && needsFollowUp) {
-            log.info('Adding system message requiring the LLM to run additional tools with different parameters');
-
-            // Build a more directive message based on which tools were empty
-            const emptyToolNames = toolResultMessages
-                .filter(msg => this.isEmptyToolResult(msg.content, msg.name || ''))
-                .map(msg => msg.name);
-
-            let directiveMessage = `YOU MUST NOT GIVE UP AFTER A SINGLE EMPTY SEARCH RESULT. `;
-
-            if (emptyToolNames.includes('search_notes') || emptyToolNames.includes('keyword_search')) {
-                directiveMessage += `IMMEDIATELY RUN ANOTHER SEARCH TOOL with broader search terms, alternative keywords, or related concepts. `;
-                directiveMessage += `Try synonyms, more general terms, or related topics. `;
-            }
-
-            if (emptyToolNames.includes('keyword_search')) {
-                directiveMessage += `IMMEDIATELY TRY SEARCH_NOTES INSTEAD as it might find matches where keyword search failed. `;
+        // Add aggressive system message for continued tool usage
+        if (needsFollowUp) {
+            log.info('Adding enhanced system message to encourage continued tool usage');
+
+            let directiveMessage = '';
+
+            if (hasEmptyResults) {
+                // Empty results - be very directive about trying alternatives
+                const emptyToolNames = toolResultMessages
+                    .filter(msg => this.isEmptyToolResult(msg.content, msg.name || ''))
+                    .map(msg => msg.name);
+
+                directiveMessage = `CRITICAL INSTRUCTION: YOU MUST NOT STOP AFTER EMPTY RESULTS!\n\n`;
+                directiveMessage += `REQUIRED ACTIONS:\n`;
+                
+                if (emptyToolNames.includes('search_notes')) {
+                    directiveMessage += `1. IMMEDIATELY use keyword_search_notes with specific terms\n`;
+                    directiveMessage += `2. Try attribute_search if content might be tagged/categorized\n`;
+                    directiveMessage += `3. Use discover_tools to find alternative approaches\n`;
+                }
+                
+                if (emptyToolNames.includes('keyword_search_notes')) {
+                    directiveMessage += `1. IMMEDIATELY use search_notes for semantic matching\n`;
+                    directiveMessage += `2. Try broader or alternative keyword terms\n`;
+                    directiveMessage += `3. Use workflow_helper for guidance on next steps\n`;
+                }
+                
+                if (emptyToolNames.includes('attribute_search')) {
+                    directiveMessage += `1. Use search_notes to find content about the attribute topic\n`;
+                    directiveMessage += `2. Try different attribute names or types\n`;
+                    directiveMessage += `3. Use search_suggestion to see available attributes\n`;
+                }
+                
+                directiveMessage += `\nFORBIDDEN: Do NOT ask user for clarification or offer general information!\n`;
+                directiveMessage += `REQUIRED: CONTINUE with alternative tools and approaches immediately!`;
+            } else {
+                // Has results - encourage follow-up actions
+                directiveMessage = `EXCELLENT! You found results. Now CONTINUE the workflow:\n\n`;
+                directiveMessage += `NEXT REQUIRED ACTIONS:\n`;
+                directiveMessage += `1. Use read_note to examine the most relevant results\n`;
+                directiveMessage += `2. Use workflow_helper to plan next steps based on your findings\n`;
+                directiveMessage += `3. Consider using related tools for deeper analysis\n\n`;
+                directiveMessage += `GOAL: Provide comprehensive information by using multiple tools in sequence.\n`;
+                directiveMessage += `CONTINUE with tool usage - don't stop at just search results!`;
             }
 
-            directiveMessage += `DO NOT ask the user what to do next or if they want general information. CONTINUE SEARCHING with different parameters.`;
-
             updatedMessages.push({
                 role: 'system',
                 content: directiveMessage
@@ -609,10 +633,19 @@ export class ToolCallingStage extends BasePipelineStage<ToolExecutionInput, { re
             }
         }
 
-        // Add a general suggestion to try search_notes as a fallback
+        // Add general recommendations including new helper tools
         if (!toolName.includes('search_notes')) {
             guidance += "RECOMMENDATION: If specific searches fail, try the 'search_notes' tool which performs semantic searches.\n";
         }
+        
+        // Always suggest helper tools for guidance
+        guidance += "HELPER TOOLS AVAILABLE:\n";
+        guidance += "• Use 'discover_tools' to find the right tool for your task\n";
+        guidance += "• Use 'workflow_helper' to get guidance on next steps\n";
+        guidance += "• Use 'search_suggestion' for search syntax help\n";
+        
+        // Encourage continued tool usage
+        guidance += "\nIMPORTANT: Don't stop after one failed tool - try alternatives immediately!";
 
         return guidance;
     }

apps/server/src/services/llm/tools/attribute_search_tool.ts

@@ -19,26 +19,61 @@ export const attributeSearchToolDefinition: Tool = {
     type: 'function',
     function: {
         name: 'attribute_search',
-        description: 'Search for notes with specific attributes (labels or relations). Use this when you need to find notes based on their metadata rather than content. IMPORTANT: attributeType must be exactly "label" or "relation" (lowercase).',
+        description: `ATTRIBUTE-BASED search for notes. Find notes by their labels or relations (metadata/tags).
+        
+        BEST FOR: Finding notes by categories, tags, status, relationships, or other metadata
+        USE WHEN: You need notes with specific labels, relations, or organizational attributes
+        DIFFERENT FROM: search_notes (content) and keyword_search_notes (text)
+        
+        CRITICAL: attributeType MUST be exactly "label" or "relation" (lowercase only!)
+        
+        COMMON ATTRIBUTES:
+        • Labels: #important, #todo, #project, #status, #priority
+        • Relations: ~relatedTo, ~childOf, ~contains, ~references
+        
+        NEXT STEPS: Use read_note with returned noteId values for full content`,
         parameters: {
             type: 'object',
             properties: {
                 attributeType: {
                     type: 'string',
-                    description: 'MUST be exactly "label" or "relation" (lowercase, no other values are valid)',
+                    description: `MUST be exactly "label" or "relation" (lowercase only!)
+                    
+                    CORRECT: "label", "relation"
+                    WRONG: "Label", "LABEL", "labels", "relations"
+                    
+                    • "label" = tags/categories like #important, #todo
+                    • "relation" = connections like ~relatedTo, ~childOf`,
                     enum: ['label', 'relation']
                 },
                 attributeName: {
                     type: 'string',
-                    description: 'Name of the attribute to search for (e.g., "important", "todo", "related-to")'
+                    description: `Name of the attribute to search for.
+                    
+                    LABEL EXAMPLES:
+                    - "important" (finds notes with #important)
+                    - "status" (finds notes with #status label)
+                    - "project" (finds notes tagged #project)
+                    
+                    RELATION EXAMPLES:
+                    - "relatedTo" (finds notes with ~relatedTo relation)
+                    - "childOf" (finds notes with ~childOf relation)
+                    - "contains" (finds notes with ~contains relation)`
                 },
                 attributeValue: {
                     type: 'string',
-                    description: 'Optional value of the attribute. If not provided, will find all notes with the given attribute name.'
+                    description: `OPTIONAL: Specific value of the attribute.
+                    
+                    • Leave empty to find ALL notes with this attribute
+                    • Specify value to find notes where attribute = specific value
+                    
+                    EXAMPLES:
+                    - attributeName: "status", attributeValue: "completed"
+                    - attributeName: "priority", attributeValue: "high"`
                 },
                 maxResults: {
                     type: 'number',
-                    description: 'Maximum number of results to return (default: 20)'
+                    description: 'Number of results (1-50, default: 20). Use higher values for comprehensive searches.'
                 }
             },
             required: ['attributeType', 'attributeName']
@@ -61,9 +96,33 @@ export class AttributeSearchTool implements ToolHandler {
 
             log.info(`Executing attribute_search tool - Type: "${attributeType}", Name: "${attributeName}", Value: "${attributeValue || 'any'}", MaxResults: ${maxResults}`);
 
-            // Validate attribute type
+            // Enhanced validation with helpful guidance
             if (attributeType !== 'label' && attributeType !== 'relation') {
-                return `Error: Invalid attribute type. Must be exactly "label" or "relation" (lowercase). You provided: "${attributeType}".`;
+                const suggestions: string[] = [];
+                
+                if (attributeType.toLowerCase() === 'label' || attributeType.toLowerCase() === 'relation') {
+                    suggestions.push(`CASE SENSITIVE: Use "${attributeType.toLowerCase()}" (lowercase)`);
+                }
+                
+                if (attributeType.includes('label') || attributeType.includes('Label')) {
+                    suggestions.push('CORRECT: Use "label" for tags and categories');
+                }
+                
+                if (attributeType.includes('relation') || attributeType.includes('Relation')) {
+                    suggestions.push('CORRECT: Use "relation" for connections and relationships');
+                }
+                
+                const errorMessage = `Invalid attributeType: "${attributeType}"
+
+REQUIRED: Must be exactly "label" or "relation" (lowercase only!)
+
+${suggestions.length > 0 ? suggestions.join('\n') : ''}
+
+EXAMPLES:
+• Find notes with #important tag: { "attributeType": "label", "attributeName": "important" }
+• Find notes with ~relatedTo relation: { "attributeType": "relation", "attributeName": "relatedTo" }`;
+                
+                return errorMessage;
             }
 
             // Execute the search

apps/server/src/services/llm/tools/keyword_search_tool.ts

@@ -17,21 +17,49 @@ export const keywordSearchToolDefinition: Tool = {
     type: 'function',
     function: {
         name: 'keyword_search_notes',
-        description: 'Search for notes using exact keyword matching and attribute filters. Use this for precise searches when you need exact matches or want to filter by attributes.',
+        description: `EXACT KEYWORD search for notes. Finds notes containing specific words, phrases, or attribute filters.
+        
+        BEST FOR: Finding notes with specific words/phrases you know exist
+        USE WHEN: You need exact text matches, specific terms, or attribute-based filtering
+        DIFFERENT FROM: search_notes (which finds conceptual/semantic matches)
+        
+        SEARCH TYPES:
+        • Simple: "machine learning" (finds notes containing both words)
+        • Phrase: "\"exact phrase\"" (finds this exact phrase)
+        • Attributes: "#label" or "~relation" (notes with specific labels/relations)
+        • Complex: "AI #project ~relatedTo" (combines keywords with attributes)
+        
+        NEXT STEPS: Use read_note with returned noteId values for full content`,
         parameters: {
             type: 'object',
             properties: {
                 query: {
                     type: 'string',
-                    description: 'The search query using Trilium\'s search syntax. Examples: "rings tolkien" (find notes with both words), "#book #year >= 2000" (notes with label "book" and "year" attribute >= 2000), "note.content *=* important" (notes with "important" in content)'
+                    description: `Keyword search query using Trilium search syntax.
+                    
+                    SIMPLE EXAMPLES:
+                    - "machine learning" (both words anywhere)
+                    - "\"project management\"" (exact phrase)
+                    - "python OR javascript" (either word)
+                    
+                    ATTRIBUTE EXAMPLES:
+                    - "#important" (notes with 'important' label)
+                    - "~project" (notes with 'project' relation)
+                    - "#status = completed" (specific label value)
+                    
+                    COMBINED EXAMPLES:
+                    - "AI #project #status = active" (AI content with project label and active status)
+                    - "note.title *= \"weekly\"" (titles containing 'weekly')
+                    
+                    AVOID: Conceptual queries better suited for search_notes`
                 },
                 maxResults: {
                     type: 'number',
-                    description: 'Maximum number of results to return (default: 10)'
+                    description: 'Number of results (1-50, default: 10). Use higher values for comprehensive searches.'
                 },
                 includeArchived: {
                     type: 'boolean',
-                    description: 'Whether to include archived notes in search results (default: false)'
+                    description: 'INCLUDE ARCHIVED: Search archived notes too (default: false). Use true for complete historical search.'
                 }
             },
             required: ['query']
@@ -45,6 +73,22 @@ export const keywordSearchToolDefinition: Tool = {
 export class KeywordSearchTool implements ToolHandler {
     public definition: Tool = keywordSearchToolDefinition;
 
+    /**
+     * Convert a keyword query to a semantic query suggestion
+     */
+    private convertToSemanticQuery(keywordQuery: string): string {
+        // Remove search operators and attributes to create a semantic query
+        return keywordQuery
+            .replace(/#\w+/g, '') // Remove label filters
+            .replace(/~\w+/g, '') // Remove relation filters
+            .replace(/\"[^\"]*\"/g, (match) => match.slice(1, -1)) // Remove quotes but keep content
+            .replace(/\s+OR\s+/gi, ' ') // Replace OR with space
+            .replace(/\s+AND\s+/gi, ' ') // Replace AND with space
+            .replace(/note\.(title|content)\s*\*=\*\s*/gi, '') // Remove note.content operators
+            .replace(/\s+/g, ' ') // Normalize spaces
+            .trim();
+    }
+
     /**
      * Execute the keyword search notes tool
      */
@@ -80,21 +124,52 @@ export class KeywordSearchTool implements ToolHandler {
                 log.info(`No matching notes found for query: "${query}"`);
             }
 
-            // Format the results
+            // Format the results with enhanced guidance
+            if (limitedResults.length === 0) {
+                return {
+                    count: 0,
+                    results: [],
+                    query: query,
+                    searchType: 'keyword',
+                    message: 'No exact keyword matches found.',
+                    nextSteps: {
+                        immediate: [
+                            `Try search_notes for semantic/conceptual search: "${this.convertToSemanticQuery(query)}"`,
+                            `Use attribute_search if looking for specific labels or relations`,
+                            `Try simpler keywords or check spelling`
+                        ],
+                        queryHelp: [
+                            'Remove quotes for broader matching',
+                            'Try individual words instead of phrases',
+                            'Use OR operator: "word1 OR word2"',
+                            'Check if content might be in archived notes (set includeArchived: true)'
+                        ]
+                    }
+                };
+            }
+            
             return {
                 count: limitedResults.length,
                 totalFound: searchResults.length,
+                query: query,
+                searchType: 'keyword',
+                message: 'Found exact keyword matches. Use noteId values with other tools.',
+                nextSteps: {
+                    examine: `Use read_note with any noteId (e.g., "${limitedResults[0].noteId}") to get full content`,
+                    refine: limitedResults.length < searchResults.length ? `Found ${searchResults.length} total matches (showing ${limitedResults.length}). Increase maxResults for more.` : null,
+                    related: 'Use search_notes for conceptually related content beyond exact keywords'
+                },
                 results: limitedResults.map(note => {
-                    // Get a preview of the note content
+                    // Get a preview of the note content with highlighted search terms
                     let contentPreview = '';
                     try {
                         const content = note.getContent();
                         if (typeof content === 'string') {
-                            contentPreview = content.length > 150 ? content.substring(0, 150) + '...' : content;
+                            contentPreview = content.length > 200 ? content.substring(0, 200) + '...' : content;
                         } else if (Buffer.isBuffer(content)) {
                             contentPreview = '[Binary content]';
                         } else {
-                            contentPreview = String(content).substring(0, 150) + (String(content).length > 150 ? '...' : '');
+                            contentPreview = String(content).substring(0, 200) + (String(content).length > 200 ? '...' : '');
                         }
                     } catch (e) {
                         contentPreview = '[Content not available]';
@@ -114,7 +189,8 @@ export class KeywordSearchTool implements ToolHandler {
                         attributes: attributes.length > 0 ? attributes : undefined,
                         type: note.type,
                         mime: note.mime,
-                        isArchived: note.isArchived
+                        isArchived: note.isArchived,
+                        dateModified: note.dateModified
                     };
                 })
             };