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

Author: perfectra1n

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

@@ -490,43 +490,9 @@ export class ToolCallingStage extends BasePipelineStage<ToolExecutionInput, { re
             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!`;
+                directiveMessage = `No results found. Try alternative search approaches: use different search tools, broader terms, or alternative keywords. Continue searching - don't ask the user for guidance.`;
             } 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 = `You found results! Use read_note with the noteId values to get full content and continue your analysis.`;
             }
 
             updatedMessages.push({
@@ -638,14 +604,8 @@ export class ToolCallingStage extends BasePipelineStage<ToolExecutionInput, { re
             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!";
+        guidance += "\nTry alternative tools immediately. Use discover_tools if unsure which tool to use next.";
 
         return guidance;
     }

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

@@ -19,61 +19,26 @@ export const attributeSearchToolDefinition: Tool = {
     type: 'function',
     function: {
         name: 'attribute_search',
-        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`,
+        description: 'Search notes by attributes (labels/relations). attributeType must be exactly "label" or "relation" (lowercase).',
         parameters: {
             type: 'object',
             properties: {
                 attributeType: {
                     type: 'string',
-                    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`,
+                    description: 'Must be exactly "label" or "relation" (lowercase only).',
                     enum: ['label', 'relation']
                 },
                 attributeName: {
                     type: 'string',
-                    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)`
+                    description: 'Name of the attribute (e.g., "important", "todo", "relatedTo").'
                 },
                 attributeValue: {
                     type: 'string',
-                    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"`
+                    description: 'Optional value to match. Leave empty to find all notes with this attribute name.'
                 },
                 maxResults: {
                     type: 'number',
-                    description: 'Number of results (1-50, default: 20). Use higher values for comprehensive searches.'
+                    description: 'Maximum number of results (default: 20).'
                 }
             },
             required: ['attributeType', 'attributeName']
@@ -112,15 +77,7 @@ export class AttributeSearchTool implements ToolHandler {
                     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" }`;
+                const errorMessage = `Invalid attributeType: "${attributeType}". Must be exactly "label" or "relation" (lowercase). Example: {"attributeType": "label", "attributeName": "important"}`;
 
                 return errorMessage;
             }

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

@@ -17,49 +17,21 @@ export const keywordSearchToolDefinition: Tool = {
     type: 'function',
     function: {
         name: 'keyword_search_notes',
-        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`,
+        description: 'Keyword search for exact text matches. Supports phrases in quotes, #labels, ~relations, and search operators like OR.',
         parameters: {
             type: 'object',
             properties: {
                 query: {
                     type: 'string',
-                    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`
+                    description: 'Search query. Examples: "machine learning", "#important", "python OR javascript", "note.title *= weekly"'
                 },
                 maxResults: {
                     type: 'number',
                     description: 'Number of results (1-50, default: 10). Use higher values for comprehensive searches.'
                 },
                 includeArchived: {
                     type: 'boolean',
-                    description: 'INCLUDE ARCHIVED: Search archived notes too (default: false). Use true for complete historical search.'
+                    description: 'Include archived notes in search (default: false).'
                 }
             },
             required: ['query']
@@ -130,21 +102,7 @@ export class KeywordSearchTool implements ToolHandler {
                     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)'
-                        ]
-                    }
+                    message: `No keyword matches. Try: search_notes with "${this.convertToSemanticQuery(query)}" or check spelling/try simpler terms.`
                 };
             }
 
@@ -153,12 +111,7 @@ export class KeywordSearchTool implements ToolHandler {
                 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'
-                },
+                message: `Found ${limitedResults.length} keyword matches. Use read_note with noteId for full content.`,
                 results: limitedResults.map(note => {
                     // Get a preview of the note content with highlighted search terms
                     let contentPreview = '';

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

@@ -34,37 +34,17 @@ export const readNoteToolDefinition: Tool = {
     type: 'function',
     function: {
         name: 'read_note',
-        description: `READ FULL CONTENT of a specific note by its ID. Get complete note content and metadata.
-        
-        BEST FOR: Getting complete content after finding notes through search tools
-        USE WHEN: You have a noteId from search results and need the full content
-        IMPORTANT: Must use noteId (like "abc123def456") from search results - NOT note titles
-        
-        TIP: This is typically used after search_notes, keyword_search_notes, or attribute_search
-        
-        NEXT STEPS: Use note_update or attribute_manager tools to modify the note if needed`,
+        description: 'Read the full content of a note by its ID. Use noteId from search results, not note titles.',
         parameters: {
             type: 'object',
             properties: {
                 noteId: {
                     type: 'string',
-                    description: `SYSTEM ID of the note to read.
-                    
-                    CRITICAL: Must be a noteId (like "abc123def456") - NOT a note title!
-                    
-                    CORRECT: "abc123def456" (from search results)
-                    WRONG: "My Note Title" (this will fail)
-                    
-                    WHERE TO GET: From noteId field in search tool results`
+                    description: 'The noteId of the note to read (e.g., "abc123def456"). Get this from search results, not note titles.'
                 },
                 includeAttributes: {
                     type: 'boolean',
-                    description: `INCLUDE METADATA: Get note attributes (labels, relations) in response.
-                    
-                    • true = Get full note with all attributes/metadata
-                    • false = Get just note content (default)
-                    
-                    Use true when you need to see tags, labels, relations, or other metadata`
+                    description: 'Include note attributes/metadata in response (default: false).'
                 }
             },
             required: ['noteId']