ToolCairnEvery call to search_tools and get_stack flows through the same five-stage pipeline. Most stages are invisible to users; understanding them helps you write better prompts and interpret responses.
Stage overview
┌───────────────────────────── User prompt ─────────────────────────────┐
│ "best ORM for TypeScript" │
└───────────────────────────────┬───────────────────────────────────────┘
│
▼
┌─── Stage 0: Direct lookup ────────────────────────────────────────────┐
│ A query that clearly names a tool is returned immediately. │
└───────────────────────────────┬───────────────────────────────────────┘
│ (nothing obvious — continue)
▼
┌─── Stage 1: Broad retrieval ──────────────────────────────────────────┐
│ Shortlist all tools that plausibly match what was asked, │
│ blending literal phrasing and intent. │
└───────────────────────────────┬───────────────────────────────────────┘
│ Shortlist
▼
┌─── Stage 2: Guided discovery (optional) ──────────────────────────────┐
│ If the shortlist is close, ask a clarifying question │
│ to narrow intent. │
└───────────────────────────────┬───────────────────────────────────────┘
│ Narrowed list
▼
┌─── Stage 3: Relevance rerank ─────────────────────────────────────────┐
│ Reorder by fit with your project's existing tools and │
│ declared constraints (language, deployment, license). │
└───────────────────────────────┬───────────────────────────────────────┘
│ Reranked
▼
┌─── Stage 4: Selection ────────────────────────────────────────────────┐
│ Filter out abandoned or duplicative candidates. │
│ Return one or two recommendations. │
└───────────────────────────────┬───────────────────────────────────────┘
▼
┌──────────┐
│ Result │
└──────────┘Stage 0 — Exact-match short-circuit
If the query is unambiguously a tool name (e.g. "prisma"), ToolCairn returns that node directly. No ranking, no clarification. This keeps direct lookups cheap and the response latency predictable.
Stage 1 — Hybrid retrieval
The engine casts a wide net. Both literal phrasing and intent are considered in parallel so a tool you'd find by name is just as findable as one you describe by purpose. What emerges is a broad shortlist — not yet a recommendation.
Stage 2 — Guided discovery
When the shortlist is genuinely close, the engine asks one clarifying question instead of guessing. Your agent answers via search_tools_respond. Questions are capped — search never turns into an interview.
Stage 3 — Relevance rerank
Candidates are reordered by how well they fit your situation: the tools already in the project's config, the declared constraints (language, deployment, license), and established companion relationships. A tool that's known to work alongside your existing stack rises; a tool with a conflict falls.
Stage 4 — Selection
The final stage filters out candidates that look abandoned or duplicative of a stronger pick, then returns one or two recommendations. Two picks appear only when they represent genuinely different bets the user should choose between — never two near-identical tools.
Related
- Guided Discovery — deep-dive on Stage 2.
- Health Tiers — what drives Stage 4 filtering.
- search_tools — calling this pipeline.