Rich Context Guide

The problem: unnecessary round-trips

ToolCairn’s Guided Discovery system asks follow-up questions when a query is ambiguous. That’s great for interactive use — but in automated pipelines or when an AI agent already has full project context, those extra round-trips add latency without adding value.

A bare query like this will almost always trigger clarification:

{
  "query": "database"
}

ToolCairn needs to know: SQL or NoSQL? What language? Self-hosted or cloud? What’s the scale? Without answers, it can’t rank meaningfully. The solution is to provide that context upfront.

The solution: context filters

Add a context object to your search_tools call. This gives ToolCairn the signal it needs to skip clarification and go straight to results.

{
  "query": "database",
  "context": {
    "language": "Python",
    "category": "orm",
    "deployment": "self-hosted"
  }
}

With those three filters, ToolCairn knows exactly what you mean: a self-hosted ORM for Python. No follow-up needed — you get results on the first call.

Side by side: without vs. with context

// Request
{ "query": "database" }

// Response — clarification required
{
  "type": "clarification",
  "query_id": "xyz-789",
  "questions": [
    { "key": "category", "question": "What type of database?", "options": ["relational", "document", "key-value", "graph"] },
    { "key": "language", "question": "Primary language?", "options": ["TypeScript", "Python", "Go", "Java"] },
    { "key": "deployment", "question": "Deployment model?", "options": ["self-hosted", "managed", "embedded"] }
  ]
}

// Requires a second call with search_tools_respond...

// Request
{
  "query": "database",
  "context": {
    "language": "Python",
    "category": "orm",
    "deployment": "self-hosted"
  }
}

// Response — immediate results
{
  "type": "results",
  "recommended": {
    "name": "sqlalchemy",
    "health_tier": "healthy",
    "health_score": 93,
    "why": "Python's most mature ORM — extensive docs, self-hosted, strong community"
  },
  "alternatives": [
    { "name": "django-orm", "health_score": 90, "why": "Great if you're using Django" },
    { "name": "tortoise-orm", "health_score": 72, "why": "Async-first alternative" }
  ]
}

Available context filters

You can provide any combination of these filters. Each one narrows the search and reduces the likelihood of clarification.

All filters are optional. Providing even one significantly reduces clarification frequency.

When to use which approach

Smart agent pattern: auto-detect context

The most effective agents don’t wait for the user to provide context — they extract it from the codebase automatically. Here’s the pattern:

import { readFile } from 'fs/promises';

async function buildSearchContext(projectRoot: string) {
  const context: Record<string, string> = {};

  // Detect language from package.json or pyproject.toml
  try {
    const pkg = JSON.parse(await readFile(`${projectRoot}/package.json`, 'utf-8'));
    context.language = pkg.devDependencies?.typescript ? 'TypeScript' : 'JavaScript';
  } catch {
    try {
      await readFile(`${projectRoot}/pyproject.toml`, 'utf-8');
      context.language = 'Python';
    } catch {
      // Language unknown — let clarification handle it
    }
  }

  // Detect deployment from Docker or cloud configs
  try {
    await readFile(`${projectRoot}/Dockerfile`, 'utf-8');
    context.deployment = 'self-hosted';
  } catch {
    // No Dockerfile — might be cloud or embedded
  }

  return context;
}

Recap

Rich context is a power-user feature. By adding a context object with language, category, license, or deployment filters to your search_tools call, you skip clarification entirely and get instant results. For the best experience, build agents that auto-detect project context from the codebase.