search-strategy

name	search-strategy
description	Strategy for routing Farsight's web_search / web_fetch / web_docs tools across their providers. Guides which provider fits which intent, how to react to fallback/errors, when to summarize, and how to cite. Auto-triggered when any Farsight web tool is relevant.

Farsight search strategy

Farsight — reach beyond the horizon for knowledge.

Pick the tool by intent

Intent	Tool
Find pages / current info / unknown URLs	web_search
Read or extract from a known URL	web_fetch
Canonical, version-pinned library/SDK docs	web_docs (prefer over web_search for libraries)

Flow: web_search → web_fetch the best hit. Or skip the second call by using a search+content provider (Exa type:deep, or Firecrawl).

web_search — provider choice

Provider	Use when	Free tier	Returns
brave (default)	General / news / keyword / current events	~$5/mo credits	links + snippets
exa	Semantic / "find similar" / research / technical	20,000/mo	links; full content with type:"deep" or livecrawl:"preferred"
tavily	You want a synthesized answer, not a link list	1,000/mo	result[0] is the synthesized answer; then cited links
serper	You want Google's ranking / Knowledge Graph	2,500 (one-time)	organic links; KG entry prepended if present
searxng	Privacy / no-key (needs a self-hosted instance)	self-hosted	aggregated links

Rules:

• Default brave for general queries. exa for semantic/research. tavily for "what is X" answer-style. serper when Google ranking matters.
• allowed_domains / blocked_domains are mutually exclusive. Use them to focus (e.g. docs site, or exclude SEO spam).
• Pass provider only when intent clearly maps above; otherwise let the default run.
• On keys_exhausted error: that provider's keys are cooling down / disabled. Retry the same query with a different provider, or wait.

web_fetch — provider choice

Provider	Use when	Cost
local (default)	Static / server-rendered pages (docs, blogs, raw files)	free, zero-dep
firecrawl	JS-rendered SPAs, anti-scrape, complex pages	1,000 credits/mo (2 concurrent on free)
jina	Lightweight URL→markdown; large keyless free tier	free (key optional)

Behavior you should know:

• Auto-fallback: local → firecrawl (then jina) automatically when the page is a JS shell, or returns 401/403/405, or a non-2xx + SPA framework markers. You usually don't need to force this.
• Force external for known JS-heavy sites: pass provider:"firecrawl" to skip the local attempt (saves a wasted round-trip).
• Cross-host redirect: the tool returns a redirect message instead of following. Re-call web_fetch with the redirectUrl it gives you. (Same-host redirects are followed automatically.)
• SSRF: the tool refuses intranet URLs (localhost, 192.168.x, 169.254.169.254 metadata, etc.) — don't try to fetch those.

prompt = small-model summary (save tokens)

Pass prompt:"<what to extract>" to run the fetched content through a cheap small model (default deepseek-v4-flash, ~$2e-6/call) and get a concise extract instead of the full page.

• Use it for long pages where you need specific info (saves context tokens).
• Skip it for short pages or when you need the raw content verbatim (code, exact text).
• Summary is re-run per prompt; raw content is cached 15 min.

web_docs — library docs

Prefer web_docs over web_search for canonical library/API docs (version-pinned, accurate — better than scraping a doc site).

• Pass a library name ("react") — auto-resolved — or a Context7 ID ("/vercel/next.js") to skip resolution.
• Add query to focus (e.g. "useState"), tokens to cap size (default 10000).
• Keyless works (lower rate); a configured key unlocks more.

Errors & retries

• 429 / keys_exhausted: provider keys cooling down. For web_search, retry with another provider. For web_fetch, the tool already auto-fell-back; if that also fails, try the other external provider explicitly.
• 401/403 (auth): a key is invalid — surfaced, that key disabled. Rotate to another provider.
• timeout / 5xx: transient; retry once.
• Provider status is in the result details (poolExhausted, poolStatus).

Citations (mandatory)

After using any search/fetch result in your answer, include a Sources: section with markdown hyperlinks:

Sources:
- [Title](https://example.com/a)
- [Title](https://example.com/b)

Never skip sources. Use the current year in search queries for recent info (the tool reminds you of the current month).

Cost awareness

• Prefer local fetch and brave/exa search (generous free tiers) when they suffice.
• Reserve firecrawl for JS/anti-scrape pages; free plan = 2 concurrent, so don't fire many in parallel.
• Use prompt summary on long pages to save context tokens.
• web_docs is usually cheaper and more accurate than web_search+web_fetch for library questions.