Feature: Merge search_by_metadata into search_notes as optional filters

[bm-clawd]

Problem

We currently have two search tools: search_notes (text/semantic search) and search_by_metadata (frontmatter filter). This is confusing for agents and wastes tool calls when you want both — e.g. "find active tasks about dashboards" requires either two calls or picking one approach.

Proposal

Add optional type and metadata_filters parameters to search_notes so one tool handles everything:

search_notes(
    query="dashboard",           # text/semantic search (optional)
    type="Task",                  # shorthand for frontmatter type filter
    metadata_filters={"status": "active"},  # additional frontmatter filters
    limit=10
)

Behavior:

• query only → current text/semantic search (unchanged)
• type/metadata_filters only → pure metadata filter (replaces search_by_metadata)
• Both → text search filtered by metadata (the common case agents actually need)

Why

• Simpler tool surface for agents (1 tool instead of 2)
• The dashboard currently has to choose between text search and metadata filter — combining them is the natural query
• Reduces tool call overhead
• search_by_metadata can be deprecated/aliased

Backward Compatibility

• All existing search_notes calls work unchanged (new params are optional)
• search_by_metadata could remain as an alias or be deprecated with a migration period

[claude]

Claude finished @bm-clawd's task in 1m 54s —— View job

---

Triage Analysis

• Gather context from issue
• Read relevant source files
• Assess complexity and feasibility
• Check for duplicates
• Apply labels
• Provide final triage summary

---

Issue Classification

Attribute	Value
Type	Enhancement (unifying two tools)
Priority	Medium
Component	MCP Tools
Complexity	Medium
Label Applied	enhancement

---

Analysis

No duplicates found. This is a clean, well-scoped feature request.

Good news — most of the backend already supports this! After reviewing the code:

• search_notes already accepts metadata_filters: Optional[Dict[str, Any]] as an optional parameter (added previously)
• The SearchQuery schema supports metadata filters independently of text queries
• The search repository and service both handle metadata_filters without requiring a text query

What's actually missing / needs to change:

1. query is currently required in search_notes — it's query: str, not Optional[str]. Making it optional would allow pure metadata-only searches without a text query.

2. type shorthand parameter — convenience param that maps to metadata_filters={"type": "Task"}. Not currently present in search_notes.

3. search_by_metadata uses different pagination (offset/limit) vs search_notes (page/page_size). The deprecation path needs to handle this gap.

4. Deprecation notice for search_by_metadata once the unified approach is ready.

Minimal changeset:

• Make query: Optional[str] = None in search_notes
• Add type: Optional[str] = None as a shorthand convenience parameter
• Add guard: require at least one of query, type, or metadata_filters to be provided
• Update docstring to reflect combined usage
• Add deprecation notice to search_by_metadata
• Update tests

The proposal is sound and well-scoped. The implementation complexity is medium since the heavy lifting (backend metadata filter support) is already done — it's primarily a tool interface update with careful handling of the optional query parameter.