Web Research Rules — Use webscraper_search_hint Proactively

Rule: Search Before Asking

Before asking Patrick for information about a library, framework, API, technology, or error — always try webscraper_search_hint first.

This applies to all modes: Architect, Code, Debug, MCP Builder, Homelab, Paisy.

Why

webscraper_search_hint uses Brave Search — no API key, no setup, always available
Brave returns real results without CAPTCHA or consent walls (Google/DuckDuckGo both block)
Handles special characters correctly (C++, &, %, etc. — URL-encoded automatically)
The hint field gives immediately actionable title + URL + snippet without further calls

The Two-Step Pattern

Step 1: webscraper_search_hint("2-3 keyword query") → structured results + hint string
Step 2: webscraper_fetch(best_url, max_chars=8000)   → full page content

Never skip Step 1. It costs one tool call and often reveals the exact page to read.

Step 1 Output

The tool returns:

hint — pipe-separated "Title (url): snippet[:120]" — read this first
results[] — array of {title, url, snippet} — pick the most relevant URL
search_url — the Brave search URL used (useful for debugging)
result_count — number of results returned

Step 2 Output

webscraper_fetch(url) returns full page as Markdown. Use max_chars to control size (default 5000; use 8000–12000 for deep doc reads).

Mode-Specific Guidance

🏗️ Architect Mode

Before designing any system or feature: search for existing patterns, reference architectures, and official docs
Example: planning a new MCP server → webscraper_search_hint("FastMCP server patterns 2025")
Example: choosing between two libraries → search both and read their official comparison pages

🪲 Debug Mode

Search the exact error message before forming hypotheses
Example: webscraper_search_hint("sqlite3 ProgrammingError Cannot operate closed database Python")
If the error is long, take the most distinctive phrase (2-5 words) as the query

💻 Code Mode

Before implementing a feature using an unfamiliar API: search the official docs URL pattern first
Example: webscraper_search_hint("httpx async client connection pool settings")

🔧 MCP Builder Mode

Check FastMCP changelog/docs before implementing new patterns
Example: webscraper_search_hint("FastMCP tool decorator async 2025")
Example: webscraper_search_hint("FastMCP context lifespan")

🏠 Homelab Mode

Look up Docker/TrueNAS configs, package versions, service docs before asking Patrick
Example: webscraper_search_hint("Gitea webhook payload format")

Query Crafting Tips

✅ Good queries	❌ Bad queries
`"httpx timeout settings"`	`"how do I configure httpx timeouts in Python async code"`
`"FastMCP tool decorator"`	`"mcp server python tool registration method"`
`"sqlite WAL mode enable"`	`"sqlite performance mode for concurrent reads"`
`"Brave Search API no key"`	`"search engine that works without api key or captcha"`

Use 2–4 keywords, not full sentences
Prefer library/framework name + specific feature
For errors: distinctive phrase from the message, not the full stack trace

Known Limitations

Reddit / Stack Overflow snippets — these platforms block snippet extraction; you may get empty snippets. The URL is still valid — fetch it directly if needed.
Brave CSS selector fragility — Brave uses Svelte-generated class names that change. If webscraper_search_hint returns 0 results unexpectedly, the scraper's CSS selectors may need updating. Last verified working: 2026-04-05.
Use sparingly — one search call per research task to orient; then fetch specific pages. Don't call it in a loop.

Anti-Patterns to Avoid

❌ Asking Patrick "what's the FastMCP syntax for X?" before searching
❌ Designing architecture without looking up existing solutions first
❌ Forming a debug hypothesis without searching the error message
❌ Writing code against an API from memory without verifying current docs
❌ Calling webscraper_search_hint more than 2-3 times for the same topic (broaden/narrow the query instead)

4.2 KiB Raw Blame History Unescape Escape