| 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.
