find_similar
Find pages similar to a URL or concept by combining keyword search, embeddings, and web results. Uses a local cache for cheap recommendations after crawling.
Instructions
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.
Input Schema
| 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. |