refactor(tools)!: move /v1/tools route to /v1/admin/tools (ogx-ai#5787)

# What does this PR do?

Moves the `GET /v1/tools` endpoint to `GET /v1/admin/tools`, following
the same pattern as ogx-ai#5659 (connectors → admin). Tools are
admin-controlled resources configured at the distribution level, not
user-scoped — users don't register or unregister tool groups. The
rationale is identical to the connectors move.

**Pattern followed from ogx-ai#5659:**
- `Admin` protocol gains `list_tools` method
- `AdminImpl` delegates to the `ToolGroupsRoutingTable` via `self.deps`
- Tools `fastapi_routes.py` deleted; route served by the admin router
- Admin router restructured with sub-routers to support both `/v1alpha`
(existing admin endpoints) and `/v1` (tools) prefixes

**BREAKING CHANGE:** `GET /v1/tools` is removed. Use `GET
/v1/admin/tools` instead.

## Test Plan

1. Pre-commit checks pass (all except `api-conformance` which is
expected for breaking changes — the `refactor!:` commit message signals
intentional breakage)
2. Unit tests pass: `uv run pytest tests/unit/core/ --tb=short -q -k
"tool or route or admin"` — 77 passed
3. mypy passes with no errors
4. OpenAPI specs regenerated and validated

---------

Signed-off-by: Sébastien Han <seb@redhat.com>
Signed-off-by: Charlie Doern <cdoern@redhat.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Charlie Doern <cdoern@redhat.com>

Author: 3 people

client-sdks/stainless/openapi.yml

@@ -2087,7 +2087,7 @@ paths:
           title: Identifier
         description: The identifier of the shield to unregister.
       deprecated: true
-  /v1/tools:
+  /v1/admin/tools:
     get:
       responses:
         '200':
@@ -2112,7 +2112,7 @@ paths:
       - Tools
       summary: List tools with optional tool group filter.
       description: List tools with optional tool group filter.
-      operationId: list_tools_v1_tools_get
+      operationId: list_tools_v1_admin_tools_get
       parameters:
       - name: toolgroup_id
         in: query

docs/static/ogx-spec.yaml

@@ -1926,7 +1926,7 @@ paths:
           input_items = client.responses.input_items.list("resp_abc123")
           for item in input_items:
               print(item)
-  /v1/tools:
+  /v1/admin/tools:
     get:
       responses:
         '200':
@@ -1951,7 +1951,7 @@ paths:
       - Tools
       summary: List tools with optional tool group filter.
       description: List tools with optional tool group filter.
-      operationId: list_tools_v1_tools_get
+      operationId: list_tools_v1_admin_tools_get
       parameters:
       - name: toolgroup_id
         in: query

docs/static/stainless-ogx-spec.yaml

@@ -2087,7 +2087,7 @@ paths:
           title: Identifier
         description: The identifier of the shield to unregister.
       deprecated: true
-  /v1/tools:
+  /v1/admin/tools:
     get:
       responses:
         '200':
@@ -2112,7 +2112,7 @@ paths:
       - Tools
       summary: List tools with optional tool group filter.
       description: List tools with optional tool group filter.
-      operationId: list_tools_v1_tools_get
+      operationId: list_tools_v1_admin_tools_get
       parameters:
       - name: toolgroup_id
         in: query

scripts/openapi_generator/_legacy_order.py

@@ -47,7 +47,7 @@
     "/v1/tool-runtime/list-tools",
     "/v1/toolgroups",
     "/v1/toolgroups/{toolgroup_id}",
-    "/v1/tools",
+    "/v1/admin/tools",
     "/v1/tools/{tool_name}",
     "/v1/vector-io/insert",
     "/v1/vector-io/query",

src/ogx/core/admin.py

@@ -42,6 +42,8 @@
     ListToolsResponse,
 )
 from ogx_api.tools import ToolDef
+from ogx_api.tools.api import ToolGroups
+from ogx_api.tools.models import ListToolDefsResponse, ListToolsRequest
 
 logger = get_logger(name=__name__, category="core")
 
