The Latent Space

Recent Notes

v1.4.1 Release Changelog - Tag Search Tooling Refinement

8 min read

🎯 Focus

Tag-based discovery without the token tax.
Version 1.4.1 introduces token-efficient tag search capabilities, addressing a critical workflow gap: finding notes by tags without parsing entire note contents or frontmatter blocks. This point release completes the v1.4 metadata manipulation series by adding intelligent tag discovery tools.
The implementation carefully balances functionality with context efficiency—adding only the tool that provides genuine token savings while avoiding redundant operations already achievable through existing frontmatter CRUD tools.
Core Philosophy: Search operations should match their use case—content search for concepts, title search for names, and now tag search for taxonomy-based discovery.

📊 Performance Impact

Token Efficiency Gains

OperationTraditional ApproachTag Search ToolSavings
Find tagged notes (100 notes)list_notes (~2000-5000 tokens) + filtersearch_notes_by_tag (~200-500 tokens)80-95%
Find notes with 2+ tags (OR)list + parse all frontmatter (~3000-8000 tokens)search_notes_by_tag (~250-600 tokens)92-96%
Find notes with ALL tags (AND)list + parse + filter (~3000-8000 tokens)search_notes_by_tag (~250-600 tokens)92-96%
Find recent tagged noteslist + metadata + filter (~3000-6000 tokens)search_notes_by_tag w/ metadata (~300-1200 tokens)90-95%

Real-World Impact:

  • Tag organization workflows: 80-95% token reduction per search
  • Multi-tag queries: Direct AND/OR semantics without client-side filtering
  • Large vaults (1000+ notes): Sub-2-second response times
  • Typical user savings: ~2000-7000 tokens per tag search operation

Cost Analysis

For users performing 10 tag searches per day:

  • Without tool: ~40,000 tokens/day = ~1.2M tokens/month
  • With tool: ~4,000 tokens/day = ~120K tokens/month
  • Monthly savings: 90% reduction ($3-9/month at API rates)

✨ New Features

1. Token-Efficient Tag Search (search_notes_by_tag)

What it does:

  • Searches notes by tags without loading full content
  • Parses only frontmatter (not entire markdown body)
  • Returns matching notes with optional metadata

Key capabilities:

  • Case-insensitive matching: “Machine-Learning” matches “machine-learning”
  • AND/OR semantics: match_all parameter for intersection vs. union queries
  • Format flexibility: Supports both YAML list [ml, ai] and string ml formats
  • Optional metadata: Include timestamps and matched tags when needed
  • Graceful error handling: Skips malformed files, continues search

Example usage:

# Find any ML-related notes
search_notes_by_tag(["machine-learning", "ml", "deep-learning"], match_all=False)
 
# Find notes with BOTH tags
search_notes_by_tag(["obsidian", "mcp"], match_all=True)
 
# Find recent TODO notes
search_notes_by_tag(["todo"], include_metadata=True)

Tool count: 21 → 22 tools

🔧 Implementation Details

New Helper Function

  • search_notes_by_tags() - Core search logic with frontmatter-only parsing
    • Normalizes tags for case-insensitive matching
    • Handles both list and string tag formats in YAML
    • Implements AND/OR logic based on match_all parameter
    • Returns sorted results (alphabetical or by modification time)
    • Skips files gracefully on parse errors

New MCP Tool

  • search_notes_by_tag() - Token-efficient tag search
    • Annotations: readOnlyHint=True, openWorldHint=False
    • Parameters: tags, match_all, include_metadata, vault, ctx
    • Returns: Vault name, search params, and matches (with optional metadata)

Design Decisions

What we added:

  • ✅ Tag search tool (genuine 80-95% token savings)

What we deliberately skipped:

  • ❌ add_tag_to_note - Redundant with existing update_obsidian_frontmatter
  • ❌ remove_tag_from_note - Redundant with existing frontmatter CRUD
  • ❌ Advanced mode system - Unnecessary complexity, not standard MCP pattern

Rationale: Token economics showed that add/remove operations provide 0-300 token savings but cost 600 tokens in tool context overhead. Only when notes have 15+ frontmatter fields do dedicated add/remove tools break even, making them unsuitable for most users.

