Search effectively

search_context works well with a plain query, but hard questions benefit from the knobs it exposes. This guide applies to both the REST endpoint (POST /api/v1/search_context) and the MCP tool.

Start simple

{
  "query": "deployment requirements",
  "limit": 10
}

The query supports websearch syntax: "quoted phrases" for exact matches and -excluded terms. strategy can force keyword or semantic retrieval; the default hybrid fuses both.

Add typed sub-queries

When one phrasing is not enough, supply 1 to 8 typed sub-queries. They are fused with the original query by weighted reciprocal-rank fusion, and the original always runs at double weight so sub-queries broaden recall without hijacking the ask.

{
  "query": "deployment requirements",
  "searches": [
    { "type": "lex", "text": "\"production requirements\" -staging" },
    { "type": "vec", "text": "what is needed to run the app in production" },
    { "type": "hyde", "text": "Production deployments require PostgreSQL 16, Redis, and the DATABASE_URL and SESSION_SECRET environment variables." }
  ]
}

• lex carries exact keywords to full-text search.
• vec carries a natural-language restatement to vector search.
• hyde carries a 30 to 80 word hypothetical answer passage that is embedded in place of the question. Write it as if you were the document you hope to find.

Control the output

• limit: maximum chunks (default 10, max 50)
• minScore: drop weak results below a score threshold
• tokenBudget: approximate token budget for the returned content
• explain: attach per-result score traces when you need to debug ranking

Decide how fresh the answer has to be

mode controls how far a search reaches into connected sources whose bodies are cataloged but not indexed:

{
  "query": "who owns the billing webhook retry logic",
  "mode": "fresh",
  "sourceIds": ["4f6c2d8a-1b7e-4a52-9c31-0d5f8e2a7b64"]
}

• fast stays inside retained content and never contacts a provider. Use it in tight loops where latency matters more than coverage.
• balanced is the default. It also searches the catalog and live-fetches a few decisively matching bodies.
• fresh adds live-answering providers such as issue trackers, at the cost of more upstream calls.

sourceIds narrows a search to specific sources. When the question is really about one provider, query_source goes straight at it, and fetch_source_document pulls one document's full body by external ID.

Read the coverage block alongside results: it names what was fetched live, what the catalog lists but was not fetched, and whether a daily provider budget cut the search short. Treat it as routing information, not as evidence to quote.

Read ranges, not files

Every result carries a location with startLine/endLine anchors and the Markdown headingPath. Follow up with a ranged get_file:

{
  "name": "get_file",
  "arguments": { "id": "abc123", "fromLine": 120, "maxLines": 80 }
}

This keeps agent context small and cites the exact lines that answered the question.

Prefer bundles for known workflows

If the task matches a curated workflow, load a bundle instead of searching: list_bundles shows each bundle's useWhen guidance, and get_bundle returns the complete current contents of its files. See Retrieval.