> ## Documentation Index
> Fetch the complete documentation index at: https://agentheya.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```json theme={null}
{
  "error": "web_search failed: ...",
  "details": {
    "query": "...",
    "http_status": 429,
    "hint": "..."
  }
}
```

## Call from your own custom tool

```js theme={null}
// 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 theme={null}
# 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.