Token Cost Breakdown

search_notes_by_tag without metadata:

  • Tool call overhead: ~50 tokens
  • Parameters (tags, match_all): ~30 tokens
  • Response (paths only): ~120-400 tokens
  • Total: ~200-500 tokens

search_notes_by_tag with metadata:

  • Tool call overhead: ~50 tokens
  • Parameters: ~30 tokens
  • Response (paths + timestamps + tags): ~220-1120 tokens
  • Total: ~300-1200 tokens

Scale efficiency: Adds ~9 tokens per matched note when metadata is included.

🧪 Test Results

Test Coverage

  • Basic tag matching (single tag, multiple tags)
  • Case-insensitive matching
  • AND/OR semantics
  • Format handling (list vs string)
  • Metadata inclusion
  • Edge cases (empty tags, no frontmatter, malformed YAML)
  • Performance (1000+ notes)
  • Nested folders
  • Special characters in tags

Test Results

v1.4.1 Testing

📐 Design Philosophy

1. Token Efficiency First

Every tool must justify its token cost. Tag search provides 80-95% savings—clearly worth the ~200-token tool description overhead.

2. Avoid Redundancy

Don’t add tools that barely improve on existing operations. The add_tag / remove_tag analysis showed they would save only 0-300 tokens while costing 600 tokens in tool descriptions—net negative for most users.

3. Markdown-Native Operations

Tags live in frontmatter. Search should parse frontmatter, not full content. This aligns with how Obsidian actually works.

4. Compose, Don’t Bloat

Users can compose read_frontmatter + update_frontmatter for tag modifications. Adding dedicated tools would create unnecessary API surface area.

5. Real Workflows Drive Features

The implementation enables the core workflow: “tag my notes about machine learning” → search → analyze → tag. The search step was the bottleneck—now solved.

🏗️ Key Architectural Insights

Why Only One New Tool?

Token Economics Analysis:

Tool CandidateUpfront CostPer-Use SavingsBreak-Even Point
search_notes_by_tag+200 tokens~2000-7000 tokensFirst use ✅
add_tag_to_note+200 tokens~0-300 tokens2-4+ uses ❌
remove_tag_from_note+200 tokens~0-300 tokens2-4+ uses ❌

Decision: Only implement tools that provide immediate token ROI.

Frontmatter-Only Parsing

Traditional content search:

1. Read entire file (~800-2000 tokens per note)
2. Parse frontmatter + body
3. Extract tags
4. Filter matches
Total: ~2000-5000 tokens for 100 notes

Tag search approach:

1. Read file
2. Quick check: starts with "---"? If no, skip
3. Parse only YAML block (~50-150 tokens per note)
4. Extract tags
5. Match and return
Total: ~200-500 tokens for 100 notes

Key insight: Most notes don’t match. Don’t parse content you’ll discard.

AND/OR Semantics

Rather than forcing users to make multiple tool calls and filter client-side, the tool provides native AND/OR logic:

# OR: Match ANY tag (union)
match_all=False  # Default
# Returns: notes with tag1 OR tag2 OR tag3
 
# AND: Match ALL tags (intersection)
match_all=True
# Returns: notes with tag1 AND tag2 AND tag3

This eliminates an entire class of multi-step workflows.

Format Flexibility

Obsidian users employ different tagging styles:

tags: [ml, ai, research]           # List format
tags: machine-learning             # String format  
tags: Machine-Learning             # Mixed case

The tool normalizes all variants, preventing “tag doesn’t exist” errors due to format differences.

🚀 Migration Guide

Backward Compatibility

v1.4.1 is 100% backward compatible. No breaking changes, no required migrations.

Before (token-expensive):

# List all notes
all_notes = list_obsidian_notes(include_metadata=True)
# ~2000-5000 tokens
 
# Client-side filter by reading each note's frontmatter
ml_notes = []
for note in all_notes["notes"]:
    frontmatter = read_obsidian_frontmatter(note["path"])
    if "machine-learning" in frontmatter.get("tags", []):
        ml_notes.append(note)
