# Brave Search

> Search the web using Brave Search API. Use when the user asks to "search the web", "look up current information", "find news about", "research a topic online", "check prices online", or needs up-to-date facts that may not be in the model's training data. Requires BRAVE_SEARCH_API_KEY. Supports structured web results (pages, FAQs, news, videos) and an optional AI summarizer.

- Skill: `akaihola/brave-search` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add akaihola/brave-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/akaihola/brave-search/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: akaihola (https://skillmd.com/u/akaihola)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/akaihola/brave-search

---


# Purpose

Provide deterministic wrappers around Brave Search’s web and summarizer endpoints. Use the web workflow to retrieve structured SERP data (web pages, FAQs, discussions, news, videos). Use the summarizer workflow to turn Brave’s aggregated findings into a concise narrative when the subscription permits summarization.

# When to Use

- Run web fact-finding on current events, product comparisons, research digests, or perspective gathering when Google/Bing responses are insufficient.
- Request the summarizer only after a prior web search produced a `summarizer_key`, and the user explicitly wants a Brave-generated synthesis.

# Configuration Requirements

- Set `BRAVE_SEARCH_API_KEY` in the execution environment. The value populates the `X-Subscription-Token` header.
- Prefer secure storage through the project’s secrets tooling before launching the script.
- All invocations must use `uv run` to respect the project’s Python environment.

# Workflows

## A. Web Search (results only)

1. Prepare JSON containing at least `"query"`. Optional keys include `country`, `search_lang`, `ui_lang`, `count`, `offset`, `safesearch`, `freshness`, `text_decorations`, `spellcheck`, `result_filter`, `goggles`, `units`, and `extra_snippets`.
2. Run `uv run scripts/brave_search.py web --params-json '<JSON>'`.
3. Consume `web_results`, `faq_results`, `discussions_results`, `news_results`, and `video_results` from the JSON output. Each section mirrors the Brave MCP tool’s simplified records.
4. If `ok` is `false` with `"No web results found"`, broaden or restate the query before retrying.

## B. Web Search with Summarizer Key

1. Follow workflow A but add `"summary": true` to the JSON payload.
2. The script automatically requests `result_filter=summarizer`. Inspect the response’s `summarizer_key`.
3. Store the key and cite the original `web_results` when answering detailed questions while preparing for a summarizer follow-up.

## C. Summarizer

1. Ensure a recent workflow B run produced a `summarizer_key`.
2. Build JSON like `{"key": "<summarizer_key>", "entity_info": false, "inline_references": true}`. Optional overrides: `poll_interval_ms` (default 50) and `max_attempts` (default 20).
3. Run `uv run scripts/brave_search.py summarizer --params-json '<JSON>'`.
4. Use `summary_text` as the main synthesis. Supplement with `enrichments`, `followups`, and `entities_infos` for deeper context or suggested next steps.
5. If the summarizer fails, rely on the previously collected `web_results` to craft a manual answer.

# Error Handling and Fallbacks

- Missing API key: the script emits `ok: false` with an explicit description; set the environment variable and rerun.
- HTTP or Brave-side errors: review the `details` object, adjust parameters, or pause if throttled.
- Summarizer polling timeout: rerun the web search to refresh the key, or answer using raw web data.

# References

- `references/brave_web_search_params.md` — exhaustive parameter definitions and sample payloads.
- `references/brave_summarizer_workflow.md` — polling logic, summary message schema, and tuning guidance.
- `references/brave_search_examples.md` — end-to-end scenarios demonstrating combined web and summarizer usage.