## Overview

**Web search** gives the bot two tools for querying the **public internet** — things it does not know
and that do not live in your account: news, market prices, public company data, documentation,
anything that changed after the model was trained.

| Tool | What it does |
|---|---|
| **`web_search`** | Searches the web and returns ranked results with the **title, URL and a snippet** of each page. |
| **`web_fetch`** | Reads the **full text** of specific pages by URL — after a search when the snippet is not enough, or whenever the bot already has the URL. |

Both are **read-only** and **send the contact nothing**: they return text to the model, which then
decides what (if anything) to say. That is also why they stay available when the bot delegates to a
sub-agent.

> For your **account's own** content — contacts, deals, catalog, history — the bot has dedicated
> tools, and the **knowledge base** holds your material. Web search is for what lives **outside**.

## Prerequisites

- **Maestro enabled** and a configured bot.
- A **Tavily API key** available to the bot (see "The key" below).
- The **`web_search`** and/or **`web_fetch`** tools enabled in the bot's tools grid — without them,
  nothing in this section has any effect.

## Step by step

1. In the bot's configuration, open the **Tools** grid and enable **Search the web** and/or **Read a
   web page** (**Knowledge** category).
2. Scroll to the **Web search** section. If neither tool is on, a notice tells you nothing there will
   take effect yet.
3. Adjust **Search depth** and **Results per search**.
4. To restrict it, fill in **Search only these domains** and/or **Never these domains**.
5. **Save.**

To switch search off entirely, **disable both tools** in the grid. Your settings are kept for
whenever you turn them back on.

## Settings & options

| Option | What it does | Default |
|---|---|---|
| **Search depth** | **Basic** or **Advanced**. Advanced reads more of each page and matches better, but **costs more credits** per call. It also applies when `web_fetch` reads a page. | Basic |
| **Results per search** | A ceiling of **1 to 20**. Empty = the tool default (**5**). | Empty (5) |
| **Search only these domains** | Restricts search to those domains. Empty = the whole web. | Empty |
| **Never these domains** | Always blocks those domains. | Empty |

### How the two domain lists combine

They do **not** work the same way, and the difference is deliberate:

- **Search only these domains** is a **restriction**. When you fill it in, the bot's own list is
  ignored — it **cannot** search anywhere else, not even if it asks. A restriction the model can
  widen is not a restriction.
- **Never these domains** is a **blocklist**. Your domains always apply, and the bot may still add
  more for a specific query.

Type domains separated by commas or newlines. `https://`, `www.` and any path after the slash are
stripped automatically — Tavily matches **hosts**, so `https://example.com/pricing` becomes
`example.com`.

### What the bot decides (and you do not)

- **How many results to request** for that query: it may ask for **fewer** than your ceiling, never
  more.
- The **topic** of the query (general, news or finance) and the **time window** (past day, week,
  month or year), decided per question. Neither has a fixed per-bot field today — the default is
  **general**, with no time filter.
- **Which URLs to read** with `web_fetch` — at most **5 per call**.

### The key (Tavily)

Search needs a Tavily key. It is looked up in this order:

1. The **bot's own** key (API keys section, provider **tavily**).
2. Your **account's** key, under Integrations.
3. The **installation's** key, configured by the operator.

With none of them, the tools reply that search is not configured and the bot carries on with what it
already knows — **the conversation does not break**.

## Use cases

- **Technical support** — check a partner's public documentation before advising the customer.
- **Pre-sales** — look up public data about the contact's company to qualify better.
- **News and prices** — answer about something that changed after the model was trained.
- **Restricted base** — put your own site and documentation in **Search only these domains**: the bot
  searches **only** there, like an internal search over public content.

## Tips, limits & best practices

- **Every search consumes Tavily credits.** Advanced depth and a high result count multiply the
  spend — start on **Basic** with the default of 5.
- An extra result is also extra **context** in the turn: 20 results can push the conversation's own
  information out.
- `web_fetch` reads at most **5 pages per call**, and each page's text is **truncated** to fit the
  turn.
- A URL that could not be read is **reported** to the bot, not silently dropped — so it does not
  answer as if it had checked.
- The public web is **not a source of truth about your operation**. For your prices, policies and
  lead times, use the **knowledge base**.
- Pair it with **turn verification** if you want to hold replies that claim something the turn did
  not establish.

## Troubleshooting

- **"I configured everything and the bot never searches"** — are the **`web_search`/`web_fetch`**
  tools enabled in the grid? The notice in the section tells you when they are not.
- **"Search is not configured"** — there is no Tavily key at any of the three levels.
- **"The API key is invalid"** — the key exists but was rejected; issue a new one at Tavily.
- **"The plan limit was reached"** — the Tavily account is out of credits.
- **"Search is rate limited right now"** — too many calls in a short window; it retries later.
- **"It searched a site I did not want"** — add the domain to **Never these domains**, or lock
  everything down with **Search only these domains**.
- **"Results come from another country/language"** — make the query more specific in the bot's
  instructions and restrict by domain.

## See also

- [What Maestro AI and the Account Brain are](/hc/ajuda/articles/maestro-brain-overview-en)
- [Maestro tools by module](/hc/ajuda/articles/maestro-brain-ferramentas-maestro-por-modulo-en)
- [Knowledge base and ontology](/hc/ajuda/articles/maestro-brain-base-de-conhecimento-e-ontologia-en)
- [Verifying what the bot claims](/hc/ajuda/articles/maestro-brain-verificacao-do-que-o-robo-afirma-en)