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

# Web Search Tool

> Configure the Web Search Tool, the Workspace Tool that lets the LLM search the web using the Tavily search API.

The **Web Search Tool** (`web_search`) is a mAItion Workspace Tool. It gives the LLM one on-demand function — searching the live web — backed by the [Tavily](https://tavily.com) search API.

## What It Does

`web_search(query)` takes a single required search string and returns a formatted block: each result's title, URL, and a content snippet, plus (when available and enabled) Tavily's own synthesized answer to the query.

For each result that has a URL, the tool emits a `source` citation event so it appears as a clickable reference under the response.

## Valves

| Field               | Required | Default     | Description                                                                                                                                                         |
| ------------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tavily_api_key`    | **yes**  | `""`        | Tavily API key (starts with `tvly-`). Get one at [tavily.com](https://tavily.com). Empty by default — the tool returns an error and will not run until this is set. |
| `max_results`       | no       | `5`         | Maximum number of search results per query. Valid range 1–20, enforced at the schema level. Higher values are slower.                                               |
| `search_depth`      | no       | `"basic"`   | `"basic"` is fast and cheap; `"advanced"` is more thorough and returns richer content.                                                                              |
| `include_answer`    | no       | `true`      | Include Tavily's synthesized answer to the query in the output.                                                                                                     |
| `topic`             | no       | `"general"` | Search content category: `"general"`, `"news"` (recent headlines), or `"finance"` (market data).                                                                    |
| `timeout`           | no       | `30`        | HTTP request timeout in seconds. Valid range 1–120 (120 is Tavily's own hard cap), enforced at the schema level.                                                    |
| `max_content_chars` | no       | `4000`      | Maximum characters of content per result. Valid range 100–50,000, enforced at the schema level. Longer snippets are truncated.                                      |

Every numeric valve above has real schema validation — an out-of-range value is rejected, not silently clamped. Tool id: `web_search`. Display name: "Web Search". Valves can be edited after install from **Workspace → Tools** in mAItion.

## Enabling via ENV

This tool is opt-in, with a single-condition gate. Set in `.env`:

```bash theme={null}
TOOL_WEB_SEARCH_ENABLED=True
TOOL_WEB_SEARCH_API_KEY=
```

* `TOOL_WEB_SEARCH_ENABLED=True` is the only required condition to install.
* `TOOL_WEB_SEARCH_API_KEY` is optional for install, but set it at the same time as `TOOL_WEB_SEARCH_ENABLED` in practice — without it, the tool installs but can't run any search until you set the `tavily_api_key` valve manually afterward. If left unset, the tool still installs, with `tavily_api_key` at its empty default, and the entrypoint script logs a note pointing to Workspace → Tools for manual configuration. Nothing fails and nothing is skipped.
* Only `tavily_api_key` is ever set from ENV. The other six valves (`max_results`, `search_depth`, `include_answer`, `topic`, `timeout`, `max_content_chars`) are configured only through the UI, or left at their defaults above.

<Note>
  This installs only during first-start initialization — the setup that runs only once, the first time the container boots, gated on a marker file. Setting the ENV flag on an already-running instance does not install it retroactively. Set the flag before the container's first boot, or add the tool manually afterward from the admin UI.
</Note>

## Troubleshooting

| Symptom                                                                    | Cause                                                                                                                                                                                                                     |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Error: tavily_api_key is not configured.`                                 | The `tavily_api_key` valve is empty. Set it via ENV (see above) or manually from Workspace → Tools in mAItion.                                                                                                            |
| `Error: search query cannot be empty.`                                     | An empty query string was passed to the tool.                                                                                                                                                                             |
| `Error: Tavily API key is invalid. ...`                                    | The configured key was rejected by Tavily. Check `tavily_api_key`.                                                                                                                                                        |
| `Error: Tavily usage limit exceeded ...`                                   | Tavily's rate limit or quota was hit. Try again later, or check your Tavily plan.                                                                                                                                         |
| `Error: Tavily rejected the request (...)`                                 | Tavily returned a bad-request error — the message includes Tavily's own detail. Check the query and valve values.                                                                                                         |
| `Error: Tavily search timed out after N seconds.`                          | The request exceeded the `timeout` valve. Consider raising it (up to 120).                                                                                                                                                |
| `Error: unexpected error during web search. ...`                           | An unhandled error occurred during the search call. Check server logs.                                                                                                                                                    |
| No output at all, or a raised exception instead of a returned error string | The Tavily client failed to import or construct — this happens before the tool's own error handling starts, so it is not converted into a graceful error message. Check that the `tavily-python` dependency is installed. |
| `No web results found for '<query>'.`                                      | Not an error — the search ran but Tavily returned nothing.                                                                                                                                                                |