[NOTICKET] Adopt verb-first skill naming

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 — `data_retrieve`
+"${t<id>}" placeholders, and the assumed data-flow convention — `retrieve_data`
 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: data_retrieve pulls rows -> analyze_aggregate sums revenue per
+# Shows: retrieve_data pulls rows -> analyze_aggregate sums revenue per
 # category in one call (no manual per-category queries).
 # --------------------------------------------------------------------------- #
 
@@ -35,7 +35,7 @@ _EXAMPLE_A = TaskList(
             id="t1",
             stage="data_understanding",
             objective="Confirm the sales source exposes category, revenue, and order date.",
-            tool_calls=[ToolCall(tool="data_check", args={"source_id": "src_sales"})],
+            tool_calls=[ToolCall(tool="check_data", args={"source_id": "src_sales"})],
             expected_output="source_shape",
             success_criteria="Produced the orders table schema; the 3 needed columns are present.",
             depends_on=[],
@@ -47,7 +47,7 @@ _EXAMPLE_A = TaskList(
             objective="Pull last quarter's order-level category and revenue rows.",
             tool_calls=[
                 ToolCall(
-                    tool="data_retrieve",
+                    tool="retrieve_data",
                     args={
                         "ir": {
                             "source_id": "src_sales",
@@ -111,7 +111,7 @@ _EXAMPLE_B = TaskList(
             id="t1",
             stage="data_understanding",
             objective="Confirm the sales source exposes order date, revenue, and region.",
-            tool_calls=[ToolCall(tool="data_check", args={"source_id": "src_sales"})],
+            tool_calls=[ToolCall(tool="check_data", args={"source_id": "src_sales"})],
             expected_output="source_shape",
             success_criteria="Produced the orders table schema; the needed columns are present.",
             depends_on=[],
@@ -123,7 +123,7 @@ _EXAMPLE_B = TaskList(
             objective="Pull this year's order dates, revenue, and region.",
             tool_calls=[
                 ToolCall(
-                    tool="data_retrieve",
+                    tool="retrieve_data",
                     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 knowledge_retrieve branch that pulls qualitative context. Note
-# knowledge_retrieve takes a natural-language `query` (NOT a `${t<id>}` data
+# INDEPENDENT retrieve_knowledge branch that pulls qualitative context. Note
+# retrieve_knowledge 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.
 # --------------------------------------------------------------------------- #
@@ -203,7 +203,7 @@ _EXAMPLE_C = TaskList(
             id="t1",
             stage="data_understanding",
             objective="Confirm the sales source exposes order date and revenue.",
-            tool_calls=[ToolCall(tool="data_check", args={"source_id": "src_sales"})],
+            tool_calls=[ToolCall(tool="check_data", args={"source_id": "src_sales"})],
             expected_output="source_shape",
             success_criteria="Produced the orders table schema; date and revenue columns present.",
             depends_on=[],
@@ -215,7 +215,7 @@ _EXAMPLE_C = TaskList(
             objective="Pull Q1 order dates and revenue.",
             tool_calls=[
                 ToolCall(
-                    tool="data_retrieve",
+                    tool="retrieve_data",
                     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="knowledge_retrieve",
+                    tool="retrieve_knowledge",
                     args={
                         "query": "operational issues, outages, or notable events in Q1 2026",
                         "top_k": 5,
@@ -308,7 +308,7 @@ _EXAMPLE_D = TaskList(
             id="t1",
             stage="data_understanding",
             objective="Confirm the sales source exposes region and revenue.",
-            tool_calls=[ToolCall(tool="data_check", args={"source_id": "src_sales"})],
+            tool_calls=[ToolCall(tool="check_data", args={"source_id": "src_sales"})],
             expected_output="source_shape",
             success_criteria="Produced the orders table schema; region and revenue present.",
             depends_on=[],
@@ -320,7 +320,7 @@ _EXAMPLE_D = TaskList(
             objective="Pull order-level region and revenue.",
             tool_calls=[
                 ToolCall(
-                    tool="data_retrieve",
+                    tool="retrieve_data",
                     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 `knowledge_retrieve`.
+available unstructured sources so the planner can plan `retrieve_knowledge`.
 
-The planner *validator* still checks inline `data_retrieve` IRs against the
+The planner *validator* still checks inline `retrieve_data` 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 knowledge_retrieve):")
+            lines.append("Unstructured sources (for retrieve_knowledge):")
             for src in self.unstructured_sources:
                 lines.append(f"  - {src.name} — id={src.source_id}")
 

src/agents/planner/registry.py

@@ -7,8 +7,8 @@ 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 (`data_retrieve` / `knowledge_retrieve` / `data_check` /
-  `knowledge_check`) — spec BODIES still a local stub.** The tool team owns these too,
+- **Data access (`retrieve_data` / `retrieve_knowledge` / `check_data` /
+  `check_knowledge`) — 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
   `src.tools.data_access.DATA_ACCESS_TOOLS` (R11), so a tool rename/addition upstream
@@ -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 `data_retrieve` output (no
+`"${t<id>}"` placeholder pointing at an upstream `retrieve_data` 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;
-`data_retrieve.args["ir"]` carries an inline QueryIR validated against the
+`retrieve_data.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="data_retrieve",
+        name="retrieve_data",
         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 knowledge_retrieve)."
+            "use it to read documents (use retrieve_knowledge)."
         ),
     ),
     ToolSpec(
-        name="knowledge_retrieve",
+        name="retrieve_knowledge",
         category="retrieval.documents",
         input_schema={
             "required": ["query"],
@@ -71,11 +71,11 @@ _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 data_retrieve's job."
+            "Do NOT use it for numbers in tables — that is retrieve_data's job."
         ),
     ),
     ToolSpec(
-        name="data_check",
+        name="check_data",
         category="catalog.introspection",
         input_schema={
             "required": [],
@@ -88,11 +88,11 @@ _DATA_ACCESS_SPEC_BODIES: tuple[ToolSpec, ...] = (
             "data_understanding to discover what exists. With a `source_id`, returns that "
             "source's tables and columns (names, types, row counts) — use to confirm a "
             "source's shape before querying it. Cheap. Do NOT use it to fetch data rows "
-            "(use data_retrieve) or to inspect documents (use knowledge_check)."
+            "(use retrieve_data) or to inspect documents (use check_knowledge)."
         ),
     ),
     ToolSpec(
-        name="knowledge_check",
+        name="check_knowledge",
         category="catalog.introspection",
         input_schema={"required": [], "properties": {}},
         output_kind="table",
@@ -100,7 +100,7 @@ _DATA_ACCESS_SPEC_BODIES: tuple[ToolSpec, ...] = (
             "List the user's unstructured sources / documents (id, name, type). Use in "
             "data_understanding to discover what qualitative material exists before "
             "retrieving from it. Do NOT use it to read document content (use "
-            "knowledge_retrieve) or to inspect structured data (use data_check)."
+            "retrieve_knowledge) or to inspect structured data (use check_data)."
         ),
     ),
 )

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 `data_retrieve` IRs.
+catalog so the existing `IRValidator` can check inline `retrieve_data` 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 data_retrieve IR validates against the catalog.
-                if call.tool == "data_retrieve":
+                # Check 8b — inline retrieve_data IR validates against the catalog.
+                if call.tool == "retrieve_data":
                     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}: data_retrieve.args.ir must be an inline QueryIR "
+                f"task {task_id}: retrieve_data.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}: data_retrieve.args.ir is not a valid QueryIR: {e}"
+                f"task {task_id}: retrieve_data.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}: data_retrieve IR failed catalog validation: {e}"
+                f"task {task_id}: retrieve_data IR failed catalog validation: {e}"
             ) from e
 
     @staticmethod

src/catalog/reader.py

@@ -45,8 +45,8 @@ 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
-    data_check's structured read + knowledge_check's unstructured read, then
-    data_retrieve's structured read). Wrapping the base reader collapses those
+    check_data's structured read + check_knowledge's unstructured read, then
+    retrieve_data'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
-   `data_retrieve` tool call's `args.ir`.
+   `retrieve_data` 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.** `data_retrieve` is the data-access entry
+- **Data access vs analytics tools.** `retrieve_data` 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 `data_retrieve` to fetch the rows, then pass its output to
+  profiling — run `retrieve_data` 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
-  `knowledge_retrieve` task against an unstructured source listed in the catalog.
+  `retrieve_knowledge` 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 `data_retrieve` runs, the connection is
+        Planner LLM call — by the time `retrieve_data` 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
-`data_retrieve` step — the wrapper layer later maps a QueryIR onto this.
+`retrieve_data` 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

@@ -8,18 +8,18 @@ the runtime/Coordinator supplies them; INV-7 keeps the agent layer
 tool-agnostic).
 
 Tools implemented here:
-- `data_check`        — structured data sources (DB + tabular). No `source_id`
+- `check_data`        — structured data sources (DB + tabular). No `source_id`
                         → list sources (id, name, type, table count); with a
                         `source_id` → that source's tables/columns (one row per
                         column, metadata only — exposes `pii_flag`, never
                         sample values).
-- `knowledge_check`   — the user's unstructured sources / documents (id, name,
+- `check_knowledge`   — the user's unstructured sources / documents (id, name,
                         type).
-- `data_retrieve`  — runs a pre-built `QueryIR` (validate -> dispatch ->
+- `retrieve_data`  — 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.
-- `knowledge_retrieve` — dense retrieval over unstructured sources, returns
+- `retrieve_knowledge` — dense retrieval over unstructured sources, returns
                         `ToolOutput(kind="documents")`.
 
 Frozen guarantee (§8.4): **never throws.** Any failure returns
@@ -51,7 +51,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(
-    {"data_check", "knowledge_check", "data_retrieve", "knowledge_retrieve"}
+    {"check_data", "check_knowledge", "retrieve_data", "retrieve_knowledge"}
 )
 
 
@@ -77,28 +77,28 @@ class DataAccessToolInvoker:
     ) -> None:
         self._user_id = user_id
         self._reader = catalog_reader
-        # data_retrieve deps — injectable so tests need no real LLM/DB. The
+        # retrieve_data 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
         )
-        # knowledge_retrieve dep — the module singleton by default, injectable
+        # retrieve_knowledge 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
 
     async def invoke(self, tool_name: str, args: dict[str, Any]) -> ToolOutput:
         try:
-            if tool_name == "data_check":
-                return await self._data_check(args)
-            if tool_name == "knowledge_check":
-                return await self._knowledge_check()
-            if tool_name == "data_retrieve":
-                return await self._data_retrieve(args)
-            if tool_name == "knowledge_retrieve":
-                return await self._knowledge_retrieve(args)
+            if tool_name == "check_data":
+                return await self._check_data(args)
+            if tool_name == "check_knowledge":
+                return await self._check_knowledge()
+            if tool_name == "retrieve_data":
+                return await self._retrieve_data(args)
+            if tool_name == "retrieve_knowledge":
+                return await self._retrieve_knowledge(args)
             return ToolOutput(
                 tool=tool_name, kind="error", error=f"unknown tool {tool_name!r}"
             )
@@ -107,7 +107,7 @@ class DataAccessToolInvoker:
                 tool=tool_name, kind="error", error=f"{type(exc).__name__}: {exc}"
             )
 
-    async def _data_check(self, args: dict[str, Any]) -> ToolOutput:
+    async def _check_data(self, args: dict[str, Any]) -> ToolOutput:
         """Inspect the user's structured data sources (DB + tabular).
 
         No `source_id` → an overview: one row per structured source (id, name,
@@ -116,7 +116,7 @@ class DataAccessToolInvoker:
 
         Pattern A note: schema is catalog metadata only — never returns row
         data or PII sample values (only the `pii_flag` boolean per column).
-        Unstructured documents are covered by `knowledge_check`.
+        Unstructured documents are covered by `check_knowledge`.
         """
         structured = await self._reader.read(self._user_id, "structured")
         source_id = args.get("source_id")
@@ -127,7 +127,7 @@ class DataAccessToolInvoker:
                 for s in structured.sources
             ]
             return ToolOutput(
-                tool="data_check",
+                tool="check_data",
                 kind="table",
                 columns=["source_id", "name", "source_type", "table_count"],
                 rows=rows,
@@ -139,7 +139,7 @@ class DataAccessToolInvoker:
         )
         if source is None:
             return ToolOutput(
-                tool="data_check",
+                tool="check_data",
                 kind="error",
                 error=f"structured source {source_id!r} not found",
             )
@@ -159,7 +159,7 @@ class DataAccessToolInvoker:
             for c in t.columns
         ]
         return ToolOutput(
-            tool="data_check",
+            tool="check_data",
             kind="table",
             columns=[
                 "table_id",
@@ -181,24 +181,24 @@ class DataAccessToolInvoker:
             },
         )
 
-    async def _knowledge_check(self) -> ToolOutput:
+    async def _check_knowledge(self) -> ToolOutput:
         """List the user's unstructured sources (documents).
 
         Documents have no column schema to drill into, so there is no
-        `source_id` mode — reading document content is `knowledge_retrieve`'s
+        `source_id` mode — reading document content is `retrieve_knowledge`'s
         job.
         """
         unstructured = await self._reader.read(self._user_id, "unstructured")
         rows = [[s.source_id, s.name, s.source_type] for s in unstructured.sources]
         return ToolOutput(
-            tool="knowledge_check",
+            tool="check_knowledge",
             kind="table",
             columns=["source_id", "name", "source_type"],
             rows=rows,
             meta={"source_count": len(unstructured.sources)},
         )
 
-    async def _data_retrieve(self, args: dict[str, Any]) -> ToolOutput:
+    async def _retrieve_data(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
@@ -211,14 +211,14 @@ class DataAccessToolInvoker:
         raw = args.get("ir")
         if raw is None:
             return ToolOutput(
-                tool="data_retrieve", kind="error", error="missing 'ir' argument"
+                tool="retrieve_data", 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="data_retrieve", kind="error", error=f"invalid IR: {exc}"
+                tool="retrieve_data", kind="error", error=f"invalid IR: {exc}"
             )
 
         catalog = await self._reader.read(self._user_id, "structured")
@@ -227,7 +227,7 @@ class DataAccessToolInvoker:
             self._validator.validate(ir, catalog)
         except IRValidationError as exc:
             return ToolOutput(
-                tool="data_retrieve",
+                tool="retrieve_data",
                 kind="error",
                 error=f"IR validation failed: {exc}",
             )
@@ -238,7 +238,7 @@ class DataAccessToolInvoker:
 
         if result.error:
             return ToolOutput(
-                tool="data_retrieve", kind="error", error=result.error
+                tool="retrieve_data", kind="error", error=result.error
             )
 
         # QueryResult.rows is list[dict]; ToolOutput.rows is list[list] ordered
@@ -250,7 +250,7 @@ class DataAccessToolInvoker:
             [_json_safe(row.get(c)) for c in result.columns] for row in result.rows
         ]
         return ToolOutput(
-            tool="data_retrieve",
+            tool="retrieve_data",
             kind="table",
             columns=result.columns,
             rows=rows,
@@ -266,7 +266,7 @@ class DataAccessToolInvoker:
             },
         )
 
-    async def _knowledge_retrieve(self, args: dict[str, Any]) -> ToolOutput:
+    async def _retrieve_knowledge(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`
@@ -274,7 +274,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 `knowledge_retrieve`
+        TODO(retrieval scoping): the Planner few-shot has no `retrieve_knowledge`
         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
@@ -284,7 +284,7 @@ class DataAccessToolInvoker:
         query = args.get("query")
         if not isinstance(query, str) or not query.strip():
             return ToolOutput(
-                tool="knowledge_retrieve",
+                tool="retrieve_knowledge",
                 kind="error",
                 error="missing 'query' argument",
             )
@@ -315,7 +315,7 @@ class DataAccessToolInvoker:
             for r in results
         ]
         return ToolOutput(
-            tool="knowledge_retrieve",
+            tool="retrieve_knowledge",
             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
-  `data_retrieve` table output, resolved to a DataFrame at execution time.
+  `retrieve_data` 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,8 +17,8 @@ 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 (data_retrieve / knowledge_retrieve / data_check /
-knowledge_check) are registered separately once their wrappers land (KM-465 #4);
+The four data-access tools (retrieve_data / retrieve_knowledge / check_data /
+check_knowledge) are registered separately once their wrappers land (KM-465 #4);
 `default_registry()` composes both slices.
 """