[KM-642] refactor(tools): rename data-access tools to data/knowledge naming

Mechanical rename across the tool layer, the planner stub/validator/prompt/
few-shots, and docstrings: query_structured -> data_retrieve and
retrieve_documents -> knowledge_retrieve (data/knowledge taxonomy from the
2026-06-11 checkpoint). No behavior change; the data_check/knowledge_check
merge lands in a follow-up. Tests green (206 passed); all changed files pass
ruff, data_access.py clean under mypy.

Touches the planner area (prompt, validator, examples) — rename only,
wording preserved. Flagged for Rifqi review.

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

src/agents/planner/examples.py

@@ -2,7 +2,7 @@
 
 Two illustrative (question -> TaskList) pairs that teach the OUTPUT SHAPE:
 stages, dependency edges, ordered tool-call chains, inline QueryIR,
-"${t<id>}" placeholders, and the assumed data-flow convention — `query_structured`
+"${t<id>}" placeholders, and the assumed data-flow convention — `data_retrieve`
 pulls rows, then a composite `analyze_*` tool consumes them via a `data` placeholder
 referencing the upstream result's column aliases (Pattern A; the tool team may
 instead pick self-fetch by `source_id`, in which case these examples are reshaped
@@ -21,7 +21,7 @@ from .schemas import Task, TaskList, ToolCall
 # --------------------------------------------------------------------------- #
 # Example A — exploratory, no modeling.
 # "Which product categories drove last quarter's revenue?"
-# Shows: query_structured pulls rows -> analyze_aggregate sums revenue per
+# Shows: data_retrieve pulls rows -> analyze_aggregate sums revenue per
 # category in one call (no manual per-category queries).
 # --------------------------------------------------------------------------- #
 
