Skip to main content
Glama
KnockOutEZ

wigolo

by KnockOutEZ
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

find_similar

Read-onlyIdempotent

Find pages related to a known URL or topic by fusing keyword, embedding, and web search signals; use it after crawling or fetching to get stronger cached recommendations.

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_start to 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

NameRequiredDescriptionDefault
urlNoFind pages similar to this URL. The page is fetched (or read from cache) and its content analyzed for key terms.
modeNoRetrieval strategy: cache (local hybrid), web-expansion (key terms + web search), crawl-rank (1-hop crawl from seed URL + embed + cosine rank), or auto.auto
conceptNoFind pages related to this concept or topic description. Use when you don't have a specific URL.
thresholdNoHard 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_webNoSupplement with web search if needed (default: true)
max_resultsNoMaximum results to return (default 10, max 50)
include_cacheNoSearch local cache for similar pages (default: true)
max_tokens_outNoToken-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_formatNoCitation rendering style. 'numbered' (default) inline [N] markers; 'json' returns a citations[] array; 'anthropic_tags' wraps sources in <source id='...'> tags.
exclude_domainsNoNever return results from these domains
include_domainsNoOnly return results from these domains
include_full_markdownNoInclude full markdown body in the response. Default false on multi-result tools (returns evidence excerpts only); set true to restore.
include_ranking_debugNoAttach 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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.2.1
  2. Removedv0.2.0
  3. First observed

TDQS

A4.1/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover readOnly/idempotent/openWorld, and the description adds substantial behavior beyond them: the RRF fusion of three signals, the `cold_start` response flag and how to surface it, the cache-warming effect on cost and quality, and an env-var tuning hook. This is the kind of context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the usage condition and keeps parameter notes in a scannable bullet list. The cold-start/cache-warming point is repeated three times (main paragraph, concept bullet, ranking-debug bullet), which costs space without adding information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 13 parameters and no output schema, the description does the necessary work of enumerating the return fields (results[], method, cache_hits, match_signals, cold_start), which an agent could not get elsewhere. The value is undercut by the incorrect default values and the missing `mode` parameter.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline would be 3, but the description actively misstates structured data: it says `max_results` default 5 (schema: 10), `threshold` default 0.5 (schema: 0), and names a parameter `include_cached` that does not exist (schema: `include_cache`). It also omits the `mode`, `include_domains`, and `exclude_domains` parameters entirely, so an agent trusting it would pass wrong defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: 'Find content related to a URL or concept,' with the two supported input modes named up front. It doesn't explicitly contrast itself with the `search` sibling, so an agent must infer the difference, which keeps it at 4 rather than 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use guidance ('Best after a successful crawl/fetch') and explicitly names the alternative tools (`crawl`/`fetch`) as prerequisites for warm-cache usage. It also warns when results will be poor (concept-only on cold cache) and tells the agent what to do instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools