Hare/yoi
1
1
Fork 0
Code Actions Packages Releases Activity

ticket: add Brave Search API notes

Browse Source
This commit is contained in:
Keisuke Hirata 2026-05-29 17:31:33 +09:00
parent 51e5354afe
commit 37ead9c1a8
No known key found for this signature in database
1 changed files with 19 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
work-items/open/20260528-152959-web-search-fetch-tools/item.md
View File

@ -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: <api key>`; 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.