wigolo
wigolo is a local-first web intelligence MCP server for AI agents — no API keys, no cloud, no metered costs. All cache, embeddings, and models are stored locally under ~/.wigolo/.
search– Multi-engine web search (18 engines) with rank fusion, ML reranking, and explainable per-result scores. Supports parallel multi-query arrays, category filters (news, code, docs, papers, images), date ranges, domain scoping, and optional LLM-synthesized answers.fetch– Load any URL via a tiered router (HTTP → TLS-impersonation → headless browser) that auto-escalates on anti-bot challenges. Supports JS rendering, browser actions (click, type, scroll, screenshot), authenticated sessions, section extraction, and site-specific extractors (Reddit, YouTube, Amazon). Returns clean markdown and metadata.crawl– Multi-page crawl from a seed URL using BFS, DFS, sitemap, or map-only strategies. Respects robots.txt, enforces per-domain rate limits, deduplicates content, and caches all pages locally.extract– Extract structured data from a URL or raw HTML: CSS selectors, tables, metadata (OG/JSON-LD), named schemas (Article, Recipe, Product, CodeSnippet, Paper), custom JSON Schema fields, and brand identity (logo, colors, fonts, social links).cache– Full-text search (BM25/FTS5) or hybrid semantic+keyword search over previously fetched content without hitting the network. Supports URL pattern filtering, date filtering, cache stats, clearing, and change detection.find_similar– Find pages similar to a URL or concept via 3-way fusion of keyword, semantic embeddings, and live web signals.research– Autonomous multi-step research: decomposes a question into sub-queries, fetches sources in parallel, and synthesizes a cited markdown report. Supports quick/standard/comprehensive depth and custom output schemas.agent– Autonomous data-gathering loop: plans queries and URLs from a natural-language prompt, executes in parallel within a time/page budget, optionally extracts structured fields, and synthesizes results with full step transparency.diff– Compute diffs between two markdown bodies or two URL fetches, with unified patch, structured hunks, or summary output at line, word, or section granularity.watch– Schedule lazy re-checks of a URL and surface diffs on change. Jobs persist across sessions and support inline or webhook notifications.
Optional LLM synthesis (for research, agent, and search format=answer) can be connected via Gemini, OpenAI, Anthropic, Groq, or a local Ollama instance.
Adds Brave Search as a search engine adapter, improving retrieval diversity and result consensus.
Integrates GitHub code search with an API token, increasing rate limits and enabling private repository results.
Supports Google as an optional cloud LLM provider for synthesis, configured via GOOGLE_API_KEY.
Supports local LLM inference via Ollama for synthesis, keeping all processing on-device.
Integrates SearXNG as an optional fallback search backend for enhanced engine coverage.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@wigoloResearch the benefits of local-first web intelligence"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Local-first web intelligence for AI agents — no keys, no cloud, no metered bill.
works with Claude Code · Cursor · Codex · Gemini CLI · OpenCode · VS Code · Windsurf · Zed · Antigravity and beyond LangChain · CrewAI · LlamaIndex · Vercel AI SDK · n8n & self-hosted agents · any MCP client · plain REST
Quickstart · Tools · Why wigolo · Sponsors · Benchmark · Docs · Examples · Feedback · FAQ
New features and updates ship steadily. Follow @yourtowhid on X for all of it and new ways to use wigolo, and reach out there for collaborations or feedback · also on LinkedIn
wigolo gives an AI agent one surface for everything web-related: search, fetch, crawl, extract, cache, find-similar, research, and autonomous gather loops. It runs wherever your agent runs — as an MCP server next to your coding agent, as a REST/MCP endpoint on the box where your self-hosted agents live, or embedded through an SDK inside your own app. The core tools need no API keys, nothing it touches leaves ~/.wigolo/, and no bill grows with how much your agent thinks.
Quickstart
npx wigolo init # set up the local engine — any system
npx wigolo init --agents=claude-code,cursor # …or set up + wire your day-to-day agents in one commandRequires Node ≥ 20 and ~1.5 GB of free disk on macOS, Linux, or Windows. Bare init sets up the local engine: it downloads the browser engine and on-device models, runs a health check, and reports each component. Adding --agents wires the named agents in the same run, so a coding agent you use daily is ready in one command.
Supported agents —
--agentstakes any ofclaude-code·cursor·codex·gemini-cli·opencode·vscode·windsurf·zed·antigravity(comma-separated); wigolo writes the MCP config and, where supported, instructions for each.Any other setup — any MCP client, agent framework, or self-hosted agent registers
npx -y wigoloin its own MCP config. The installation guide has the exact config block for every client, plus Docker, Homebrew, and single-file-binary channels.More on the way — the supported list keeps growing, and a PR to add your agent is welcome; see CONTRIBUTING.md.
Interactive setup —
--interactiveis a plain-text flow;--wizardis the full terminal TUI.Defer downloads —
--no-warmupwaits until first use. A failed component download never fails setup; init reports what's not ready with the exact fix and still completes.
init is unattended by default, so it's safe in scripts and CI, and any setup problem surfaces right here in the per-component report, before your agent's first call. Search, fetch, crawl, extract, cache, and find-similar work with no API key. Check it's healthy anytime:
npx wigolo doctorTo remove everything cleanly, run npx wigolo config --uninstall --yes. You can also paste the installation guide into any AI assistant and let it do the setup; it's written to be self-contained.
Recommended — a free key for research & agent
Search, fetch, crawl, extract, cache, and find-similar are fully keyless. research, agent, and search format=answer use an LLM to write the synthesized, cited answer. Without one they hand back a raw brief and evidence for your agent to assemble. A free Gemini key turns that into a finished answer:
export WIGOLO_LLM_PROVIDER=gemini
export GEMINI_API_KEY=<free-key> # grab one at aistudio.google.com/apikey — the free tier is plentyAny provider works (anthropic · openai · groq), or stay fully local and keyless with WIGOLO_LLM_PROVIDER=ollama (or any OpenAI-compatible URL). Set it in your shell or your agent's MCP env block. Providers, models, and the keyless local-model ladder are in the configuration guide.
Related MCP server: myscrape
What your agent gets back
Every search result is evidence the agent can act on. It carries a verbatim excerpt pinned to its exact position in the source, a citation ID the agent can quote, and a score it can inspect (abridged real shape):
{
"results": [{
"title": "Logical replication - PostgreSQL docs",
"url": "https://www.postgresql.org/docs/current/logical-replication.html",
"excerpt": "Logical replication is a method of replicating data objects…",
"citation_id": "src-1",
"source_span": { "start": 1042, "end": 1305 }, // byte-exact provenance
"evidence_score": { "final": 0.86, "semantic": 0.91, "lexical": 0.78, "engine_consensus": 3 }
}],
"citations": [{ "id": "src-1", "url": "…" }],
"freshness_signal": { "published": "2026-05-12", "confidence": "high" }
}Weak results get flagged as junk by wigolo's own scorer. Failed engines are reported and stale cache is labeled, so the agent always knows what it's standing on. Full response contracts per tool are in the tools reference.
Tools
Tool | What it does |
🔎 | Multi-engine web search (18 direct adapters) with rank fusion, ML reranking, and an explainable per-result score. Pass a query array for parallel breadth. Scope by domain and time range, match an exact phrase, or return image results. |
📄 | Load one URL through a tiered router that auto-escalates from plain HTTP to a headless browser engine on anti-bot challenges or SPA shells. Clean markdown + metadata + links. Handles PDFs, a single-heading |
🕸️ | Multi-page crawl — BFS, DFS, sitemap, or map-only. Per-domain rate limits, robots.txt respect, boilerplate dedup. |
🧩 | Structured data from a page: tables, metadata, JSON-LD, brand identity, named schemas (Article / Recipe / Product / …), or any custom JSON Schema. |
💾 | Query everything already seen — keyword or hybrid semantic. Plus stats, clear, and change detection. |
🧲 | Pages similar to a URL or a concept, via 3-way fusion of keyword + semantic + live web. |
🧠 | Decompose a question → fan out sub-queries → fetch sources → synthesize a cited report (or a structured brief the host LLM writes from). |
🤖 | Autonomous gather loop: plan → search → fetch → extract → synthesize, with a step log, time budget, and optional output schema. |
🔁 | See exactly what changed on a page since last visit; re-check on demand and deliver changes to a webhook. |
Every tool also runs from the terminal (wigolo search "…" --json), from an interactive shell with NDJSON piping (wigolo shell), over REST, and through the SDKs — CLI reference. Per-tool guides with the full parameter set are in docs/tools.md; runnable examples are in examples/.
Why it's different
wigolo isn't a free stand-in for the paid tools — it's built to match them. It's a focused web layer for your agents: an MCP and REST surface they call directly, with the search and extraction quality the paid services charge for. What separates it:
Built for agents. One MCP call fans out many queries across many engines in parallel, which a serial host tool-loop can't replicate. Every result carries transparent per-result scoring, and output is budget-aware.
Honest output. Stale cache, failed fetches, degraded backends, and truncation are surfaced in the result. When a bot-protected page can't be read, you get a labeled
blocked_by_challengefailure, not a challenge shell returned as content.$0 per query, free to re-query. Default search talks to public engines through direct adapters; the reranker and embeddings run on-device. Every response is cached, so asking again is instant and costs nothing.
Private by default. Cache, embeddings, models, and config live under
~/.wigolo/. Nothing reaches a third party unless you explicitly opt into an LLM for synthesis.
Here's what one real result looks like, dissected. It includes the failed engine and the weak result, because those are part of the answer too:
Sponsors
Thank you to the sponsors below, who help keep wigolo maintained and free for everyone to use. Their support goes straight into the work.
TestMu AI (formerly LambdaTest) is the world's first full-stack agentic AI quality engineering platform, trusted by 18,000+ enterprises.
wigolo is free for all and is meant to stay that way. If you or your company would like to help keep it maintained, there's room for more sponsors — reach out at ktowhid20@gmail.com, or see SPONSORS.md for the terms. A one-off via Buy Me a Coffee is welcome too.
Benchmark
All four tools converged on the same core answer, and only one of them handed back verbatim, byte-pinned evidence while doing it.
One cold query ran live inside a single Claude Fable 5 session, fanned out to four web tools on equal footing (built-in WebSearch, wigolo, Tavily, Exa), and was judged by the agent on the evidence alone. All four converged on the same answer and the same top source, so the parity is demonstrated on-screen. wigolo alone returned verbatim excerpts pinned to byte-offset source spans, an explainable score decomposition, and live per-engine telemetry, and its own scorer flagged two weak results as junk. The cloud tools earn their place too: Exa rendered the official docs' comparison matrix in full. Run your own query and you'll see the same shape.
How it compares
wigolo | Firecrawl | Exa | Tavily | |
Multi-engine web search | ✅ | ✅ | ✅ | ✅ |
Fetch & structured extraction | ✅ | ✅ | ✅ | ✅ |
Whole-site crawl & map | ✅ | ✅ | — | ✅ |
Verbatim excerpts pinned to byte-offset source spans | ✅ | — | — | — |
Explainable per-result score decomposition | ✅ | — | — | — |
Persistent local memory — re-query instantly, offline | ✅ | — | — | — |
Query data stays on your machine | ✅ | — | — | — |
API key / account | none | required | required | required |
Cost per query | $0 | metered | metered | metered |
Feature standing as of July 2026 — check each vendor's docs for current state.
That last row compounds, because agents ask in bursts:
Beyond your editor
The same ten tools serve every kind of agent, over whichever surface fits: MCP for coding agents, REST for everything else, SDKs to embed, and framework wrappers to drop in.
REST API — wigolo serve
One process exposes a plain-JSON REST API next to the MCP transport. No MCP client needed, just curl:
wigolo serve # 127.0.0.1:3333 — loopback is open; off-loopback requires a token
curl -sX POST http://127.0.0.1:3333/v1/search \
-H 'Content-Type: application/json' \
-d '{"query":"local-first software","max_results":5}'POST /v1/{tool} covers all ten tools, GET /openapi.json is the OpenAPI 3.1 contract, and /mcp + /sse serve remote MCP clients from the same port. Bind past loopback and a bearer token is required, so the server fails closed by default. Point n8n, a Hermes-style assistant, or any self-hosted agent at it. → REST API
SDKs — TypeScript & Python
Thin, typed clients with an embedded local mode that finds or starts the daemon for you. No separate serve step.
TypeScript — npm install wigolo-sdk (zero-dep; Node / Bun / Deno / edge):
import { createLocalClient } from 'wigolo-sdk/local';
const { client, close } = await createLocalClient(); // reuse a running daemon, or spawn one
const res = await client.search({ query: 'local-first web search', max_results: 5 });
console.log(res.results.map((r) => r.title));
await close(); // stops the daemon only if this call spawned itPython — pip install wigolo (standard library only; sync + async):
from wigolo import local_client
with local_client() as client: # reuse a healthy daemon, or spawn one
res = client.search(query="local-first web search", max_results=5)
for r in res["results"]:
print(r["title"], r["url"])Framework integrations
Drop wigolo's tools into the framework you already use. You get the full ten-tool surface, including the cache / find_similar / research / agent that most framework web-tools don't ship:
Framework | Package | What you get |
LangChain |
| each tool as a |
CrewAI |
|
|
LlamaIndex |
| a |
Vercel AI SDK |
| tool factories for |
Docker
# stdio MCP — wire it into any MCP client as command: docker
docker run -i --rm -v wigolo-data:/data ghcr.io/knockoutez/wigolo
# HTTP server for remote / multi-client use
docker run -p 3333:3333 -v wigolo-data:/data \
-e WIGOLO_API_TOKEN=a-long-random-secret \
ghcr.io/knockoutez/wigolo serve --host 0.0.0.0The slim image lazy-loads models into the volume; :full preinstalls the browser engine. Also on Docker Hub as towhid69420/wigolo. → installation & all channels
Agent skills
An 11-pack skill catalog teaches your coding agent to drive each tool well. It's installed by init and managed with wigolo skills add|list|remove. → skills
One note for self-hosters: some challenge-protected sites score IP reputation, so a datacenter IP won't clear walls a home connection would. wigolo labels those failures, and the self-hosting guide covers the opt-in proxy answer.
Star history
Refreshed daily from the GitHub API. Add a ⭐ if wigolo is useful to you.
Architecture
A single Node process speaks MCP (JSON-RPC over stdio). Everything heavy is local and lazy-loaded, so a zero-key install pays nothing for the parts it isn't using.
flowchart TD
A["🤖 AI agent<br/>any MCP client · REST · SDK"]
A -->|MCP over stdio| B["<b>wigolo</b><br/>10 tools · dynamic instructions<br/>in-process browser pool + cache + models"]
B --> C{"Tool layer"}
C --> T1["search · fetch · crawl · extract"]
C --> T2["cache · find_similar · research · agent"]
T1 --> F["⚙️ Fetch router<br/>tiered escalation, learned per domain"]
T1 --> S["⚙️ Search<br/>18 engines → rank fusion → ML rerank<br/><i>explainable evidence score</i>"]
T2 --> DB[("🗄️ Local cache<br/>keyword + vector index")]
T2 --> ML["🧠 On-device ML<br/>embeddings + reranker"]
F -.->|optional| LLM["☁️ LLM<br/>synthesis only · opt-in"]
S -.->|optional| SX["🔀 Aggregator backend<br/>opt-in legacy / hybrid"]
F --> WEB["🌍 Public web"]
S --> WEB
style B fill:#7c3aed,stroke:#5b21b6,color:#fff
style WEB fill:#0ea5e9,stroke:#0369a1,color:#fff
style DB fill:#1e293b,stroke:#334155,color:#fff
style LLM stroke-dasharray: 5 5
style SX stroke-dasharray: 5 5Code beats model. Deterministic work stays off the LLM: canonicalization, rank fusion, dedup, and schema matching. The model is reserved for judgment, opt-in, and capped per request. LLM-filled fields are checked against the source and nulled if absent.
Signal-driven routing. The fetch ladder escalates to a real browser on observable signals, not domain guesses: SPA markers, challenge bodies, thin content. It learns per domain, unlearns when a site stops needing it, and
wigolo tune listshows you exactly what it learned.Reads pages the way a browser does. Tiered fetching waits out interstitial challenges and reuses clearances per domain, politely: robots.txt respected, per-domain rate limits, research-grade volumes. When a wall stays up, the failure is labeled and reported.
Configuration
A clean install works out of the box. Three settings raise output quality:
# 1. Synthesis — the biggest lever (research / agent / search-answer write real prose)
export WIGOLO_LLM_PROVIDER=gemini # or anthropic / openai / groq / ollama (keyless)
export GEMINI_API_KEY=<your-key>
# 2. Wider retrieval funnel
export WIGOLO_SEARCH=hybrid # core engines + aggregator fallback
export WIGOLO_GITHUB_TOKEN=... # GitHub code search 10 → 30 req/min
# 3. Land more fetches, stay warm
export WIGOLO_TLS_TIER=auto # per-domain learned fetch hardening
export WIGOLO_EAGER_WARMUP=1 # pay the ~1s model load up frontPer-call habits that pay off: query arrays (["a","b","c"]) for parallel breadth · search_depth: "deep" for queries that matter · include_domains as a hard filter for docs lookups. The full reference covers every environment variable, config-file key, search backend, cache TTL, and serve limit; it's in the configuration guide.
Docs & examples
docs/ — the complete manual: getting started · installation & channels · configuration · tools reference · CLI & shell · REST API · SDKs & integrations · self-hosting · agent skills · plugins · troubleshooting & FAQ · privacy & security
examples/ — runnable, each with a README (and most with a terminal recording): one-shot CLI, NDJSON shell pipelines, REST via curl, TypeScript & Python SDKs, Vercel AI SDK tools, pointing self-hosted n8n at a remote wigolo, watch-with-webhook, and writing your own search-engine plugin. The docs are also rendered on the site at knockoutez.github.io/wigolo/docs.
Beta & feedback
wigolo is in public beta. Everything documented here works and is held to a 7,600-test suite; it's stable, and beta is about the polish bar. It stays beta until enough people have used it, kicked it, and starred it that calling it v1 means something. Your feedback shapes what comes next, and every report is read, usually the same day:
🐛 Report a bug — broke, misbehaved, surprised you
💡 Request a feature — something it should do
💬 Ask anything — questions, setups, show & tell
If wigolo earns a place in your setup, three things keep it going: a ⭐ star (it's how open source gets found), a ☕ coffee (there's no paid tier and never will be), or an email that goes straight to the one developer who wrote the code.
Troubleshooting
wigolo doctor names any broken component and the exact env var or command that fixes it; wigolo doctor --fix repairs the common cases, and wigolo verify health-checks every component. A component failing during init doesn't break wigolo: init still exits 0, and core search / fetch / crawl / extract / cache work with no models and no browser. Quick hits:
Slow or failed downloads — re-run
wigolo warmup --all(or--browser/--embeddings/--reranker); they resume and retry.Browser won't launch on Linux —
wigolo warmup --browserinstalls the OS libraries (or prints the exact command).Native build error / unusual Node — use an LTS: Node 20, 22, or 24.
Behind a proxy —
USE_PROXY=true+PROXY_URL; addNODE_EXTRA_CA_CERTSfor TLS-inspecting proxies.
The full guide covers per-symptom fixes, a "what still works when X fails" map, platform notes (incl. linux-arm64), and offline installs: docs/troubleshooting.md.
FAQ
No catch by design. The expensive parts (ranking, embeddings, the browser engine) run on your hardware, so there's no per-query cost to recover and no reason for a meter. It's sustained by donations, and the AGPL license legally prevents a switch into a closed hosted product.
The benchmark section above is a live 4-way run you can reproduce: everyday agent queries land at parity, the paid tools still win some deep-extraction edge cases, and crawling is where wigolo is strongest. Every result shows its scoring, so you don't have to take anyone's word for it.
It's engineered for exactly that: 18 engines fused with rank fusion (any one failing barely moves results), a tiered fetch ladder with per-domain learning, and an optional aggregator fallback. Degraded backends are reported in the output, and the local cache means everything already seen keeps working regardless.
wigolo reads the public web the way a browser does: robots.txt respected by default, per-domain rate limits, and research-grade volumes for one agent on one machine. It sits deliberately at the polite end of the spectrum.
Yes, freely, company-wide. The license only bites if you modify wigolo and run it as a network service, in which case you must publish those modifications; using it as a local dev tool carries zero obligation. For commercial-licensing questions, reach out.
That's the on-device brain: a full browser engine plus the ranking and embedding models the cloud services run on their side and bill you for. Once it's on disk, every query uses it for free.
Available on
npm —
wigolo(primary channel — the Quickstart above)PyPI —
wigolo(Python SDK)Docker —
ghcr.io/knockoutez/wigolo·towhid69420/wigoloOfficial MCP Registry —
io.github.KnockOutEZ/wigolo
Homebrew, curl | sh, and the single-file binary are covered in the installation guide. Use one channel per machine; they all share ~/.wigolo.
Contributing
Bug reports, feature requests, and PRs are all welcome; see CONTRIBUTING.md. Keep tool handlers thin, add tests, and run the suite before opening a PR. The friendliest entry point is the plugin system for custom search engines and extractors: add a search engine in ~100 lines, with a template in examples/plugin-search-engine.
License
GNU AGPL-3.0-only. Free to use, modify, and self-host, including inside a company. The one obligation: if you run a modified version as a network service, you must publish your modified source under the same license. That keeps wigolo open while preventing a closed, hosted fork. See SECURITY.md to report a vulnerability and TRADEMARK.md for use of the name. For commercial-licensing questions, reach out.
wigolo is free and actively maintained, and it's meant to stay that way. If it saves you a metered search bill, a ⭐, a sharp issue, or a ☕ coffee helps keep it sustainable.
Built and maintained by @KnockOutEZ · ktowhid20@gmail.com · X · LinkedIn
Available Tools
7 toolsagentA
Natural-language data gathering across sources. Plans queries + URLs from a prompt, executes in parallel, optionally extracts structured fields, synthesizes. Full step transparency.
LLM-optional: with a synthesis LLM configured it writes the summary; without one it returns gathered evidence + a step log (plus schema-shaped fields when a schema is given) — YOU write the summary from the returned evidence, never present the raw step log as a poor result. For best agent results configure a free LLM key (e.g. Gemini).
Key parameters:
prompt: NL description of what to gather (e.g. "pricing for the top 5 CRM tools").
urls: optional seed URLs.
schema: optional JSON Schema — extracts matching fields from each page and merges.
max_pages: default 10.
max_time_ms: default 60000.
stream: progress notifications per step.
max_tokens_out / include_full_markdown / citation_format: budget + shape controls.
Pipeline: plan → search+fetch in parallel within budget → optional schema extraction → synthesize. steps[] exposes every action with timing. Uses MCP sampling when supported; falls back to keyword extraction otherwise.
Returns result, sources[], pages_fetched, steps[], total_time_ms, sampling_supported.
| Name | Required | Description | Default |
|---|---|---|---|
| urls | No | Specific URLs to include in the data gathering | |
| prompt | Yes | Natural-language description of what data to gather | |
| schema | No | Optional JSON Schema -- extract structured data matching this schema from each page | |
| stream | No | Send progress notifications as each step completes | |
| max_pages | No | Maximum pages to fetch (default 10, max 100) | |
| max_time_ms | No | Maximum execution time in milliseconds (default 60000) | |
| max_tokens_out | No | Token-budget cap on total output. Uses cl100k-base BPE; non-OpenAI tokenizer counts may drift ~5-15%. When both max_tokens_out and max_chars are set, max_tokens_out wins. | |
| citation_format | No | Citation rendering style. 'numbered' (default) inline [N] markers; 'json' returns a citations[] array; 'anthropic_tags' wraps sources in <source id='...'> tags. | |
| include_full_markdown | No | Include full markdown body in the response. Default false on multi-result tools (returns evidence excerpts only); set true to restore. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It details the pipeline (plan, search+fetch in parallel, optional extraction, synthesis), mentions full step transparency via steps[], explains LLM-optional behavior, and discloses fallback to keyword extraction. It also covers budget and output controls.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a high-level summary, LLM-optional note, parameter details, pipeline, and return value list. It is front-loaded with purpose. However, it is somewhat lengthy and includes minor details (e.g., tokenizer drift) that could be omitted for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 parameters, nested objects, no output schema), the description is thorough. It explains the pipeline, behavior without synthesis LLM, return fields (result, sources[], steps[], etc.), and parameter effects. It covers edge cases like max_tokens_out vs max_chars and citation format options.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds significant value beyond the schema. It explains the purpose of each key parameter in context (e.g., 'prompt: NL description of what to gather'), provides defaults (max_pages=10, max_time_ms=60000), and describes citation_format options with examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Natural-language data gathering across sources', clearly stating the verb (gather) and resource (sources). It distinguishes the tool from siblings like fetch and search by describing a multi-step pipeline (plan, parallel fetch, extract, synthesize).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool (for NL data gathering with optional schema) and provides context for LLM-optional behavior. It tells the agent to configure an LLM key for best results and warns against presenting raw step logs. However, it does not explicitly list when not to use it or compare directly to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
cacheA
Search previously fetched content without hitting the network. Run this BEFORE any search/fetch — cache hits return instantly with full markdown.
Key parameters:
query: FTS5 full-text search over cached markdown + titles (supports AND, OR, NOT, "phrase").
url_pattern: glob filter on URLs (e.g. "example.com").
since: ISO date — only entries cached after this date.
stats: true to get cache size, entry count, oldest/newest dates.
clear: true to delete matching entries.
Persists across sessions. No remote round-trip.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Search strategy when query is provided. "fts" (default) runs keyword-only BM25 over the FTS5 index. "hybrid" additionally runs semantic vector search and fuses both rankings with reciprocal rank fusion for higher-recall lookups; falls back to FTS when the embedding index is empty or unavailable. | |
| clear | No | Clear matching cache entries (requires at least one filter: query, url_pattern, or since) | |
| limit | No | Maximum number of results to return (default 20). | |
| query | No | Full-text search over cached content | |
| since | No | ISO date — only results cached after this date | |
| stats | No | Return cache statistics (total URLs, size, date range) | |
| url_pattern | No | Filter by URL glob pattern (e.g., "*example.com*") | |
| check_changes | No | Re-fetch all matching cached URLs and report which ones have changed. Returns a list of URLs with changed/unchanged status and diff summaries. Use with query or url_pattern to scope which cached entries to check. | |
| max_tokens_out | No | Token-budget cap on total output (cl100k-base BPE). Caps the aggregate size of all returned markdown bodies; bodies past the budget are truncated or dropped. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: no network round-trip, persistence across sessions, FTS5 search capabilities, support for globs, date filtering, stats, and clear. It also explains the mode parameter's fallback strategy and the check_changes feature. No gaps or contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and guidance, then uses a bullet list for key parameters, and ends with a summary line. Every sentence provides essential information without redundancy. Efficient and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters with no output schema, the description covers all behaviors including complex ones like hybrid search and change detection. It sufficiently equips an agent to use the tool correctly without ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, yet the description adds significant value: it details FTS5 operators for query, explains hybrid vs fts mode, requires filters for clear, describes stats output, and elaborates on check_changes. This greatly aids correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search previously fetched content without hitting the network.' It specifies the verb (search) and resource (cached content), and distinguishes itself from sibling tools like fetch and search by directing the user to run this before them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to 'Run this BEFORE any search/fetch' and implies it's for instant cache hits. While it doesn't explicitly list alternatives for cache misses, the context is clear enough. Lacks explicit 'when not to use' but still provides strong guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
diffA
Compute a diff between two markdown bodies or two URL fetches.
Key parameters:
old: { url?, markdown?, content_hash? } — left-hand side. URL form reads from cache; cache miss returns a structured
cache_misserror (no network re-fetch).new: { url?, markdown? } — right-hand side. Same cache rules as
old.output: 'unified' (default, git-style patch) | 'hunks' (structured array) | 'summary' (line counts only).
granularity: 'line' (default) | 'word' | 'section'. Section walks H1/H2/H3 boundaries and tags each hunk with
section_title.
Returns { changed, summary, unified_diff?|hunks?, truncated? }. summary always present (added/removed/modified lines + total_changed_chars). Above the 5000-line cap the engine emits truncated: true plus an approximate summary — never silently degrades.
| Name | Required | Description | Default |
|---|---|---|---|
| new | No | Right-hand side of the diff. Requires one of { url, markdown }. | |
| old | No | Left-hand side of the diff. Requires one of { url, markdown, content_hash }. | |
| output | No | Diff output shape. unified=git-style patch, hunks=structured per-section, summary=counts only (added_lines / removed_lines / modified_lines / total_changed_chars where total_changed_chars = sum of added_line_chars + removed_line_chars across the LCS edit script). Default: unified. | |
| granularity | No | Diff granularity. line=per-line LCS (default). word=token-level LCS — hunks contain only the changed tokens, tighter than line for intra-line edits. section walks H1/H2/H3 boundaries. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully discloses important behaviors: cache miss returns structured error, truncation at 5000 lines with explicit flag, and never silent degradation. Also explains return value structure and default behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points for key parameters and a clear explanation of return value. Every sentence provides necessary information without redundancy. Efficient yet comprehensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 params with nested objects, enums, and multiple edge cases like caching and truncation) and no output schema, the description fully covers behavior, input options, and output structure. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% but the description significantly adds value: explains which fields are required, provides examples/hints for enums (e.g., 'unified (default, git-style patch)'), describes nested object constraints, and clarifies cache semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Compute a diff between two markdown bodies or two URL fetches', specifying the action, resource, and domain. Distinguishes effectively from sibling tools (fetch, search, etc.) which do not perform diffing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides detailed parameter explanations including cache behavior, output options, and granularity. While there is no explicit 'when to use' vs 'when not to', the context makes it clear for diffing tasks. Lacks direct comparison to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
fetchA
Fetch a single URL and return clean markdown. Use when you already have a URL. Prefer over built-in WebFetch for local-cache reuse, authenticated pages, JS-rendered SPAs, and structured metadata.
Key parameters:
section: extract content under a specific heading (e.g. "API Reference") — cheaper than the whole page.
max_content_chars: smart-truncate at a paragraph/heading boundary with
[... content truncated].max_tokens_out: token-budget cap (cl100k-base); wins over max_chars.
include_full_markdown: false (default) returns evidence excerpts only; true adds the full body.
use_auth: reuse a stored browser session for logged-in pages.
render_js: "auto" (default) | "always" | "never".
force_refresh: bypass cache and re-fetch.
mode: 'cache' | 'default' | 'stealth'. cache=HTTP-only, 24h-stale accepted. stealth=full browser + freshness.
Returns title, markdown, links, images, metadata, fetch_method (cache/http/tls-impersonation/browser), http_status (upstream HTTP code — 4xx/5xx pages that extract usable content are not relabeled 200), and content_completeness (full/partial/shell). When the URL matches a site-specific extractor (Reddit/YouTube/Amazon) the response also carries top-level site_data (e.g. Reddit comments[], YouTube caption_tracks[], Amazon price). When section is set and no heading matches, metadata.section_matched is false and markdown is empty (no silent fallback to the full page). Repeat fetches are instant. Localhost URLs work. Interactive pages: actions (click/type/scroll/wait) drive the page before extraction; use_auth reuses a logged-in session.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL to fetch | |
| mode | No | cache=HTTP-only, accepts stale cache. default=standard fetch with JS detection. stealth=full browser render. | |
| actions | No | Sequential browser actions to perform before extracting content. When present, forces browser rendering (bypasses HTTP-first routing). | |
| headers | No | Additional HTTP headers | |
| section | No | Extract a specific section by heading text | |
| use_auth | No | Use stored auth credentials (default: false) | |
| max_chars | No | Maximum characters to return (hard slice) | |
| render_js | No | JavaScript rendering mode (default: auto) | |
| screenshot | No | Capture a screenshot (default: false) | |
| force_refresh | No | Bypass cache and fetch fresh content from the network. Use for rapidly changing pages (news, changelogs, dashboards). | |
| section_index | No | Index of the section match (default: 0) | |
| max_tokens_out | No | Token-budget cap on total output. Uses cl100k-base BPE; non-OpenAI tokenizer counts may drift ~5-15%. When both max_tokens_out and max_chars are set, max_tokens_out wins. | |
| citation_format | No | Citation rendering style. 'numbered' (default) inline [N] markers; 'json' returns a citations[] array; 'anthropic_tags' wraps sources in <source id='...'> tags. | |
| max_content_chars | No | Smart truncate markdown to N chars at paragraph/heading boundary with [... content truncated] marker. Preferred over max_chars for AI agents. | |
| include_full_markdown | No | Include full markdown body in the response. Default false on multi-result tools (returns evidence excerpts only); set true to restore. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It thoroughly explains caching behavior, section extraction smart truncation, auth reuse, JS rendering, mode differences, return fields (including fetch_method, http_status, content_completeness), site-specific extractors, and edge cases like empty markdown when section doesn't match. All relevant behavioral traits are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but well organized: a one-sentence summary, a paragraph on key parameters, then return fields, site-specific behaviors, and edge cases. Every sentence adds value, though minor trimming could improve succinctness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 15 parameters, 100% schema coverage, and no output schema, the description is remarkably complete. It covers all key behaviors, parameter interactions, return fields, sibling differentiation, and edge cases. No gaps are apparent for an AI agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds significant meaning: explains the interaction between max_tokens_out and max_chars, the effect of include_full_markdown default, the meanings of mode values, and how actions bypass HTTP-first routing. This goes well beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch a single URL and return clean markdown,' specifying verb and resource. It distinguishes from sister tool 'WebFetch' by listing advantages like local-cache reuse, authenticated pages, JS-rendered SPAs, and structured metadata. This makes the tool's unique purpose immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use when you already have a URL' and advises 'Prefer over built-in WebFetch...' providing clear context for when to use this tool over alternatives. It does not explicitly list exclusions, but the guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
find_similarA
Find content related to a URL or concept. Best after a successful crawl/fetch — the local cache makes recommendations cheap. Concept-only queries on a cold cache often return 0-2 weak matches; warm the cache first via crawl / fetch for materially better results.
Key parameters:
url: known-good page; its content + embeddings drive similarity.
concept: free-text alternative to url. Thin cache → expect
cold_startto fire.max_results: default 5.
include_cached: true (default) to search cache first; false = web only.
threshold: minimum fused score (0-1, default 0.5).
include_ranking_debug: opt-in per-result
ranking_debug{ fts5_rank, embedding_rank, web_rank, rrf_score } so you can audit which signal won.max_tokens_out / include_full_markdown / citation_format: budget + shape controls.
Pass either url or concept. Three signals fused via RRF: keyword (FTS5), embeddings, optional live web. Each result carries match_signals with embedding_rank, fts5_rank, fused_score. When local signals are weak (cache empty, no hits, or concept mode returns only 1-2 cache matches), the response carries cold_start — pass it verbatim to the user (tune WIGOLO_FIND_SIMILAR_COLD_START_THRESHOLD to adjust).
Returns results[], method ("hybrid" | "embedding" | "fts5" | "search"), cache_hits, search_hits, embedding_available, total_time_ms.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Find pages similar to this URL. The page is fetched (or read from cache) and its content analyzed for key terms. | |
| mode | No | Retrieval strategy: cache (local hybrid), web-expansion (key terms + web search), crawl-rank (1-hop crawl from seed URL + embed + cosine rank), or auto. | auto |
| concept | No | Find pages related to this concept or topic description. Use when you don't have a specific URL. | |
| threshold | No | Hard post-filter on match_signals.fused_score. Results below this raw fused score are dropped (empty array is correct when nothing qualifies). Default 0 (no filtering). Note: filters on the raw RRF/embedding score, not the normalized relevance_score. | |
| include_web | No | Supplement with web search if needed (default: true) | |
| max_results | No | Maximum results to return (default 10, max 50) | |
| include_cache | No | Search local cache for similar pages (default: true) | |
| max_tokens_out | No | Token-budget cap on total output. Uses cl100k-base BPE; non-OpenAI tokenizer counts may drift ~5-15%. When both max_tokens_out and max_chars are set, max_tokens_out wins. | |
| citation_format | No | Citation rendering style. 'numbered' (default) inline [N] markers; 'json' returns a citations[] array; 'anthropic_tags' wraps sources in <source id='...'> tags. | |
| exclude_domains | No | Never return results from these domains | |
| include_domains | No | Only return results from these domains | |
| include_full_markdown | No | Include full markdown body in the response. Default false on multi-result tools (returns evidence excerpts only); set true to restore. | |
| include_ranking_debug | No | Attach per-result ranking_debug { fts5_rank, embedding_rank, web_rank, rrf_score } so callers can audit disagreement between the three ranking sources. Off by default. Concept-mode results improve materially with a warm cache — run wigolo_crawl on the relevant docs before relying on concept-only retrieval. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: three signals fused via RRF, cold_start signal for weak cache, opt-in ranking_debug, parameter budget controls, and the shape of the response (results, method, cache_hits, etc.). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, starting with a one-sentence summary, followed by usage guidelines, then parameter details. It is front-loaded with the key purpose. However, it is somewhat dense and verbose, especially in the parameter section, which could be more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (13 parameters, no output schema, three signals), the description is thorough and complete. It covers what the tool returns, how parameters affect behavior, and caveats like cold cache. It provides enough information for an AI agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant value beyond parameter names and types. It explains the interplay between parameters (e.g., include_ranking_debug, cold_start, threshold behavior), provides context for url vs concept, and describes how parameters affect the fusion logic.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Find content related to a URL or concept', specifying the resource and scope. It distinguishes from siblings by emphasizing 'Best after a successful crawl/fetch' and referencing alternative tools like crawl/fetch for warming the cache.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance on when to use the tool ('Best after a successful crawl/fetch') and when not to use it ('concept-only queries on a cold cache often return 0-2 weak matches'). It advises warming the cache first via crawl/fetch and specifies that either url or concept should be passed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
researchA
Multi-step research on a complex question. Decomposes into sub-queries, searches in parallel, fetches sources, synthesizes a cited report. Beats chaining search + fetch manually for multi-source synthesis.
LLM-optional: with a synthesis LLM configured, the returned report is a written answer. Without one it returns a structured, cited brief (key_findings/highlights/sections) — YOU write the final answer from it; do not hand the user the raw structure as a weak result. For the best research quality a free Gemini API key (or any provider) is strongly recommended.
Key parameters:
question: the research question.
depth: 'quick' (~15s, 2 sub-queries) | 'standard' (~40s, 4 sub-queries, default) | 'comprehensive' (~80s, 7 sub-queries).
max_sources: override per-depth source count.
include_domains / exclude_domains: scope.
schema: optional JSON Schema — structures the report.
stream: progress notifications per phase.
max_tokens_out / include_full_markdown / citation_format: budget + shape controls.
Returns report (markdown with [N]), citations[], sources[], sub_queries[], depth, total_time_ms, sampling_supported, and brief with topics, highlights, key_findings, sections (overview.cross_references, comparison, gaps — gaps lists any named sub-entity research could not corroborate).
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | Research depth: quick (~15s), standard (~40s, default), comprehensive (~80s) | |
| schema | No | Optional JSON Schema -- structure the report to extract these fields | |
| stream | No | Send progress notifications as each research phase completes | |
| question | Yes | The research question to investigate | |
| max_sources | No | Override the default source count for the chosen depth (max 50) | |
| max_tokens_out | No | Token-budget cap on total output. Uses cl100k-base BPE; non-OpenAI tokenizer counts may drift ~5-15%. When both max_tokens_out and max_chars are set, max_tokens_out wins. | |
| citation_format | No | Citation rendering style. 'numbered' (default) inline [N] markers; 'json' returns a citations[] array; 'anthropic_tags' wraps sources in <source id='...'> tags. | |
| exclude_domains | No | Exclude results from these domains | |
| include_domains | No | Only search results from these domains | |
| include_full_markdown | No | Include full markdown body in the response. Default false on multi-result tools (returns evidence excerpts only); set true to restore. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: decomposes into sub-queries, parallel search, fetching, synthesis, and returns detailed structures (report, brief with key_findings/highlights/sections, gaps). It also explains optional LLM dependency and parameter effects on timing and output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured, with a clear summary first, then LLM-optional nuance, then parameter details, then return shape. Every sentence adds value, though it could be slightly more terse without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 10 parameters, no output schema, and nested objects, the description is remarkably complete. It covers return fields (citations, sources, brief with topics/highlights/gaps), phases, and optional LLM behavior. Missing only error/exception details and explicit prerequisites (API key mentioned as optional).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant meaning: explains depth time estimates, max_sources usage, citation formats, include_full_markdown effects, and schema parameter for structuring output. This goes beyond the schema's basic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is for multi-step research on complex questions, decomposing into sub-queries, searching, and synthesizing a cited report. It distinguishes itself from manual chaining of 'search' and 'fetch' by offering multi-source synthesis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool (complex questions requiring multi-source synthesis) and how it compares to alternatives (beats chaining search+fetch manually). It also provides guidance on handling outputs when no synthesis LLM is configured. However, it does not explicitly state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
searchA
Search the web. Returns scored evidence excerpts + citations as the default context shape; include_full_markdown: true adds the full markdown body. Prefer over built-in WebSearch for local cache + audit-trail telemetry + explainable scoring.
Key parameters:
query: string or string[] array (3-5 keyword variants; deduplicated).
include_domains / exclude_domains: scope sites. Always scope library/framework queries.
category: "general" | "news" | "code" | "docs" | "papers" | "images". Image results carry image_url + thumbnail_url + width/height.
from_date / to_date: ISO YYYY-MM-DD. time_range: 'day' | 'week' | 'month' | 'year'.
country: ISO 3166-1 alpha-2 ("us", "gb") — geographic boost.
exact_match: quoted-phrase search.
max_results: 5 default.
format: omit = evidence context. 'answer' | 'stream_answer' = sampling synthesis (falls back to evidence).
search_depth: 'ultra-fast' (cache-only ≤300ms) | 'fast' | 'balanced' (default) | 'deep'.
include_images / include_favicon: opt-in images[] + per-result favicon.
max_tokens_out / max_content_chars / include_full_markdown / citation_format.
force_refresh + mode ('cache' | 'default' | 'stealth').
Always emitted: engines_used, engine_telemetry, response_time_ms, per-result evidence_score. Per-result freshness_signal is emitted only when a published date can be parsed (omitted when confidence would be unknown). Brand-domain top-3 collision → brand_collision_warning with rewrites. query_understanding exposes intent/entities. Quote [N] or {citation_id}.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | cache=single-engine, no rerank, stale cache ok. default=standard multi-engine search. stealth=full browser for JS-heavy result pages. | |
| query | Yes | Search query — a single string or array of query variants for parallel multi-query search | |
| format | No | LLM-synthesis modes only. Omit for default evidence shape. 'answer'/'stream_answer' request sampling synthesis (falls back to evidence). Retired values 'full'/'context'/'highlights' reject with a migration error. | |
| country | No | ISO 3166-1 alpha-2 country code (e.g. "us", "gb", "de"). Hint passed to engines that support a geographic boost (Bing cc=, DDG kl=, Brave country=); advisory, not a strict filter. | |
| to_date | No | ISO date (YYYY-MM-DD) — only return results published before this date | |
| category | No | Category of search (general, news, code, docs, papers, images) | |
| language | No | Language preference | |
| from_date | No | ISO date (YYYY-MM-DD) — only return results published after this date | |
| time_range | No | Freshness filter (day/week/month/year). Conservative: only drops results with a confidently-extracted published_date — pages with no parseable date pass through, so this is a precision-boost not a hard bound. For strict ranges use from_date+to_date with a date-aware category (news, papers). | |
| exact_match | No | Treat the query as a quoted phrase. Engines that honour `"..."` filter to phrase matches, and results without the exact phrase in title or snippet are dropped. | |
| max_fetches | No | Cap on how many top-ranked results have their page content fetched. Defaults to max_results. Set lower (e.g. 3) to keep snippet-only listings cheap and only deep-read the most relevant. | |
| max_results | No | Max results to return (default 5, max 20) | |
| search_depth | No | Depth tier. ultra-fast=cache-only (≤300ms); on miss emits notice and empty results. fast=engines only, no content fetch / rerank (≤1s). balanced (default)=full pipeline. deep=balanced + full enrichment. | |
| agent_context | No | Optional agent context for ranking + dedup. text is concatenated with the query before embedding; recent_urls are dropped from results. | |
| force_refresh | No | Bypass all caches (search results and page content). Use when you need the most current information. | |
| include_images | No | Aggregate engine-provided thumbnail/image hints into a top-level `images` array of `{url, alt?, source_url}`. Empty array if no engine surfaced one. | |
| max_highlights | No | Maximum highlights to return (default 10). Highlights are 1-3 sentence passages scored by relevance to the query. | |
| max_tokens_out | No | Token-budget cap on total output. Uses cl100k-base BPE; non-OpenAI tokenizer counts may drift ~5-15%. When both max_tokens_out and max_chars are set, max_tokens_out wins. | |
| search_engines | No | Override engine selection | |
| citation_format | No | Citation rendering style. 'numbered' (default) inline [N] markers; 'json' returns a citations[] array; 'anthropic_tags' wraps sources in <source id='...'> tags. | |
| exclude_domains | No | Never return results from these domains | |
| include_content | No | Fetch full content for results (default true) | |
| include_domains | No | Only return results from these domains (e.g. ["react.dev", "github.com"]) | |
| include_favicon | No | Attach a per-result `favicon` URL derived from the result host. Cached per-domain across the call. | |
| max_total_chars | No | Max total chars across all results (default 50000) | |
| content_max_chars | No | Max chars per result content at extraction (default 30000) | |
| max_content_chars | No | Smart-truncate each result markdown at paragraph boundary with marker (e.g. 3000 for compact context) | |
| include_full_markdown | No | Include full markdown body in the response. Default false on multi-result tools (returns evidence excerpts only); set true to restore. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses default behavior, brand collision warning, conditional freshness_signal, mode behavior, and response shape. Thorough coverage of edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: purpose sentence, usage recommendation, bullet-like parameter list, always-emitted fields. Front-loaded with key info. Slightly long but justified by complexity; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 28-parameter tool with no output schema, description is remarkably complete: explains all output fields, parameter interactions, and edge cases (brand collision, conditional signals). Leaves no major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds significant value: explains defaults (max_results=5), behavioral nuances (time_range is precision-boost not hard bound), and extra output context (image fields, query_understanding).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States 'Search the web' and clearly describes default output (scored evidence excerpts + citations) and optional full markdown. Differentiates from built-in WebSearch via local cache, telemetry, and scoring.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends this tool over built-in WebSearch for caching/telemetry/scoring. Provides extensive parameter usage guidance (e.g., scope domains for library queries, time_range precision vs. from_date/to_date). Missing explicit when-not-to-use scenarios but strong overall.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
6 tool updates
v0.2.1- Added
agent - Added
diff - Added
fetch - Added
find_similar - Added
research - Added
search
2 tool updates
v0.2.0- Added
cache - Removed
crawl
9 tool updates
v0.2.0- Removed
agent - Removed
cache - Removed
diff - Removed
extract - Removed
fetch - Removed
find_similar - Removed
research - Removed
search - Removed
watch
10 tool updates
- First observed
agent - First observed
cache - First observed
crawl - First observed
diff - First observed
extract - First observed
fetch - First observed
find_similar - First observed
research - First observed
search - First observed
watch
TDQS
Each tool targets a distinct operation: single-URL fetch, web search, cache search, similarity search, multi-step research, flexible agent, and diff. There is no overlap or ambiguity in their purposes.
Most tool names are single lowercase words (fetch, search, cache, research, agent, diff), but find_similar breaks the pattern with an underscore. The naming is generally clear and predictable.
With 7 tools, the server is well-scoped for its purpose of web content retrieval and analysis. Each tool provides distinct value, and the count is neither too few nor too many.
The tool set covers the full lifecycle of web information gathering: fetching, searching, caching, similarity finding, deep research, flexible agent-based gathering, and diff comparison. There are no obvious gaps for the intended domain.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Scrape, crawl and search the web for AI agents via MCP.
One MCP for the Web. Easily search, crawl, navigate, and extract websites without getting blocked.…
Search the agentic web. 4,100+ sites, 11 tools incl. check_url + verify_mcp for probe-before-use.
Docs: https://docs.keenable.ai/mcp-server Keenable is a free, remote MCP server that gives agents access to the web index. Search the web with ranked results and date/site filters, then fetch any indexed page as clean markdown. Works out of the box with no account or API key.
Related MCP Servers
- AlicenseAqualityAmaintenanceA local-first, no-API-key MCP server that enables LLMs to search the web, fetch pages, and read documents using multiple engines and smart fallbacks.1060MIT
- AlicenseNot gradedqualityAmaintenanceA self-contained web-research MCP server that lets local LLM agents search, fetch, and synthesize web content using tools like web_search, web_fetch, and web_research.1MIT
- AlicenseNot gradedqualityBmaintenanceMCP server enabling local-first web search, fetch, extract, and caching with citeable excerpts, no API key required. Supports research workflows for agents and apps.18MIT
- AlicenseAqualityAmaintenanceLocal MCP server for web search and page extraction, providing clean markdown from URLs, search results, site mapping, and research endpoints without API keys or accounts.5Apache 2.0
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/KnockOutEZ/wigolo'
If you have feedback or need assistance with the MCP directory API, please join our Discord server