@@ -47,7 +47,7 @@ _EXAMPLE_A = TaskList(
             objective="Pull last quarter's order-level category and revenue rows.",
             tool_calls=[
                 ToolCall(
-                    tool="query_structured",
+                    tool="data_retrieve",
                     args={
                         "ir": {
                             "source_id": "src_sales",
@@ -123,7 +123,7 @@ _EXAMPLE_B = TaskList(
             objective="Pull this year's order dates, revenue, and region.",
             tool_calls=[
                 ToolCall(
-                    tool="query_structured",
+                    tool="data_retrieve",
                     args={
                         "ir": {
                             "source_id": "src_sales",
@@ -187,8 +187,8 @@ _EXAMPLE_B = TaskList(
 # Example C — mixed structured + unstructured.
 # "Revenue dipped in Q1 — what happened?"
 # Shows: a structured branch (query -> analyze_trend) runs alongside an
-# INDEPENDENT retrieve_documents branch that pulls qualitative context. Note
-# retrieve_documents takes a natural-language `query` (NOT a `${t<id>}` data
+# INDEPENDENT knowledge_retrieve branch that pulls qualitative context. Note
+# knowledge_retrieve takes a natural-language `query` (NOT a `${t<id>}` data
 # placeholder — it is a source, not a consumer) and can run in parallel; the
 # Assembler folds the document context into the explanation.
 # --------------------------------------------------------------------------- #
@@ -215,7 +215,7 @@ _EXAMPLE_C = TaskList(
             objective="Pull Q1 order dates and revenue.",
             tool_calls=[
                 ToolCall(
-                    tool="query_structured",
+                    tool="data_retrieve",
                     args={
                         "ir": {
                             "source_id": "src_sales",
@@ -273,7 +273,7 @@ _EXAMPLE_C = TaskList(
             objective="Retrieve qualitative context on Q1 operational events behind a dip.",
             tool_calls=[
                 ToolCall(
-                    tool="retrieve_documents",
+                    tool="knowledge_retrieve",
                     args={
                         "query": "operational issues, outages, or notable events in Q1 2026",
                         "top_k": 5,
@@ -320,7 +320,7 @@ _EXAMPLE_D = TaskList(
             objective="Pull order-level region and revenue.",
             tool_calls=[
                 ToolCall(
-                    tool="query_structured",
+                    tool="data_retrieve",
                     args={
                         "ir": {
                             "source_id": "src_sales",

src/agents/planner/inputs.py

@@ -4,9 +4,9 @@
 for the planner prompt. It carries every table + column id/type/PII flag + row
 counts + low-cardinality top_values, with `sample_values` nulled on PII columns
 (INV: no PII sample values into the prompt, see doc §13). It also lists the
-available unstructured sources so the planner can plan `retrieve_documents`.
+available unstructured sources so the planner can plan `knowledge_retrieve`.
 
-The planner *validator* still checks inline `query_structured` IRs against the
+The planner *validator* still checks inline `data_retrieve` IRs against the
 full `Catalog` via the existing IRValidator — the summary is a prompt input, not
 the validation source of truth.
 
@@ -124,7 +124,7 @@ class CatalogSummary(BaseModel):
             lines.append("")
 
         if self.unstructured_sources:
-            lines.append("Unstructured sources (for retrieve_documents):")
+            lines.append("Unstructured sources (for knowledge_retrieve):")
             for src in self.unstructured_sources:
                 lines.append(f"  - {src.name} — id={src.source_id}")
 

src/agents/planner/registry.py

@@ -7,7 +7,7 @@ outside it).
   `src/tools/registry.py::analytics_registry()` (KM-628), built on the canonical
   `ToolSpec` (`src/tools/contracts.py`, KM-465/KM-627) and the prompt-style tool
   descriptions (KM-625). No longer a stub on our side — it tracks the real registry.
-- **Data access (`query_structured` / `retrieve_documents` / `list_sources` /
+- **Data access (`data_retrieve` / `knowledge_retrieve` / `list_sources` /
   `describe_source`) — spec BODIES still a local stub.** The tool team owns these too,
   but their wrappers + `ToolSpec`s haven't landed yet (KM-465 #4). We keep best-guess
   spec bodies here so the Planner can plan end-to-end — but the NAMES derive from
@@ -16,10 +16,10 @@ outside it).
   this slice and swap `default_registry()` for the tool team's full composition.
 
 **Confirmed conventions (KM-465):** Pattern A — `analyze_*` tools take a `data`
-`"${t<id>}"` placeholder pointing at an upstream `query_structured` output (no
+`"${t<id>}"` placeholder pointing at an upstream `data_retrieve` output (no
 self-fetch); resolved to a DataFrame at execution time. `input_schema` is the
 lightweight `{required, properties}` dict the planner validator (check #8) reads;
-`query_structured.args["ir"]` carries an inline QueryIR validated against the
+`data_retrieve.args["ir"]` carries an inline QueryIR validated against the
 catalog by the existing IRValidator.
 
 See AGENT_ARCHITECTURE_CONTEXT_new.md §9.2 / §9.3.
@@ -38,7 +38,7 @@ from .contracts import ToolRegistry, ToolSpec
 # --------------------------------------------------------------------------- #
 _DATA_ACCESS_SPEC_BODIES: tuple[ToolSpec, ...] = (
     ToolSpec(
-        name="query_structured",
+        name="data_retrieve",
         category="analytics.query",
         input_schema={"required": ["ir"], "properties": {"ir": {"type": "object"}}},
         output_kind="table",
@@ -52,11 +52,11 @@ _DATA_ACCESS_SPEC_BODIES: tuple[ToolSpec, ...] = (
             "(count/sum/avg/min/max/count_distinct). Do NOT use it for richer statistics "
             "(median/percentile/mode/stddev/skew → analyze_descriptive), trends "
             "(analyze_trend), correlation, segmentation, or share-of-total; and do NOT "
-            "use it to read documents (use retrieve_documents)."
+            "use it to read documents (use knowledge_retrieve)."
         ),
     ),
     ToolSpec(
-        name="retrieve_documents",
+        name="knowledge_retrieve",
         category="retrieval.documents",
         input_schema={
             "required": ["query"],
@@ -71,7 +71,7 @@ _DATA_ACCESS_SPEC_BODIES: tuple[ToolSpec, ...] = (
             "Dense-retrieve the most relevant chunks from the user's unstructured "
             "sources (PDF/DOCX/TXT) for a natural-language `query`. Use this to pull "
             "qualitative context into an analysis. Optionally scope to one `source_id`. "
-            "Do NOT use it for numbers in tables — that is query_structured's job."
+            "Do NOT use it for numbers in tables — that is data_retrieve's job."
         ),
     ),
     ToolSpec(
@@ -96,7 +96,7 @@ _DATA_ACCESS_SPEC_BODIES: tuple[ToolSpec, ...] = (
         description=(
             "Return the tables and columns (names, types, row counts) of one source by "
             "`source_id`. Use in data_understanding to confirm the shape of a source "
-            "before querying it. Do NOT use it to fetch data rows (use query_structured)."
+            "before querying it. Do NOT use it to fetch data rows (use data_retrieve)."
         ),
     ),
 )

src/agents/planner/service.py

@@ -9,7 +9,7 @@ static plan.
 
 The service takes the full `Catalog` (not just a `CatalogSummary`): it derives
 the PII-safe `CatalogSummary` for the prompt, but validation needs the full
-catalog so the existing `IRValidator` can check inline `query_structured` IRs.
+catalog so the existing `IRValidator` can check inline `data_retrieve` IRs.
 
 See AGENT_ARCHITECTURE_CONTEXT_new.md §7.3.
 """

src/agents/planner/validator.py

@@ -95,8 +95,8 @@ class PlannerValidator:
                             f"source_id {src!r} (known: {sorted(known_sources)})"
                         )
 
-                # Check 8b — inline query_structured IR validates against the catalog.
-                if call.tool == "query_structured":
+                # Check 8b — inline data_retrieve IR validates against the catalog.
+                if call.tool == "data_retrieve":
                     self._validate_inline_ir(task.id, call.args, catalog)
 
             # Check 7 — success_criteria is checkable.
@@ -114,20 +114,20 @@ class PlannerValidator:
         raw_ir = args.get("ir")
         if not isinstance(raw_ir, dict):
             raise PlannerValidationError(
-                f"task {task_id}: query_structured.args.ir must be an inline QueryIR "
+                f"task {task_id}: data_retrieve.args.ir must be an inline QueryIR "
                 f"object, got {type(raw_ir).__name__}"
             )
         try:
             ir = QueryIR.model_validate(raw_ir)
         except ValidationError as e:
             raise PlannerValidationError(
-                f"task {task_id}: query_structured.args.ir is not a valid QueryIR: {e}"
+                f"task {task_id}: data_retrieve.args.ir is not a valid QueryIR: {e}"
             ) from e
         try:
             self._ir_validator.validate(ir, catalog)
         except IRValidationError as e:
             raise PlannerValidationError(
-                f"task {task_id}: query_structured IR failed catalog validation: {e}"
+                f"task {task_id}: data_retrieve IR failed catalog validation: {e}"
             ) from e
 
     @staticmethod

src/catalog/reader.py

@@ -45,7 +45,7 @@ class MemoizingCatalogReader(CatalogReader):
 
     One per request. The same per-user catalog is otherwise fetched from the
     catalog DB 4-5x during a single slow-path run (planner load, then
-    describe_source's structured+unstructured reads, then query_structured's
+    describe_source's structured+unstructured reads, then data_retrieve's
     structured read). Wrapping the base reader collapses those to one round-trip
     per distinct source_hint and pins a single consistent snapshot for the whole
     request (plan-time and execution-time catalogs can no longer diverge).

src/config/prompts/planner.md

@@ -10,7 +10,7 @@ only a `TaskList` object that conforms to the provided schema.
 
 1. **Emit intent, never code.** Never write SQL, pandas, or any code. The only
    query you express is an inline `QueryIR` (a JSON intent object) inside a
-   `query_structured` tool call's `args.ir`.
+   `data_retrieve` tool call's `args.ir`.
 2. **The plan is static.** There is no replanning and no execution feedback. Plan
    the whole analysis up front; assume each task runs once, in dependency order.
 3. **Use only tools from the "Available tools" list.** Never invent a tool name.
@@ -31,16 +31,16 @@ only a `TaskList` object that conforms to the provided schema.
 - **Wire data between tasks with placeholders.** When a task needs an upstream
   task's output as an argument, use the string `"${t<id>}"` (e.g. `"${t2}"`) as
   the argument value. Set `depends_on` accordingly.
-- **Data access vs analytics tools.** `query_structured` is the data-access entry
+- **Data access vs analytics tools.** `data_retrieve` is the data-access entry
   point: use it to select, filter, and pull rows (and simple built-in
   count/sum/avg/min/max/count_distinct the IR can express). For anything richer —
   descriptive statistics (median/percentile/mode/std/skew), time trends, group
   comparisons, share-of-total, correlation, segmentation, or data-quality
-  profiling — run `query_structured` to fetch the rows, then pass its output to
+  profiling — run `data_retrieve` to fetch the rows, then pass its output to
   the matching composite `analyze_*` tool via a `"${t<id>}"` `data` argument
   (referencing the upstream result's column aliases).
 - **Mixing structured + unstructured.** If qualitative context helps, add a
-  `retrieve_documents` task against an unstructured source listed in the catalog.
+  `knowledge_retrieve` task against an unstructured source listed in the catalog.
 - **CRISP-DM stages.** Tag each task with the stage it serves:
   `data_understanding`, `data_preparation`, or `evaluation`. (Never `modeling`.)
 - **success_criteria is a reporting signal**, not a control trigger. State, in

src/query/executor/db.py

@@ -220,7 +220,7 @@ class DbExecutor(BaseExecutor):
         """Best-effort: warm pooled engines for the catalog's schema sources.
 
         Called at slow-path entry so the TCP+TLS+auth handshake overlaps the ~4s
-        Planner LLM call — by the time `query_structured` runs, the connection is
+        Planner LLM call — by the time `data_retrieve` runs, the connection is
         already established. Warming is an optimization, never a requirement, so
         this never raises and per-source failures are swallowed.
         """

src/tools/analytics/aggregation.py

@@ -3,7 +3,7 @@
 An analytical "family" tool: in ONE call it groups rows by one or more keys
 and computes aggregates (sum, mean, count, min, max, median, nunique) per
 group. This is the deterministic compute twin of the Planner's
-`query_structured` step — the wrapper layer later maps a QueryIR onto this.
+`data_retrieve` step — the wrapper layer later maps a QueryIR onto this.
 
 STATUS: compute layer only — the function takes an already-materialized
 DataFrame. The wrapper layer (fetching data from the catalog via source_id,

src/tools/data_access.py

@@ -11,11 +11,11 @@ Tools implemented here:
 - `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 ->
+- `data_retrieve`  — 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
+- `knowledge_retrieve` — dense retrieval over unstructured sources, returns
                         `ToolOutput(kind="documents")`.
 
 Frozen guarantee (§8.4): **never throws.** Any failure returns
@@ -47,7 +47,7 @@ DispatcherFactory = Callable[[Catalog], ExecutorDispatcher]
 # adding/renaming a data-access tool can't silently drift the router out of sync
 # from the registry (R11). Must match the names in `DataAccessToolInvoker.invoke`.
 DATA_ACCESS_TOOLS: frozenset[str] = frozenset(
-    {"list_sources", "describe_source", "query_structured", "retrieve_documents"}
+    {"list_sources", "describe_source", "data_retrieve", "knowledge_retrieve"}
 )
 
 
@@ -73,14 +73,14 @@ class DataAccessToolInvoker:
     ) -> None:
         self._user_id = user_id
         self._reader = catalog_reader
-        # query_structured deps — injectable so tests need no real LLM/DB. The
+        # data_retrieve deps — injectable so tests need no real LLM/DB. The
         # validator is stateless; the dispatcher is built per-call from the
         # request's catalog (executors are picked by source_type).
         self._validator = ir_validator or IRValidator()
         self._dispatcher_factory: DispatcherFactory = (
             dispatcher_factory or ExecutorDispatcher
         )
-        # retrieve_documents dep — the module singleton by default, injectable
+        # knowledge_retrieve dep — the module singleton by default, injectable
         # for tests (the real one pulls PGVector + Redis). Lazy-imported on first
         # use so importing this module stays cheap.
         self._retriever = document_retriever
@@ -91,10 +91,10 @@ class DataAccessToolInvoker:
                 return await self._list_sources()
             if tool_name == "describe_source":
                 return await self._describe_source(args)
-            if tool_name == "query_structured":
-                return await self._query_structured(args)
-            if tool_name == "retrieve_documents":
-                return await self._retrieve_documents(args)
+            if tool_name == "data_retrieve":
+                return await self._data_retrieve(args)
+            if tool_name == "knowledge_retrieve":
+                return await self._knowledge_retrieve(args)
             return ToolOutput(
                 tool=tool_name, kind="error", error=f"unknown tool {tool_name!r}"
             )
@@ -183,7 +183,7 @@ class DataAccessToolInvoker:
             },
         )
 
-    async def _query_structured(self, args: dict[str, Any]) -> ToolOutput:
+    async def _data_retrieve(self, args: dict[str, Any]) -> ToolOutput:
         """Run one validated, single-table QueryIR and return rows as a table.
 
         This is the spine of the slow path (Pattern A): the `analyze_*` tools
@@ -196,14 +196,14 @@ class DataAccessToolInvoker:
         raw = args.get("ir")
         if raw is None:
             return ToolOutput(
-                tool="query_structured", kind="error", error="missing 'ir' argument"
+                tool="data_retrieve", kind="error", error="missing 'ir' argument"
             )
 
         try:
             ir = raw if isinstance(raw, QueryIR) else QueryIR.model_validate(raw)
         except ValidationError as exc:
             return ToolOutput(
-                tool="query_structured", kind="error", error=f"invalid IR: {exc}"
+                tool="data_retrieve", kind="error", error=f"invalid IR: {exc}"
             )
 
         catalog = await self._reader.read(self._user_id, "structured")
@@ -212,7 +212,7 @@ class DataAccessToolInvoker:
             self._validator.validate(ir, catalog)
         except IRValidationError as exc:
             return ToolOutput(
-                tool="query_structured",
+                tool="data_retrieve",
                 kind="error",
                 error=f"IR validation failed: {exc}",
             )
@@ -223,7 +223,7 @@ class DataAccessToolInvoker:
 
         if result.error:
             return ToolOutput(
-                tool="query_structured", kind="error", error=result.error
+                tool="data_retrieve", kind="error", error=result.error
             )
 
         # QueryResult.rows is list[dict]; ToolOutput.rows is list[list] ordered
@@ -235,7 +235,7 @@ class DataAccessToolInvoker:
             [_json_safe(row.get(c)) for c in result.columns] for row in result.rows
         ]
         return ToolOutput(
-            tool="query_structured",
+            tool="data_retrieve",
             kind="table",
             columns=result.columns,
             rows=rows,
@@ -251,7 +251,7 @@ class DataAccessToolInvoker:
             },
         )
 
-    async def _retrieve_documents(self, args: dict[str, Any]) -> ToolOutput:
+    async def _knowledge_retrieve(self, args: dict[str, Any]) -> ToolOutput:
         """Dense-retrieve relevant chunks from the user's unstructured sources.
 
         Pulls qualitative context (PDF/DOCX/TXT) for a natural-language `query`
@@ -259,7 +259,7 @@ class DataAccessToolInvoker:
         `source_id` scopes to one source (best-effort metadata filter — the
         router itself does not yet scope by source, so this prunes the results).
 
-        TODO(retrieval scoping): the Planner few-shot has no `retrieve_documents`
+        TODO(retrieval scoping): the Planner few-shot has no `knowledge_retrieve`
         example, so `source_id` is rarely emitted today and this post-filter is
         adequate. If source-scoped retrieval becomes common, push scoping down
         into RetrievalRouter.retrieve()/DocumentRetriever (WHERE
@@ -269,7 +269,7 @@ class DataAccessToolInvoker:
         query = args.get("query")
         if not isinstance(query, str) or not query.strip():
             return ToolOutput(
-                tool="retrieve_documents",
+                tool="knowledge_retrieve",
                 kind="error",
                 error="missing 'query' argument",
             )
@@ -300,7 +300,7 @@ class DataAccessToolInvoker:
             for r in results
         ]
         return ToolOutput(
-            tool="retrieve_documents",
+            tool="knowledge_retrieve",
             kind="documents",
             value=documents,
             meta={

src/tools/registry.py

@@ -8,7 +8,7 @@ reads to choose a tool (KM-625). This replaces the agent team's local stub in
 Conventions (decided with the agent team, KM-465):
 - **Pattern A** — `analyze_*` tools do NOT self-fetch by `source_id`. Each takes a
   `data` argument that is a `"${t<id>}"` placeholder pointing at an upstream
-  `query_structured` table output, resolved to a DataFrame at execution time.
+  `data_retrieve` table output, resolved to a DataFrame at execution time.
   Column arguments reference the aliases that upstream query produced.
 - `input_schema` is the lightweight JSON-schema-ish dict the planner validator
   consumes: `required` (arg names with no default) + `properties` (allowed args).
@@ -17,7 +17,7 @@ Conventions (decided with the agent team, KM-465):
 - `output_kind` is the `ToolOutput.kind` each tool returns: stats (labelled-metric
   dict) | table (rows×cols) | series (ordered periods).
 
-The four data-access tools (query_structured / retrieve_documents / list_sources /
+The four data-access tools (data_retrieve / knowledge_retrieve / list_sources /
 describe_source) are registered separately once their wrappers land (KM-465 #4);
 `default_registry()` composes both slices.
 """