web

web._local_search

Local Search

Effects: read

Multi-source web research with citations. Returns a synthesized answer with numbered [^1] markers and a citations array of {url, title, snippet, index}. Use for evidence-backed synthesis (competitive analysis, regulatory summary, whitepaper section). For quick fact lookups use web.search instead.

Arguments

Argument	Type	Required	Description
language	string	no	Search language hint (BCP-47, e.g. 'en', 'ru'). Defaults to 'en'. The synthesis output language matches the query language regardless. (default en)
num_sources	integer	no	How many top search results to fetch and synthesize (1-4, default 4). Lower = faster + cheaper, higher = more comprehensive. (default 4; min 1.0; max 4.0)
query	string	yes	Research question. Specific scoped questions outperform vague keywords. (min length 10; max length 2000)

web.fetch

Web Fetch

Effects: read, write

Fetches a single URL and returns its content. Use this when you have a specific URL in mind — for example, after web.search returns a link you want to read, or when the user pastes a URL.

Modes (extract):

• 'auto' (default): picks the right mode based on response content type.
• 'markdown': for HTML pages; returns cleaned markdown plus the page <title>.
• 'text': for JSON/XML/plaintext APIs; returns the raw decoded body.
• 'file': for images, PDFs, audio, video, archives, or any binary — ingests the bytes into the user's file storage and returns a file_id you can pass to messages.send (to send as an attachment), agents.add_file (to add to agent knowledge), or files.read.

Use web.fetch (not files.upload) when you need the file_id immediately for the next tool call — files.upload(source_url=…) is async and won't have the file ready in the same turn.

Use web.search (not web.fetch) when you don't have a specific URL yet and need to find one.

Arguments

Argument	Type	Required	Description
extract	string	no	How to handle the response: 'auto' (default), 'markdown' (HTML → markdown), 'text' (raw body), or 'file' (ingest as binary, return file_id). (one of auto, markdown, text, file; default auto)
url	string	yes	URL to fetch (http or https). Must be publicly reachable.

web.research

Web Research

Effects: read, external_api

Answer a research question from live web sources in one call — returns a synthesized answer with numbered [N] citation markers and a citations array of {url, title, index}. Supports recency and domain filters. Use for questions needing current, sourced information (news about a company, market state, comparisons). For raw search result links use web.search; mode='deep' runs minutes-long exhaustive research — only when explicitly requested.

Arguments

Argument	Type	Required	Description
domains	array	no	Restrict search to these domains (max 10), e.g. ['coindesk.com', 'cointelegraph.com']. Prefix with '-' to exclude a domain.
mode	string	no	Research depth: 'quick' (default, seconds, cheapest), 'pro' (harder questions, better sourcing), 'deep' (autonomous multi-step research, takes minutes — only when the user explicitly wants an exhaustive report). (one of quick, pro, deep; default quick)
query	string	yes	Research question. Specific scoped questions outperform vague keywords.
recency	string	no	Only use sources from this window. Omit for no limit. (one of day, week, month, year)

web.search

Web Search

Effects: read, external_api

Search the web for current information, news, facts, prices, or events. Use this when the user asks about something that requires up-to-date information from the internet, or when internal knowledge base doesn't have the answer. Examples: recent news, stock prices, weather, product information, current events.

Arguments

Argument	Type	Required	Description
num_results	integer	no	Number of results to return (1-10). (default 5; min 1.0; max 10.0)
query	string	yes	Search query - what to search for on the web.
search_type	string	no	Type of search: 'search' for general web, 'news' for news articles. (one of search, news; default search)
time_range	string	no	Only return results published within this window. The provider applies it, so stale articles never reach you — prefer this over judging freshness from a snippet. Applies to search_type='news'. OMIT for no age limit. (one of day, week, month, year)