discover-notes

name	discover-notes
type	primitive
description	Global embedding-based search across all Notes; returns a Collection of matches

Discover-Notes

INPUT CONTRACT

• query (required): Natural-language search string
• out (required): $variable for the resulting Collection
• limit (optional, default 5): Max number of Notes returned (top-K by similarity)
• threshold (optional, default 0.3): Minimum cosine similarity for a match

REQUIREMENTS:

• query and out must be provided

BEHAVIOR

Runs an embedding-based search over every Note in the current infospace and returns the top-limit Notes above threshold as a Collection. Each hit is wrapped in a structured search-result Note (same shape as search-web / semantic-scholar results). An empty-case (no matches) still returns success with an empty Collection.

limit is a hard top-K cap. There is no way to express "all matches above threshold" — if you need higher recall (e.g. the goal says "all existing Notes that X"), pass an explicit larger limit (50+ is reasonable for a few-hundred-Note infospace). With the default of 5 the planner cannot distinguish "exhaustive" from "undersampled".

EXAMPLES

{"type": "discover-notes", "query": "transformer architectures or attention mechanisms", "out": "$matches"}

{"type": "discover-notes", "query": "meeting notes about the Q2 release", "limit": 50, "threshold": 0.25, "out": "$hits"}

OUTPUT

Returns success with the Collection bound to out. Use get_items("$var") to read the list of result Note IDs.

FAILURE SEMANTICS

• Missing query or out
• Underlying search failed (embedding index unavailable)

ANTI-PATTERNS

• Using the default limit=5 for "find all" goals — the result is silently top-5, not exhaustive. Always pass an explicit higher limit when the goal wording signals exhaustiveness.
• Treating an empty-Collection result as failed — an empty Collection is the legitimate no-match outcome. Branch on len(get_items("$var")), not on the tool's status.
• Calling discover-notes when the goal names a specific resource (_rss_pending_titles, etc.) — use load for known names, discover-notes for semantic discovery.