Exa Neural Query Planner

Purpose

Produce an Exa search plan before any Exa API call (via exa, exa-plus, web-search-plus, MCP, or custom scripts). Exa’s neural search rewards well-phrased natural-language queries and the right category / domain / date filters — most wrappers execute requests but don’t help you plan them.

This skill does not call Exa, store API keys, or wrap the API. It outputs a ready-to-run plan another skill or script can execute.

When to use

Use when the user mentions:

• Searching with Exa or exa.ai
• Neural / semantic web search for docs, papers, companies, news, or GitHub repos
• Choosing Exa filters (domains, dates, categories)
• Poor Exa results and needing better query phrasing
• Whether to use Exa vs keyword search (Google/Serper/Tavily)

Safety and boundaries

Do not ask for or echo EXA_API_KEY or other secrets.

Do not claim live web results — this skill only plans queries; execution happens elsewhere.

Do not instruct bypassing paywalls, scraping behind logins, or violating site terms.

Rate/cost awareness: Note that type: deep and high numResults cost more; recommend conservative defaults unless the user needs exhaustive coverage.

Required inputs

Ask only what’s missing:

1. Research goal — one sentence (what decision or answer depends on this search).
2. Entity type — company, person, product, paper, news event, code/library, policy, or mixed.
3. Freshness — breaking (24h), recent (30d), evergreen, or historical range.
4. Trusted sources (optional) — domains to prefer or block (e.g. arxiv.org, github.com, exclude pinterest.com).
5. Depth — quick scan (3–5 results) vs thorough (10–20).
6. Downstream — human summary, agent context, or citation list.

Workflow

1. Restate the goal and recommend Exa vs keyword search (see decision rubric).
2. If Exa: draft the plan using Output format.
3. Include 2–3 fallback queries (broader/narrower/different category).
4. Flag stop conditions — when results are likely sufficient or when to switch provider.

Exa vs keyword — decision rubric

When unsure, plan one Exa neural query + one keyword fallback.

Output format

Return markdown:

Exa search plan — {short goal}

Primary query

Natural-language query optimized for Exa neural search (complete sentence, include context nouns, avoid boolean operators).

API hints (for executor skill)

type: neural          # or auto / keyword if noted
useAutoprompt: true   # default true for vague goals
category: <category>  # if applicable
includeDomains: []    # optional
excludeDomains: []    # optional
startPublishedDate:   # ISO or null
endPublishedDate:     # ISO or null

Fallback queries

1. Broader variant
2. Narrower variant (domain- or category-locked)
3. Keyword-style variant (if neural underperforms)

Quality checks after execution

• Top 3 results match entity type
• Publication dates fit freshness requirement
• No duplicate domains dominating results
• Snippets contain answer-bearing text (not nav pages)

Stop / escalate

When to stop searching vs try fallback vs switch to Tavily/Serper.

Quality bar

• Queries are sentences, not keyword bags — e.g. “Startup companies building on-chain identity verification for EU enterprises” not on-chain identity EU.
• Category matches entity — don’t use github for legal news.
• Filters are justified — every includeDomains entry ties to the goal.
• Executor-ready — another skill can copy the YAML block without reinterpretation.

Examples

Good primary query: “Peer-reviewed research on retrieval-augmented generation evaluation metrics published after 2024.”

Bad primary query: “RAG eval metrics 2024.”

Good excludeDomains: pinterest.com, quora.com when researching B2B SaaS pricing.

Bad excludeDomains: Blocking all blogs when the goal is practitioner guides.