From 37ead9c1a829ac964fe7e9c016127a0d7c8f89c4 Mon Sep 17 00:00:00 2001 From: Hare Date: Fri, 29 May 2026 17:31:33 +0900 Subject: [PATCH] ticket: add Brave Search API notes --- .../item.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/work-items/open/20260528-152959-web-search-fetch-tools/item.md b/work-items/open/20260528-152959-web-search-fetch-tools/item.md index 93127615..58f43bae 100644 --- a/work-items/open/20260528-152959-web-search-fetch-tools/item.md +++ b/work-items/open/20260528-152959-web-search-fetch-tools/item.md @@ -44,6 +44,25 @@ This should be implemented as normal built-in tools, not as hidden context injec - Provide clear errors for timeout, DNS/network failure, unsupported content, blocked host/scheme, and truncation. - Prompts/tool descriptions should tell the model when to use WebSearch vs WebFetch and that fetched content may be stale/untrusted. +## Brave Search API notes + +`https://github.com/brave/brave-search-mcp-server` was checked as the reference implementation. It is an MCP server around Brave Search APIs, not a general page fetcher. + +Useful details to mirror for `WebSearch`: + +- Use `https://api.search.brave.com/res/v1/web/search` for the first provider. +- Authenticate with `X-Subscription-Token: `; Insomnia should read the key from a configured environment variable such as `BRAVE_SEARCH_API_KEY` rather than storing raw secrets in the manifest. +- Send `q` for the query. Validate query length up front: Brave's MCP server caps at 400 characters and 50 words. +- Expose a small initial subset of Brave parameters rather than the full API surface: + - `count` / result limit: 1-20. + - `offset`: 0-9 if pagination is included. + - `country`, `search_lang`, `ui_lang` as optional config/defaults, not necessarily per-call in the first version. + - `safesearch`: default `moderate`. + - `freshness`: optional (`pd`, `pw`, `pm`, `py`, or date range) can be added if easy, but is not required for the first cut. +- Format output conservatively. The MCP server reduces web results to `{ url, title, description, extra_snippets }` and optionally emits FAQ, discussions, news, and videos. Insomnia's first version should return the core web result fields plus provider metadata, and may ignore non-web result buckets unless explicitly requested later. +- Brave's public docs/reference include an LLM Context endpoint (`/res/v1/summarizer/llm_context`) that returns extracted snippets/content with token and per-URL limits. This is useful as a future `WebContext`/enhanced search provider, but should not replace `WebFetch` in the first implementation because it is provider-specific and not a direct URL fetch tool. +- Brave MCP defines a nominal free-plan rate limit of 1 request/second and 15,000/month and does not implement robust self-throttling. Insomnia should at least surface HTTP 429/rate-limit errors clearly; local throttling can be a follow-up unless implementation is cheap. + ## Acceptance criteria - `WebSearch` and `WebFetch` are registered built-in tools when enabled/configured.