Semantic + lexical (hybrid) search over an indexed source. This is your PRIMARY search tool — use it FIRST for any question about the indexed code or docs. Omit source to search ALL sources at once (rankings fused via RRF, each hit tagged with its source); pass source to target one. Configured sources: . Best practices: use natural-language descriptions of what the code does, not exact identifiers (use grep for those). Good: 'method that handles player damage calculation'. Bad: 'CalculateDamage'. Args: query (natural language); source (optional name); top_k (default from config); file_glob, extensions, path_contains (optional filters). For broad/exploratory queries, or a large top_k, set outline=true to get signatures-only results (much cheaper to read): scan them, then pull just the one body you need with find_definition or its file:line. Use the default (full bodies) when you'll work with the code right away.

Multi-query fallback search. ESCALATION TOOL — use only when search returned weak or empty results, or when the user explicitly asks for a more thorough search. Slower than search because it runs multiple retrievals. How it works: tries each query variant in order; stops at the first whose results pass the weakness threshold. If all fail, returns the strongest weak set with a warning. Omit source to run across ALL sources (RRF-fused); pass source to target one. Configured sources: . Best practices: provide 2-4 GENUINELY DIFFERENT phrasings (different angles, not paraphrases). Good: ['player health system', 'damage and healing logic', 'HP component lifecycle']. Bad: ['player health', 'health of the player'] (too similar). Args: queries (ordered list of variants); source (optional name); top_k; mode ('dense'|'sparse'|'hybrid', single-source only); file_glob, extensions, path_contains; min_score, min_results (threshold overrides); return_all_variants (per-variant diagnostics, single-source only).

List all configured sources with their type, location, chunk count, and drift status.

    Call this first when you don't know which sources are available.
    Pass a name from this list as the `source` argument of the other
    tools (`search`, `deep_search`, `graph_query`, `find_*`, ...).
    

Force a full rebuild of a specific source's index.

    Day-to-day the watcher keeps the index in sync automatically; you rarely need this.
    Use it after a complex merge, a bulk rename, or when drift detection flags a
    critical change (e.g. embedding model swap).

    Do NOT call this routinely — it is expensive and blocks until complete.
    Call `get_rag_status` first to check if a rebuild is actually needed.

    Args:
        source: Name of the source to rebuild. Use `list_sources` to discover names.
        force: If True, rebuild even when no new git commits are detected.
    

Report state of the RAG index for one source or all sources.

    Use this to check if the index is up to date before deciding whether to
    call `update_source_index`. Also useful for debugging when search results
    seem stale or incomplete.

    Args:
        source: Specific source name to inspect. If None, returns the
            status of every configured source.
    

Report that you could not find what you needed. Call this BEFORE giving up after exhausting search / deep_search / graph_query. The report is appended to a LOCAL log file on this machine (rag_storage/_feedback/feedback.jsonl) — it is never uploaded anywhere — and helps the index owner tune sources, filters, and chunking. Args: trying_to_do (what you were trying to find or answer); tried (which tools/queries you already tried); stuck (where exactly you got blocked or what was missing).