exa-known-pitfalls

# Exa Known Pitfalls ## Overview Real gotchas when integrating Exa's neural search API. Exa uses embeddings-based search rather than keyword matching, which creates a different class of failure modes than traditional search APIs. This skill covers the top pitfalls with wrong/right examples. ## Pitfall 1: Keyword-Style Queries Exa's neural search interprets natural language semantically. Boolean operators and keyword syntax degrade results. ```typescript import Exa from "exa-js"; const exa = new Exa(process.env.EXA_API_KEY); // BAD: keyword/boolean style — Exa ignores AND/OR const bad = await exa.search( "python AND machine learning OR deep learning 2024" ); // GOOD: natural language statement const good = await exa.search( "recent tutorials on building ML models with Python", { type: "neural", numResults: 10 } ); ``` ## Pitfall 2: Wrong Search Type Using neural search for exact lookups (URLs, names) or keyword search for conceptual queries silently degrades quality. ```typescript // BAD: neural search for a specific URL/identifier const bad = await exa.search("arxiv.org/abs/2301.00001", { type: "neural" }); // GOOD: keyword for exact terms, neural for concepts const exactMatch = await exa.search("arxiv.org/abs/2301.00001", { type: "keyword", }); const conceptual = await exa.search( "transformer architecture improvements for long context", { type: "neural" } ); ``` ## Pitfall 3: Expecting Content from search() `search()` returns metadata only (URL, titl...