# WebSearchShorthand

Web search tool using OpenAI Responses API syntax. Automatically converted to openrouter:web_search.


## Fields

| Field                                                                                                                                                                                                                                                                                          | Type                                                                                                                                                                                                                                                                                           | Required                                                                                                                                                                                                                                                                                       | Description                                                                                                                                                                                                                                                                                    | Example                                                                                                                                                                                                                                                                                        |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                                                                                                                                                                                                                                                                                         | [components.WebSearchShorthandType](../components/websearchshorthandtype.md)                                                                                                                                                                                                                   | :heavy_check_mark:                                                                                                                                                                                                                                                                             | N/A                                                                                                                                                                                                                                                                                            |                                                                                                                                                                                                                                                                                                |
| `engine`                                                                                                                                                                                                                                                                                       | [Optional[components.WebSearchShorthandEngine]](../components/websearchshorthandengine.md)                                                                                                                                                                                                     | :heavy_minus_sign:                                                                                                                                                                                                                                                                             | Which search engine to use. "auto" (default) uses native if the provider supports it, otherwise Exa. "native" forces the provider's built-in search (parameters like max_results, search_context_size, and domain filters are not forwarded to the provider). "exa" forces the Exa search API. | auto                                                                                                                                                                                                                                                                                           |
| `max_results`                                                                                                                                                                                                                                                                                  | *Optional[float]*                                                                                                                                                                                                                                                                              | :heavy_minus_sign:                                                                                                                                                                                                                                                                             | Maximum number of search results to return per search call. Defaults to 5. Only applies when using the Exa engine; ignored with native provider search.                                                                                                                                        | 5                                                                                                                                                                                                                                                                                              |
| `max_total_results`                                                                                                                                                                                                                                                                            | *Optional[float]*                                                                                                                                                                                                                                                                              | :heavy_minus_sign:                                                                                                                                                                                                                                                                             | Maximum total number of search results across all search calls in a single request. Once this limit is reached, the tool will stop returning new results. Useful for controlling cost and context size in agentic loops.                                                                       | 20                                                                                                                                                                                                                                                                                             |
| `search_context_size`                                                                                                                                                                                                                                                                          | [Optional[components.WebSearchShorthandSearchContextSize]](../components/websearchshorthandsearchcontextsize.md)                                                                                                                                                                               | :heavy_minus_sign:                                                                                                                                                                                                                                                                             | How much context to retrieve per result. Defaults to medium (15000 chars). Only applies when using the Exa engine; ignored with native provider search.                                                                                                                                        |                                                                                                                                                                                                                                                                                                |
| `user_location`                                                                                                                                                                                                                                                                                | [Optional[components.WebSearchShorthandUserLocation]](../components/websearchshorthanduserlocation.md)                                                                                                                                                                                         | :heavy_minus_sign:                                                                                                                                                                                                                                                                             | Approximate user location for location-biased results.                                                                                                                                                                                                                                         |                                                                                                                                                                                                                                                                                                |
| `allowed_domains`                                                                                                                                                                                                                                                                              | List[*str*]                                                                                                                                                                                                                                                                                    | :heavy_minus_sign:                                                                                                                                                                                                                                                                             | Limit search results to these domains. Only applies when using the Exa engine; ignored with native provider search.                                                                                                                                                                            |                                                                                                                                                                                                                                                                                                |
| `excluded_domains`                                                                                                                                                                                                                                                                             | List[*str*]                                                                                                                                                                                                                                                                                    | :heavy_minus_sign:                                                                                                                                                                                                                                                                             | Exclude search results from these domains. Only applies when using the Exa engine; ignored with native provider search.                                                                                                                                                                        |                                                                                                                                                                                                                                                                                                |
| `parameters`                                                                                                                                                                                                                                                                                   | [Optional[components.WebSearchShorthandParameters]](../components/websearchshorthandparameters.md)                                                                                                                                                                                             | :heavy_minus_sign:                                                                                                                                                                                                                                                                             | N/A                                                                                                                                                                                                                                                                                            |                                                                                                                                                                                                                                                                                                |