Web search & research tools

Hania offers three complementary search tools. The agent picks per-query options (count, freshness, depth, topic, etc.) automatically — you just decide which tool(s) to enable.

• Brave Search (brave) — general live web search. Find current pages, facts, and (with result_type=news) recent news. Requires a Brave API key. Returns ranked links with snippets.
• Tavily (tavily) — AI-optimized research. search returns ranked results plus a synthesized answer (great for "what's the latest on X"); extract pulls the clean readable text of specific URLs (great for "read this page"). Requires a Tavily key (free tier available).
• DuckDuckGo Instant Answers (duckduckgo) — free, no key. Quick definitions and encyclopedic facts only; not a general web search — use Brave or Tavily for that.

Choosing a tool

• Quick definition or encyclopedic fact → DuckDuckGo (free).
• General web or news search → Brave.
• Research with a summary, or reading specific pages → Tavily.

A common research pattern: a Brave or Tavily search to find sources → Tavily extract (or the fetch-webpage tool) to read them.

Costs & limits

• Brave — free tier is metered (~$5/mo credit) and rate-limited to 1 request/second; bursts return a "rate limited" error. Paid plans bill per 1k requests.
• Tavily — free tier is 1,000 credits/month (basic search = 1 credit, advanced = 2; URL extraction = 1 credit per 5 URLs).
• DuckDuckGo — free and unlimited, but limited in capability (instant answers only).

Brave Search

Live web search. Configuration is a single field — your Brave Search API subscription token (starts with BSA), sent as the X-Subscription-Token header, stored encrypted and never shown again.

Get a key: go to api-dashboard.search.brave.com → sign in → subscribe to a plan (the entry plan includes a small monthly credit) → under API Keys, copy the subscription token (BSA…). Keep request volume to ≤1/sec on the free tier.

One action — search — with these parameters (the agent sets them):

• query (required) — the search query.
• count — 1–20 (default 5).
• freshness — pd / pw / pm / py (past day / week / month / year).
• result_type — web or news (news returns recent news articles).
• country — 2-letter code, e.g. us.
• safesearch — off / moderate / strict (default moderate).

Returns {type, results:[{title, url, description, age}]} (a projected shape, not raw Brave JSON).

Tavily

AI-optimized search and extraction. Configuration is a single field — your Tavily API key (starts with tvly-), stored encrypted and never shown again.

Get a key: go to app.tavily.com → sign up (no card for the free tier) → API Keys → copy your key (tvly-…). The free tier gives 1,000 credits/month.

Two actions (the agent picks one and its parameters):

• search — query (required), search_depth (basic / advanced), topic (general / news / finance), time_range (day / week / month / year), max_results (1–20), include_domains / exclude_domains. Returns {answer, results:[{title, url, content, score, published_date}]} — always with a synthesized answer.
• extract — urls (required, ≤20), optional query to rerank. Returns {results:[{url, raw_content}], failed_results} as clean markdown.

DuckDuckGo Instant Answers

Free and keyless — nothing to set up; it's always available to every bot. One action — search with a query — returning {abstract, source, url, answer, definition, related_topics:[{text, url}]}. It provides definitions and encyclopedic facts only, not general web search; use Brave or Tavily for real searches.

Classification & lifecycle

All three are read-only, so the destructive / sends-data-externally classification flags don't apply (they ship unset). Each is post-call-hook eligible — e.g. "after the call, look up the latest on the topic and email a summary."