Search effectively

search_context works well with a plain query. For difficult questions, use its additional parameters. This guide applies to the REST endpoint (POST /api/v1/search_context) and to the MCP tool.

Start simple

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

The query supports websearch syntax. Use "quoted phrases" for exact matches and -excluded for terms to exclude. Use strategy to force keyword or semantic retrieval. The default is hybrid, which combines the two.

Add typed sub-queries

If one phrase is not sufficient, supply 1 to 8 typed sub-queries. Orcha combines them with the original query by weighted reciprocal-rank fusion. The original query always has double weight. Thus sub-queries increase recall, but they do not replace the original question.

{
  "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 sends exact keywords to full-text search.
vec sends a natural-language restatement to vector search.
hyde sends a hypothetical answer passage of 30 to 80 words. Orcha makes an embedding of this passage and uses it in place of the question. Write the passage as the text of the document that you want to find.

Control the output

limit: the maximum number of chunks (default 10, max 50)
minScore: removes weak results below a score threshold
tokenBudget: the approximate token budget for the returned content
explain: adds score traces to each result, to help you debug the rank

Decide how fresh the answer has to be

mode controls how much a search uses connected sources that have bodies in the catalog but not in the index:

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

fast uses only kept content and does not contact a provider. Use it in tight loops where latency is more important than coverage.
balanced is the default. It also searches the catalog. It fetches a small number of bodies live if they are strong matches.
fresh also uses providers that answer live, for example issue trackers. This mode makes more upstream calls.

Use sourceIds to limit a search to specific sources. If the question is about one provider only, use query_source to query it directly. Use fetch_source_document to get the full body of one document by external ID.

Read the coverage block together with results. The block tells which documents Orcha fetched live. It tells which documents are in the catalog but Orcha did not fetch. It also tells if a daily provider budget stopped the search early. Use the block as routing information. Do not quote it as evidence.

Read ranges, not files

Each result has a location with startLine/endLine anchors and the Markdown headingPath. Then use a ranged get_file:

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

This keeps the agent context small. It also cites the exact lines that answer the question.

Prefer memories for known workflows

If the task matches a curated workflow, load a memory. Do not search. list_memories shows the useWhen guidance for each memory. get_memory returns the complete current contents of its members. Members are files, expanded folders, synced documents, and database records. Refer to Retrieval.