[NOTICKET] refactor(tools): single source of truth for data-access tool names + clarify input_schema is presence-only

R11 (TAB slice): the data-access tool-name set was duplicated between invoker.py and planner/registry.py, synced only by a keep-in-lockstep comment. A 5th/renamed tool added in one place but not the other would silently mis-route (registry knows it, CompositeToolInvoker rejects it). Define canonical DATA_ACCESS_TOOLS once in tools/data_access.py; invoker.py imports it. (planner/registry.py + _PLACEHOLDER_RE dedup are the agent-side remainder.)

T1: ToolSpec.input_schema comment said "validates ToolCall.args" but TaskRunner._validate_args is presence-only; properties types are documentation, not enforced. Clarified so nobody assumes type-safety.

Doc/comment + a constant move; no behavior change. 41 tool tests pass, ruff clean.

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

src/tools/contracts.py

@@ -36,7 +36,13 @@ from pydantic import BaseModel, Field
 class ToolSpec(BaseModel):
     name: str
     category: str  # analytics.query | .aggregation | .timeseries | ...
-    input_schema: dict[str, Any]  # validates ToolCall.args
+    # JSON-schema-ish dict: {"required": [...], "properties": {arg: {"type": ...}}}.
+    # VALIDATION CONTRACT — presence only: TaskRunner._validate_args enforces just
+    # `required` (each must resolve to a non-None arg). The `properties` types are
+    # DOCUMENTATION for the planner prompt, NOT checked at runtime — a wrong-typed
+    # arg passes validation and only surfaces (if at all) inside the compute fn.
+    # Do not assume type-safety here.
+    input_schema: dict[str, Any]
     output_kind: str  # the ToolOutput.kind it returns
     description: str  # prompt-style: what it does, edge cases, what NOT to use it for
     phase: Literal["P0", "P1", "P2"] = "P0"

src/tools/data_access.py

@@ -40,6 +40,16 @@ from src.tools.contracts import ToolOutput
 
 DispatcherFactory = Callable[[Catalog], ExecutorDispatcher]
 
+# Canonical set of data-access tool names — the single source of truth for which
+# tools this invoker serves. `CompositeToolInvoker` imports it to route by name;
+# the planner registry should derive its data-access spec names from it (agent ->
+# tool is the correct dependency direction). Defining it once here means
+# 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"}
+)
+
 
 class Retriever(Protocol):
     """Minimal interface this invoker needs from the retrieval layer."""

src/tools/invoker.py

@@ -37,7 +37,7 @@ from src.tools.analytics import (
     temporal,
 )
 from src.tools.contracts import ToolOutput
-from src.tools.data_access import DataAccessToolInvoker
+from src.tools.data_access import DATA_ACCESS_TOOLS, DataAccessToolInvoker
 
 # tool name -> (compute callable, ToolOutput.kind it produces). Kept in lockstep
 # with src/tools/registry.py output_kind values.
@@ -81,14 +81,6 @@ class AnalyticsToolInvoker:
         return ToolOutput(tool=tool_name, kind=kind, value=result)
 
 
-# Tool names served by the stateful data-access invoker (catalog + query +
-# retrieval). Everything else is an analyze_* tool and goes to the analytics
-# invoker. Kept in lockstep with _DATA_ACCESS_TOOLS in planner/registry.py.
-_DATA_ACCESS_TOOLS: frozenset[str] = frozenset(
-    {"query_structured", "retrieve_documents", "list_sources", "describe_source"}
-)
-
-
 class CompositeToolInvoker:
     """One `invoke()` for the whole tool surface (KM-465 #4).
 
@@ -116,7 +108,7 @@ class CompositeToolInvoker:
         self._analytics = analytics or AnalyticsToolInvoker()
 
     async def invoke(self, tool_name: str, args: dict[str, Any]) -> ToolOutput:
-        if tool_name in _DATA_ACCESS_TOOLS:
+        if tool_name in DATA_ACCESS_TOOLS:
             return await self._data_access.invoke(tool_name, args)
         return await self._analytics.invoke(tool_name, args)