# +150-450 tokens per note checked

After (token-efficient):

# Direct tag search
ml_notes = search_notes_by_tag(["machine-learning"])
# ~200-500 tokens total

Token savings: ~2000-7500 tokens (80-95% reduction)

Workflow Updates

Tag Organization Workflow:

# 1. Find candidate notes by content
candidates = search_obsidian_content("machine learning")
 
# 2. Review top matches
for note in candidates["results"][:5]:
    # Read to verify relevance
    content = retrieve_obsidian_note(note["path"])
    
    # Check existing tags
    frontmatter = read_obsidian_frontmatter(note["path"])
    current_tags = frontmatter.get("tags", [])
    
    # Add ML tag if not present
    if "machine-learning" not in current_tags:
        update_obsidian_frontmatter(
            note["path"],
            {"tags": current_tags + ["machine-learning"]}
        )
 
# 3. Verify tagging succeeded
ml_notes = search_notes_by_tag(["machine-learning"])
print(f"Tagged {len(ml_notes['matches'])} notes")

No Configuration Changes Required

The tool integrates seamlessly with existing vault management:

  • Respects active vault selection
  • Accepts explicit vault parameter
  • Works with all configured vaults

📚 Documentation Updates

README.md

  • Updated tool count: 21 → 22
  • Added search_notes_by_tag to Discovery & Search table
  • Updated token efficiency claims
  • Version bumped to v1.4.1

AGENTS.md

  • Added tool to “Discovery & search” section
  • Updated implementation notes
  • Marked v1.4.1 complete in roadmap

Tool Docstrings

  • Comprehensive parameter documentation
  • Return schema examples
  • “Use when” / “Don’t use” guidance
  • Error handling descriptions
  • Token cost estimates

🔮 Future Considerations

Not Planned for v1.5 (Awaiting User Feedback)

Potential enhancements that were considered but deferred:

  1. Tag autocomplete: List all tags in vault
  2. Tag statistics: Most used tags, orphaned notes
  3. Tag hierarchies: Support nested tags (ml/deep-learning)
  4. Regex tag matching: Pattern-based searches
  5. Bulk tag operations: Add/remove tags across multiple notes

Decision rationale: Keep v1.4.1 focused on core search functionality. Wait for real user feedback before expanding. Avoid premature optimization and feature bloat.

Known Limitations

Current implementation:

  • No regex or pattern matching
  • No tag suggestions or autocomplete
  • No tag statistics or analytics
  • No hierarchical tag support
  • No batch tag operations

These are deliberate scope decisions, not technical limitations. They can be added in future releases if user demand justifies the token cost.

Architecture Allows Future Growth

The frontmatter helper functions (_parse_frontmatter, _serialize_frontmatter, _ensure_valid_yaml) provide a solid foundation for more advanced tag operations if needed:

  • Tag renaming across vault
  • Tag merging/splitting
  • Tag hierarchy validation
  • Automated tag suggestions based on content

💡 Bottom Line

v1.4.1 delivers 80-95% token savings on tag discovery through focused, token-aware API design.

The key insight: Not every operation needs a dedicated tool. By carefully analyzing token economics, we identified that only tag search provides sufficient efficiency gains to justify the overhead. Tag modification workflows remain efficient by composing existing frontmatter CRUD operations.

Token efficiency isn’t just about cost—it’s about enabling workflows that were previously impractical. Before v1.4.1, searching 100 notes for tags cost 2000-5000 tokens. Now it costs 200-500 tokens. This 10x improvement makes tag-based organization practical for daily use.

Design philosophy in action: Build tools that solve real problems with measurable efficiency gains. Skip tools that provide marginal improvements. Compose simple operations rather than creating redundant APIs.

v1.4.1 completes the metadata manipulation series with surgical precision—one tool, massive impact.

🙏 Credits

Thanks to thorough token cost analysis and MCP best practices that guided the “implement only what provides clear value” decision-making process.

Status: ✅ Ready for release
Breaking Changes: None
Migration Required: None
Testing Required: ✅ Comprehensive test suite included

Graph View

Backlinks

Recent Notes