web_search

Search the web and return a list of results with title, URL, and snippet.

web_search

Searches the web for current information. Returns a list of results with title, url, and snippet. Use it when information may have changed since training, or for facts about the present-day world.

Parameters

Name	Type	Required	Description
query	string	yes	The search query. Keep it concise — 1-6 keywords usually works best.
allowed_domains	string[]	no	Restrict results to these domains (hostname suffix match), e.g. ["nytimes.com", "reuters.com"].
blocked_domains	string[]	no	Exclude results from these domains.
count	integer (1-20)	no	Max results to return. Default 10, max 20.
time_range	"day" | "week" | "month" | "year"	no	Recency filter — useful for news / recent changes.

Returns

A formatted text block with one result per row (title + url + snippet), ready to be reasoned over. On failure:

{
  "error": "web_search failed: ...",
  "details": {
    "query": "...",
    "http_status": 429,
    "hint": "..."
  }
}

Call from your own custom tool

// JavaScript — custom code tool (sandboxed)
export async function handle(input, ctx) {
  const results = await ctx.tools.web_search({
    query: input.topic,
    count: 5,
    time_range: 'week',
  });
  return { results };
}

# Python — custom code tool (sandboxed)
async def handle(input, ctx):
    results = await ctx.tools.web_search({
        'query': input['topic'],
        'count': 5,
        'time_range': 'week',
    })
    return { 'results': results }

Notes

• Available only when web search is enabled for your platform/agent.
• No subscriber scoping — search results are not personalized.