[KM-630] Data-Access Tools: review fixes

- describe_source: add table_row_count column (the registry tool
description advertises row counts; output now matches the contract).
- retrieve_documents: coerce top_k to int with a fallback to 5, so a
non-int top_k from the Planner can't reach the retriever unguarded.
- Refresh the module docstring to list all four tools (query_structured
and retrieve_documents were missing).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

src/tools/data_access.py

@@ -1,15 +1,22 @@
-"""DataAccessToolInvoker — catalog-introspection tools (KM-465).
+"""DataAccessToolInvoker — the data-access tool family (KM-465 / KM-630).
 
 Implements the `ToolInvoker` Protocol (src/agents/slow_path/invoker.py) for the
-data-access / catalog-introspection family. Unlike the stateless
-`AnalyticsToolInvoker`, these tools read the user's catalog, so the invoker is
-constructed per-request with the authenticated `user_id` and a `CatalogReader`
-(dependency injection — the runtime/Coordinator supplies them; INV-7 keeps the
-agent layer tool-agnostic).
+data-access family. Unlike the stateless `AnalyticsToolInvoker`, these tools
+read the user's catalog / sources, so the invoker is constructed per-request
+with the authenticated `user_id` and its dependencies (dependency injection —
+the runtime/Coordinator supplies them; INV-7 keeps the agent layer
+tool-agnostic).
 
 Tools implemented here:
-- `list_sources`    — the user's data sources (id, name, type, table count).
-- `describe_source` — tables/columns of one source (schema, one row per column).
+- `list_sources`      — the user's data sources (id, name, type, table count).
+- `describe_source`   — tables/columns of one source (one row per column,
+                        metadata only — exposes `pii_flag`, never sample values).
+- `query_structured`  — runs a pre-built `QueryIR` (validate -> dispatch ->
+                        execute, skipping the planner) and returns rows as
+                        `ToolOutput(kind="table")` — the Pattern A handoff the
+                        `analyze_*` tools consume.
+- `retrieve_documents` — dense retrieval over unstructured sources, returns
+                        `ToolOutput(kind="documents")`.
 
 Frozen guarantee (§8.4): **never throws.** Any failure returns
 `ToolOutput(kind="error", error=...)`.
@@ -132,6 +139,7 @@ class DataAccessToolInvoker:
             [
                 t.table_id,
                 t.name,
+                t.row_count,
                 c.column_id,
                 c.name,
                 c.data_type,
@@ -147,6 +155,7 @@ class DataAccessToolInvoker:
             columns=[
                 "table_id",
                 "table_name",
+                "table_row_count",
                 "column_id",
                 "column_name",
                 "data_type",
@@ -249,7 +258,10 @@ class DataAccessToolInvoker:
                 error="missing 'query' argument",
             )
 
-        top_k = args.get("top_k", 5)
+        try:
+            top_k = int(args.get("top_k", 5))
+        except (TypeError, ValueError):
+            top_k = 5
         source_id = args.get("source_id")
 
         retriever = self._retriever