Okhp3 Notion Search Strategy

okhp3-notion-search-strategy

OverKill Hill P³ · overkillhill.com · github.com/OKHP3

Finds content by keyword or topic when the user does not already know where it lives. Always load okhp3-notion-core first.

Scope

Choosing a search backend

• Workspace search: faster, Notion-only, supports exact filters and non-relevance sorting (by last_edited or created).
• AI search: semantic, includes connected apps (Slack, Google Drive, GitHub, Jira, Microsoft Teams, SharePoint, OneDrive, Linear). Requires Notion AI on the workspace.
• If the caller does not specify a backend, the default auto-selects AI search when available, otherwise workspace search. Only force a specific mode when the task specifically needs one: force workspace search for exact-filter or non-relevance-sort needs (these cannot combine with AI search), or force AI search when the target is explicitly in a connected app.

Filters and plan gating

Available on every plan: location scoping (page, data source, or single teamspace), creator, and created-date range.

Business or Enterprise required (full Notion MCP): filtering by editor, last-edited date, multiple teamspaces at once, title-only matching, content status, and sorting by date. If okhp3-notion-core's capability map shows these are gated on the current workspace, do not attempt them - fall back to a broader unfiltered search and note the limitation rather than silently dropping the filter and returning misleading results.

An empty query is valid when a filter or a non-relevance sort is supplied instead of keyword text.

Rate limit discipline

Search carries its own tighter limit: 30 requests/minute, on top of the general 180/minute MCP ceiling. Never issue parallel search calls - serialize them, and load okhp3-notion-limits-and-retry for backoff handling if a search-heavy task is likely to approach this ceiling.

Result triage

• Search results are candidates to verify, not conclusions. Fetch a genuinely important result (via okhp3-notion-page-read or the appropriate reader) before treating it as authoritative, especially before using it as the basis for a write.
• Results may include path and verification fields. A verified page with a recent verification.expires_at is a stronger signal than an unverified page with a similar title - but recency alone is a tiebreaker, not proof of authority.
• When multiple plausible matches exist for an ambiguous title, present the candidates with enough distinguishing detail (location, last-edited date, verification state) for the user or calling skill to choose, rather than picking the first result.

Output contract

Report: which backend was used and why, which filters were applied versus skipped due to plan gating, the result count, and - for each result surfaced to the user - enough context (title, location, last-edited date) to distinguish it from a similarly named alternative. State plainly when zero results likely means the search terms were too narrow versus the content genuinely does not exist.

Tooling

scripts/select_search_backend.py applies "Choosing a search backend" and "Filters and plan gating" as deterministic functions instead of a per-task judgment call. It never silently applies a gated or unrecognized filter.

python3 scripts/select_search_backend.py --requested-filters last_edited_date,creator --business-or-enterprise false
python3 scripts/select_search_backend.py --self-test

Validation loop

Plan the backend and filter set with select_search_backend.py against the current capability map, validate that no gated filter was silently dropped without a stated limitation, execute the search serialized against the 30/minute search ceiling, then verify any result that matters before treating it as authoritative.

About

Built by Jamie Hill · OverKill Hill P³ Published at github.com/OKHP3 Part of the OKHP3/skillz Agent Skill library. MIT License -- free to use, fork, and adapt. A nod to the source is appreciated.