@@ -249,3 +251,10 @@ async def list_connector_tools(
 
     async def get_connector_tool(self, request: GetConnectorToolRequest, authorization: str | None = None) -> ToolDef:
         return await self._connectors.get_connector_tool(request, authorization=authorization)
+
+    @property
+    def _tool_groups(self) -> ToolGroups:
+        return cast(ToolGroups, self.deps[Api.tool_groups.value])
+
+    async def list_tools(self, request: ListToolsRequest) -> ListToolDefsResponse:
+        return await self._tool_groups.list_tools(request)

src/ogx_api/admin/api.py

@@ -7,6 +7,7 @@
 from typing import Protocol, runtime_checkable
 
 from ogx_api.connectors.api import Connectors
+from ogx_api.tools.models import ListToolDefsResponse, ListToolsRequest
 
 from .models import (
     HealthInfo,
@@ -72,3 +73,13 @@ async def version(self) -> VersionInfo:
         :returns: Version information containing the service version number.
         """
         ...
+
+    async def list_tools(self, request: ListToolsRequest) -> ListToolDefsResponse:
+        """List tools.
+
+        List tools with optional tool group filter.
+
+        :param request: Request containing optional filter parameters
+        :returns: A ListToolDefsResponse containing available tool definitions.
+        """
+        ...

src/ogx_api/admin/fastapi_routes.py

@@ -25,7 +25,8 @@
 )
 from ogx_api.router_utils import create_path_dependency, create_query_dependency, standard_responses
 from ogx_api.tools import ToolDef
-from ogx_api.version import OGX_API_V1ALPHA
+from ogx_api.tools.models import ListToolDefsResponse, ListToolsRequest
+from ogx_api.version import OGX_API_V1, OGX_API_V1ALPHA
 
 from .api import Admin
 from .models import (
@@ -41,6 +42,7 @@
 # Automatically generate dependency functions from Pydantic models
 get_inspect_provider_request = create_path_dependency(InspectProviderRequest)
 get_list_routes_request = create_query_dependency(ListRoutesRequest)
+get_list_tools_request = create_query_dependency(ListToolsRequest)
 get_connector_request = create_path_dependency(GetConnectorRequest)
 list_connector_tools_request = create_path_dependency(ListConnectorToolsRequest)
 
@@ -55,12 +57,15 @@ def create_router(impl: Admin) -> APIRouter:
         APIRouter configured for the Admin API
     """
     router = APIRouter(
+        responses=standard_responses,
+    )
+
+    v1alpha_router = APIRouter(
         prefix=f"/{OGX_API_V1ALPHA}",
         tags=["Admin"],
-        responses=standard_responses,
     )
 
-    @router.get(
+    @v1alpha_router.get(
         "/admin/providers",
         response_model=ListProvidersResponse,
         summary="List all available providers",
@@ -72,7 +77,7 @@ def create_router(impl: Admin) -> APIRouter:
     async def list_providers() -> ListProvidersResponse:
         return await impl.list_providers()
 
-    @router.get(
+    @v1alpha_router.get(
         "/admin/providers/{provider_id}",
         response_model=ProviderInfo,
         summary="Get provider details",
@@ -87,7 +92,7 @@ async def inspect_provider(
     ) -> ProviderInfo:
         return await impl.inspect_provider(request)
 
-    @router.get(
+    @v1alpha_router.get(
         "/admin/inspect/routes",
         response_model=ListRoutesResponse,
         summary="List all available API routes",
@@ -101,7 +106,7 @@ async def list_routes(
     ) -> ListRoutesResponse:
         return await impl.list_routes(request)
 
-    @router.get(
+    @v1alpha_router.get(
         "/admin/health",
         response_model=HealthInfo,
         summary="Get service health status",
@@ -113,7 +118,7 @@ async def list_routes(
     async def health() -> HealthInfo:
         return await impl.health()
 
-    @router.get(
+    @v1alpha_router.get(
         "/admin/version",
         response_model=VersionInfo,
         summary="Get service version",
@@ -125,7 +130,7 @@ async def health() -> HealthInfo:
     async def version() -> VersionInfo:
         return await impl.version()
 
-    @router.get(
+    @v1alpha_router.get(
         "/admin/connectors",
         response_model=ListConnectorsResponse,
         summary="List all connectors.",
@@ -134,7 +139,7 @@ async def version() -> VersionInfo:
     async def list_connectors() -> ListConnectorsResponse:
         return await impl.list_connectors()
 
-    @router.get(
+    @v1alpha_router.get(
         "/admin/connectors/{connector_id}/tools/{tool_name}",
         response_model=ToolDef,
         summary="Get a tool by name from a connector.",
@@ -148,7 +153,7 @@ async def get_connector_tool(
         request = GetConnectorToolRequest(connector_id=connector_id, tool_name=tool_name)
         return await impl.get_connector_tool(request, authorization=authorization)
 
-    @router.get(
+    @v1alpha_router.get(
         "/admin/connectors/{connector_id}/tools",
         response_model=ListToolsResponse,
         summary="List tools from a connector.",
@@ -160,7 +165,7 @@ async def list_connector_tools(
     ) -> ListToolsResponse:
         return await impl.list_connector_tools(request, authorization=authorization)
 
-    @router.get(
+    @v1alpha_router.get(
         "/admin/connectors/{connector_id}",
         response_model=Connector,
         summary="Get a connector by its ID.",
@@ -172,4 +177,26 @@ async def get_connector(
     ) -> Connector:
         return await impl.get_connector(request, authorization=authorization)
 
+    v1_router = APIRouter(
+        prefix=f"/{OGX_API_V1}",
+        tags=["Tools"],
+    )
+
+    @v1_router.get(
+        "/admin/tools",
+        response_model=ListToolDefsResponse,
+        summary="List tools with optional tool group filter.",
+        description="List tools with optional tool group filter.",
+        responses={
+            200: {"description": "A ListToolDefsResponse."},
+        },
+    )
+    async def list_tools(
+        request: Annotated[ListToolsRequest, Depends(get_list_tools_request)],
+    ) -> ListToolDefsResponse:
+        return await impl.list_tools(request)
+
+    router.include_router(v1alpha_router)
+    router.include_router(v1_router)
+
     return router

src/ogx_api/tools/__init__.py

@@ -8,12 +8,8 @@
 
 This module contains the ToolGroups and ToolRuntime protocol definitions.
 Pydantic models are defined in ogx_api.tools.models.
-The FastAPI router is defined in ogx_api.tools.fastapi_routes.
 """
 
-# Import fastapi_routes for router factory access
-from . import fastapi_routes
-
 # Import protocols for re-export
 from .api import ToolGroups, ToolRuntime
 
@@ -42,5 +38,4 @@
     "ToolInvocationResult",
     "ToolRuntime",
     "ToolStore",
-    "fastapi_routes",
 ]