Enhancement Description

Add comprehensive search syntax examples and documentation to improve user experience with the search_notes tool.

Background

During live testing, it became clear that users need better guidance on:

• Supported search syntax
• Query formatting examples
• Best practices for effective searches
• Limitations and workarounds

Current State

The search_notes tool works well for basic keyword searches but lacks clear documentation about:

• What syntax is supported
• How to format complex queries
• Examples of effective search patterns
• Error handling explanations

Proposed Improvements

1. Tool Documentation Enhancement

Add to search_notes tool description:

## Search Syntax Examples

### Basic Searches
- `search_notes("keyword")` - Find any content containing "keyword"
- `search_notes("exact phrase")` - Search for exact phrase match

### Advanced Searches  
- `search_notes("term1 term2")` - Find content with both terms (implicit AND)
- `search_notes("tag:example")` - Search within specific tags
- `search_notes("category:observation")` - Filter by observation categories

### Filtering Options
- `search_notes("query", types=["entity"])` - Search only entities
- `search_notes("query", after_date="2024-01-01")` - Recent content only

2. Error Message Improvements

When search syntax fails, provide:

• Clear explanation of what went wrong
• Suggested alternative query formats
• Examples of working syntax

3. Help Examples in Tool Response

For empty or failed searches, suggest:

• Alternative query formats
• Related search strategies
• Common search patterns

Implementation Areas

1. MCP Tool Descriptions - Update tool docstrings with examples
2. Error Responses - Enhance error messages with helpful guidance
3. Tool Documentation - Add comprehensive search guide
4. User Guide - Include search best practices

Success Criteria

• Users can quickly understand supported search syntax
• Failed searches provide actionable guidance
• Search success rate improves through better user education
• Documentation covers edge cases and limitations

Priority

• Impact: High - Improves user experience significantly
• Effort: Medium - Documentation and message updates
• Timeline: Include in v0.14.0 for better search UX

Related

• Identified during comprehensive live testing
• Complements Boolean search syntax fix (Fix Boolean search syntax SQL parsing error #178)
• Improves overall search tool usability