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

# Web Tools

# Web tools

Datzi ships two lightweight web tools:

* `web_search` — Search the web via Brave Search API.
* `web_fetch` — HTTP fetch + readable extraction (HTML → markdown/text).

These are **not** browser automation. For JS-heavy sites or logins, use the
[Browser tool](/datzi/tools/browser).

## How it works

* `web_search` calls your configured provider and returns results.
  * **Brave** (default): returns structured results (title, URL, snippet).
* Results are cached by query for 15 minutes (configurable).
* `web_fetch` does a plain HTTP GET and extracts readable content
  (HTML → markdown/text). It does **not** execute JavaScript.
* `web_fetch` is enabled by default (unless explicitly disabled).

## Choosing a search provider

| Provider            | Pros                                | Cons                       | API Key         |
| ------------------- | ----------------------------------- | -------------------------- | --------------- |
| **Brave** (default) | Fast, structured results, free tier | Traditional search results | `BRAVE_API_KEY` |

Set the provider in config:

```json5 theme={null}
{
  tools: {
    web: {
      search: {
        provider: 'brave'
      }
    }
  }
}
```

## Getting a Brave API key

1. Create a Brave Search API account at [https://brave.com/search/api/](https://brave.com/search/api/)
2. In the dashboard, choose the **Data for Search** plan (not "Data for AI") and generate an API key.
3. Run `datzi configure --section web` to store the key in config (recommended), or set `BRAVE_API_KEY` in your
   environment.

Brave provides a free tier plus paid plans; check the Brave API portal for the
current limits and pricing.

### Where to set the key (recommended)

**Recommended:** run `datzi configure --section web`. It stores the key in
`~/.datzi/datzi.json` under `tools.web.search.apiKey`.

**Environment alternative:** set `BRAVE_API_KEY` in the Gateway process
environment. For a gateway install, put it in `~/.datzi/.env` (or your
service environment). See [Env vars](/datzi/help/faq#how-does-datzi-load-environment-variables).

## web\_search

Search the web using your configured provider.

### Requirements

* `tools.web.search.enabled` must not be `false` (default: enabled)
* API key for Brave: `BRAVE_API_KEY` or `tools.web.search.apiKey`

### Config

```json5 theme={null}
{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: 'BRAVE_API_KEY_HERE',
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15
      }
    }
  }
}
```

### Tool parameters

* `query` (required)
* `count` (1–10; default from config)
* `country` (optional): 2-letter country code for region-specific results (e.g., "DE", "US", "ALL"). If omitted, Brave
  chooses its default region.
* `search_lang` (optional): ISO language code for search results (e.g., "de", "en", "fr")
* `ui_lang` (optional): ISO language code for UI elements
* `freshness` (optional): filter by discovery time
  * Brave: `pd`, `pw`, `pm`, `py`, or `YYYY-MM-DDtoYYYY-MM-DD`

**Examples:**

```javascript theme={null}
// German-specific search
await web_search({
  query: 'TV online schauen',
  count: 10,
  country: 'DE',
  search_lang: 'de'
})

// French search with French UI
await web_search({
  query: 'actualités',
  country: 'FR',
  search_lang: 'fr',
  ui_lang: 'fr'
})

// Recent results (past week)
await web_search({
  query: 'TMBG interview',
  freshness: 'pw'
})
```

## web\_fetch

Fetch a URL and extract readable content.

### web\_fetch requirements

* `tools.web.fetch.enabled` must not be `false` (default: enabled)
* Optional Firecrawl fallback: set `tools.web.fetch.firecrawl.apiKey`.

### web\_fetch config

```json5 theme={null}
{
  tools: {
    web: {
      fetch: {
        enabled: true,
        maxChars: 50000,
        maxCharsCap: 50000,
        maxResponseBytes: 2000000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        maxRedirects: 3,
        userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_7_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36',
        readability: true,
        firecrawl: {
          enabled: true,
          apiKey: 'FIRECRAWL_API_KEY_HERE',
          baseUrl: 'https://api.firecrawl.dev',
          onlyMainContent: true,
          maxAgeMs: 86400000,
          // ms (1 day)
          timeoutSeconds: 60
        }
      }
    }
  }
}
```

### web\_fetch tool parameters

* `url` (required, http/https only)
* `extractMode` (`markdown` | `text`)
* `maxChars` (truncate long pages)

Notes:

* `web_fetch` uses Readability (main-content extraction) first, then Firecrawl (if configured). If both fail, the tool
  returns an error.
* Firecrawl requests use bot-circumvention mode and cache results by default.
* `web_fetch` sends a Chrome-like User-Agent and `Accept-Language` by default; override `userAgent` if needed.
* `web_fetch` blocks private/internal hostnames and re-checks redirects (limit with `maxRedirects`).
* `maxChars` is clamped to `tools.web.fetch.maxCharsCap`.
* `web_fetch` caps the downloaded response body size to `tools.web.fetch.maxResponseBytes` before parsing; oversized
  responses are truncated and include a warning.
* `web_fetch` is best-effort extraction; some sites will need the browser tool.
* Firecrawl can be configured as an optional anti-bot fallback for web fetching.
* Responses are cached (default 15 minutes) to reduce repeated fetches.
* If you use tool profiles/allowlists, add `web_search`/`web_fetch` or `group:web`.
* If the Brave key is missing, `web_search` returns a short setup hint with a docs link.