brave-search

akaihola's avatarfrom akaihola

Structured Brave Search web queries and summarizer workflows for MCP-style agents.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 5, 2026
[Web Research]

When & Why to Use This Skill

This Claude skill provides a robust integration with the Brave Search API, enabling MCP-style agents to perform structured web queries and automated summarization. It delivers deterministic access to real-time SERP data—including web pages, FAQs, news, and videos—and features a specialized workflow to synthesize complex search results into concise, narrative summaries.

Use Cases

  • Real-time Fact-Checking: Conduct deep-dive research on current events and breaking news to provide accurate, up-to-date information beyond the model's training data.
  • Comprehensive Market Research: Gather diverse perspectives, product comparisons, and consumer discussions from across the web to build detailed market intelligence reports.
  • Automated Content Summarization: Transform multiple search results into a single, coherent summary using the Brave Summarizer API for faster information consumption.
  • Structured Data Gathering: Extract specific data types such as FAQs, news snippets, and video references to populate knowledge bases or research digests.
namebrave-search
descriptionStructured Brave Search web queries and summarizer workflows for MCP-style agents.

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.