docs: align MCP tool descriptions with code

.agents/docs/architecture.md

@@ -316,23 +316,25 @@ Contract intent:
   stack. It fans out retained-source `sync_source` runs concurrently, preserves
   each source's existing running-job guard, and reports mixed source outcomes
   truthfully instead of pretending the whole batch succeeded when one source was
-  blocked or failed. Disabled or unconfigured sources may surface as `skipped`,
-  and the top-level batch status remains `completed` only when the aggregate
-  outcomes are limited to `succeeded` and `skipped`.
+  blocked or failed. Disabled sources may surface as `skipped`, and the
+  top-level batch status remains `completed` only when the aggregate outcomes
+  are limited to `succeeded` and `skipped`.
 - `search_documents` is additive and document-oriented: it uses the same
   retained-source retrieval path but returns one representative chunk-backed row
   per document for browsing.
 - `answer_with_citations` reuses `search_context_for_answer` /
   `search_context`, so query-rewrite egress and retrieval semantics stay aligned
   across search and answer flows.
-- `search_context` always returns a `debug` key. On the normal path,
-  `include_debug=False` leaves that key as `{}`, while `include_debug=True`
-  populates it with structured retrieval detail.
+- `search_context` returns a `debug` key on configured search-service paths.
+  On the normal path, `include_debug=False` leaves that key as `{}`, while
+  `include_debug=True` populates it with structured retrieval detail. The
+  current service-unconfigured fallback returns only `query` and `results`.
 - The current public exception is `search_context`'s `no_matching_sources`
   fast path, which still returns a small populated `debug` object even when
   `include_debug=False`.
-- `answer_with_citations` keeps `include_debug` as a true opt-in debug surface
-  and does not mirror the `no_matching_sources` exception path.
+- `answer_with_citations` keeps `include_debug` as a true opt-in debug surface,
+  does not mirror the `no_matching_sources` exception path, and does not
+  guarantee debug fields on default or service-unconfigured paths.
 - Retrieval policy keeps vector retrieval, metadata fallback, and rerank/debug
   reporting as distinct concerns. Query rewrite, fallback candidate addition,
   and final SQLite validation should stay inspectable without blurring them into

README.md

@@ -37,14 +37,16 @@ vector and metadata stores, then returns verified, citation-backed context.
 | `get_sync_status(source_id="")` | Get source and sync job status. |
 | `search_context(query, ...)` | Semantic search with SQLite-validated chunks. |
 | `search_documents(query, ...)` | Search results grouped by document. |
-| `fetch_context(document_id, chunk_id)` | Fetch a specific document or chunk directly. |
-| `answer_with_citations(question, ...)` | Citation-backed answer preview for preview/debug/eval use. |
+| `fetch_context(document_id="", chunk_id="")` | Fetch a specific document or chunk directly; provide at least one input. |
+| `answer_with_citations(question, ...)` | Evidence-aware answer preview for preview/debug/eval use. |
 
-> In production, use `search_context` or `search_documents` to gather grounded
-> evidence, then let a downstream LLM generate the final answer.
+> In production, use `search_context` to gather grounded evidence and use
+> `search_documents` for document discovery, then let a downstream LLM generate
+> the final answer.
 
 When validating `answer_with_citations`, inspect `citations`, `used_chunks`,
-and `debug` or `debug_markdown` when enabled.
+and, when the request reaches a configured answer-service path with
+`include_debug=True`, `debug` or `debug_markdown`.
 
 ---
 

api/tools.py

@@ -321,7 +321,7 @@ async def answer_with_citations(
         top_k: int = 5,
         include_debug: bool = False,
     ) -> dict:
-        """검색 근거 기반 helper answer preview와 citation/debug 데이터를 반환"""
+        """검색 근거 기반 helper answer payload를 반환하고 answer service 경로에서만 include_debug를 전달"""
         public_filters, has_no_public_source = _public_filters(
             filters,
             metadata_store,