Search with two paths: Path 1 is a RARE EXCEPTION for pure encyclopedia only. Path 2 (the DEFAULT for everything else) REQUIRES get_sub_domains before search.
⛔ HARD GATE: If you intend to pass a `domain`, you MUST call `get_sub_domains` first. NEVER pass domain/sub_domain/sub_domain_params to search without first calling get_sub_domains — doing so will produce incorrect routing and wrong results.
## Decision Tree (follow in order):
1. Is the query PURE encyclopedia / common knowledge with ZERO domain overlap?
(e.g., "What is gravity?", "Who wrote Hamlet?")
→ YES: Use Path 1 (general query, no domain at all)
→ UNSURE / COULD BE BOTH → Use Path 2 with batch_search: fire 1 general query + N vertical queries in parallel. This is the SAFEST approach — coverage beats guessing. This applies to ANY query where encyclopedia knowledge and domain-specific sources could both contribute (e.g., classical texts, financial theories, legal concepts, historical events, scientific breakthroughs, medical conditions, etc. — if the topic has an associated domain, use hybrid).
→ NO (clearly domain-specific): Go to step 2
2. The query involves structured data, domain-specific topics, real-time info, or ANY ambiguity.
→ Path 2 REQUIRED: get_sub_domains(domains=[...]) → search or batch_search
3. Does the query CROSS multiple domains that INTERSECT on the same topic?
(e.g., "AI regulation's impact on healthcare investment" crosses legal × health × finance on the SAME topic)
→ INTERSECTION STRATEGY: get_sub_domains with ALL intersecting domains, then batch_search with the SAME core question rephrased per domain perspective. See Multi-Domain Strategy below.
## Path 1 — General query (RARE EXCEPTION, ONLY for pure encyclopedia with ZERO domain overlap)
ONLY for "What is X / Who is Y" questions that do NOT overlap with any specific domain.
Usage: search(query="what is quantum entanglement", max_results=10)
## Path 2 — Vertical query (THE DEFAULT — use this for everything that has ANY domain relevance)
MUST follow this workflow:
Step 1: get_sub_domains(domains=["domain1", "domain2", ...]) — pass ALL potentially relevant domains at once via the `domains` array. ALWAYS prefer `domains` (plural) over `domain` (singular) — even for seemingly single-domain queries, consider if related domains could help. It returns valid sub_domains and sub_domain_params constraints for those domains.
Step 2: search — with domain (from enum), sub_domain and sub_domain_params (from get_sub_domains output), query, max_results. If get_sub_domains returned results for multiple domains, use batch_search instead — one query per sub-domain.
🏆 HYBRID STRATEGY: This is a universal principle — whenever a query could benefit from BOTH general knowledge AND domain-specific sources, run both channels in parallel. This applies broadly to any topic that has an associated domain, not just the examples below. Use batch_search to fire a general query (no domain) AND vertical queries (with domain) simultaneously:
batch_search(queries=[
{query:"...", max_results:5}, // general — no domain
{query:"...", domain:"finance", sub_domain:"..."}, // vertical channel 1
{query:"...", domain:"academic", sub_domain:"..."} // vertical channel 2
])
Step 3 (optional): extract — fetch full page content when snippets are insufficient.
## Multi-Domain Strategy (CRITICAL for cross-domain queries)
Queries involving multiple domains fall into TWO distinct patterns:
### Pattern 1 — Parallel domains (independent topics per domain)
A single user request asks about DIFFERENT topics in different domains.
Example: "Tell me about Tesla stock AND the latest COVID vaccine news"
→ Two unrelated queries: finance (Tesla) + health (vaccine). Use batch_search with DIFFERENT queries per domain.
### Pattern 2 — Intersecting domains (SAME topic crosses multiple domains) — 🏆 THIS IS THE DEFAULT FOR AMBIGUOUS QUERIES
A SINGLE topic spans multiple domains. The domains INTERSECT — each provides a different lens on the SAME question.
Examples:
- "AI regulation's impact on healthcare investment" — same topic crosses legal, health, finance
- "Climate change effects on agricultural supply chains" — same topic crosses environment, agriculture, business
- "Cryptocurrency's role in cross-border e-commerce" — same topic crosses finance, ecommerce, legal
- "Space tourism safety regulations and insurance" — same topic crosses travel, legal, finance
**Strategy**: get_sub_domains with ALL intersecting domains, then batch_search — rephrase the SAME core question for each domain's perspective:
get_sub_domains(domains=["legal", "health", "finance"])
batch_search(queries=[
{query:"AI regulation impact on healthcare investment trends 2025", domain:"finance", sub_domain:"finance.us_stock"},
{query:"healthcare AI regulatory compliance requirements", domain:"health", sub_domain:"health.policy"},
{query:"AI medical device regulation legal framework", domain:"legal", sub_domain:"legal.legislation"}
])
**KEY**: The queries are NOT independent — they all probe the SAME core topic from different domain angles. Do NOT treat intersecting domains as separate unrelated queries.
## Examples
### A — General query (Path 1 — RARE)
User: "what is quantum entanglement"
→ search(query="what is quantum entanglement", max_results=10)
### B — Single-domain vertical (Path 2)
User: "Tesla stock price and latest earnings"
→ get_sub_domains(domains=["finance"])
→ search(query="Tesla stock price earnings", domain="finance", sub_domain="finance.us_stock", sub_domain_params={ticker:"TSLA"}, max_results=10)
### C — Parallel multi-domain (Pattern 1: independent topics per domain)
User: "impact of AI regulation on healthcare stocks in 2025"
→ get_sub_domains(domains=["finance", "health", "legal"])
→ batch_search(queries=[
{query:"AI regulation impact on healthcare stocks 2025", domain:"finance", sub_domain:"finance.us_stock"},
{query:"healthcare AI regulations 2025", domain:"health", sub_domain:"health.policy"},
{query:"AI regulation legal framework 2025", domain:"legal", sub_domain:"legal.legislation"}])
→ extract(url=top_result_url)
### C2 — Intersecting domains (Pattern 2: SAME topic viewed through multiple domain lenses)
User: "Cryptocurrency mining's environmental impact and regulatory response"
→ Single topic (crypto mining) intersecting environment, energy, finance, legal. Cover all angles.
→ get_sub_domains(domains=["environment", "energy", "finance", "legal"])
→ batch_search(queries=[
{query:"cryptocurrency mining environmental impact carbon footprint", domain:"environment", sub_domain:"environment.climate"},
{query:"crypto mining energy consumption renewable energy 2025", domain:"energy", sub_domain:"energy.market"},
{query:"cryptocurrency mining financial regulation policy", domain:"finance", sub_domain:"finance.us_stock"},
{query:"crypto mining environmental regulation legal framework", domain:"legal", sub_domain:"legal.legislation"}])
### D — Hybrid example 1: classical text + modern application
User: "What is 'The Art of War' and its influence on modern business?"
→ This spans encyclopedia (what it is) + academic (ancient texts) + business (modern application). Hybrid.
→ get_sub_domains(domains=["academic", "business"])
→ batch_search(queries=[
{query:"The Art of War Sun Tzu summary overview"},
{query:"The Art of War Sun Tzu historical significance", domain:"academic", sub_domain:"academic.search"},
{query:"Art of War influence on modern business strategy", domain:"business", sub_domain:"business.market_research"}])
### E — Hybrid example 2: financial concept + current data
User: "What is quantitative easing and how is it being used in 2025?"
→ Encyclopedia definition + current financial data. Cover both.
→ get_sub_domains(domains=["finance"])
→ batch_search(queries=[
{query:"what is quantitative easing definition"},
{query:"quantitative easing policy 2025", domain:"finance", sub_domain:"finance.us_stock"}])
## Path 2 triggers (anything with domain relevance — including encyclopedia topics that touch specific domains):
- Structured identifiers: ticker, DOI, CVE, IATA, coordinates, patent number
- Domain-specific: stocks, papers, flights, weather, code, products, legal, health, finance, travel, gaming, film, music, fashion, ecommerce, geo, energy, environment, education, security, IP, religion, business
- Specialized data: stock price, flight status, drug info, exchange rate, AQI
- Places / locations / addresses / directions → geo domain
- Borderline encyclopedia topics with domain overlap — this category is BROAD: if the topic has ANY associated domain (classical texts → academic/business, financial theories → finance, legal concepts → legal, medical conditions → health, historical events → academic, scientific breakthroughs → academic/tech, etc.), it belongs here. Do NOT default to Path 1.
- Ambiguous / fuzzy queries — when unsure, hybrid general+vertical via batch_search is the safest default
## CRITICAL Rules:
⛔ NEVER call search with domain/sub_domain/sub_domain_params unless get_sub_domains was called first in this context.
- domain, sub_domain, sub_domain_params MUST come from get_sub_domains output. NEVER guess.
- query is pure natural language. Structured params → sub_domain_params, NEVER in query.
- ONE intent per search call. Split multi-intent queries with batch_search.
- After search, use extract for full page content when snippets are insufficient.
- When in doubt (ANY ambiguity at all), use the hybrid strategy: batch_search with 1 general query + N vertical queries. Coverage > guessing.
- ALWAYS use get_sub_domains(domains=[...]) with multiple domains when the query could match more than one domain.
- Hybrid is universal: ANY query that straddles the encyclopedia/domain boundary should use hybrid general+vertical via batch_search. If a topic has ANY associated domain (academic, finance, legal, health, tech, business, gaming, geo, etc.), do NOT default to Path 1 — hybrid covers both.
- Multi-domain intersection: when a SINGLE topic CROSSES multiple domains (not just multiple independent topics), batch_search across ALL intersecting domains — rephrase the SAME core question from each domain's angle. See Multi-Domain Strategy section.
## Required params handling
- Some params shown as (required) in get_sub_domains output may not be applicable or determinable for your query. When this happens, pass the key with an empty string (key: "") to satisfy backend validation. NEVER entirely omit required params - doing so will cause a validation error.