list_something pattern generalized

tests/wf_mcp/test_server.py

@@ -193,6 +193,7 @@ def test_server_exposes_upstream_admin_and_workflow_tools() -> None:
 
             assert _structured(echo_result)["echoed"] == "hello"
             assert _structured(artifacts_result)["nodes"] == []
+            assert _structured(artifacts_result)["total"] == 0
             assert _structured(capability_result)["outcome"] == "ok"
             assert _structured(capability_result)["output"] == {"value": "hello"}
             source_ids = {
@@ -423,6 +424,7 @@ def test_server_safe_tool_names_adapts_dotted_runtime_names() -> None:
             )
 
             assert artifacts["nodes"] == []
+            assert artifacts["total"] == 0
             assert echo["echoed"] == "hello"
 
     asyncio.run(run_proxy())
@@ -444,6 +446,10 @@ def test_workflow_tools_have_human_metadata() -> None:
 
             assert list_artifacts.title == "List Workflow Artifacts"
             assert "saved workflow artifacts" in (list_artifacts.description or "")
+            assert "query" in list_artifacts.inputSchema["properties"]
+            assert "kind" in list_artifacts.inputSchema["properties"]
+            assert "cursor" in list_artifacts.inputSchema["properties"]
+            assert "limit" in list_artifacts.inputSchema["properties"]
             assert run_deployment.title == "Run Workflow Deployment"
             assert "deployment_id" in (run_deployment.description or "")
             assert "trace_range" in run_deployment.inputSchema["properties"]

tests/wf_mcp/test_workflow_surface.py

@@ -74,6 +74,8 @@ def test_workflow_surface_lists_artifact_catalog_entries() -> None:
 
     nodes = payload["nodes"]
     assert len(nodes) == 1
+    assert payload["total"] == 1
+    assert payload["next_cursor"] is None
     assert nodes[0]["name"] == "workflow.summarize_docs.v1"
     assert nodes[0]["artifact_id"] == "summarize_docs"
     assert nodes[0]["version"] == 1
@@ -82,6 +84,50 @@ def test_workflow_surface_lists_artifact_catalog_entries() -> None:
     assert "plan" not in nodes[0]
 
 
+def test_workflow_surface_pages_and_filters_artifact_catalog_entries() -> None:
+    artifact_store = FileWorkflowArtifactStore(
+        local_temp_root() / "surface_artifact_pages"
+    )
+    artifact_store.save_artifact(_artifact())
+    artifact_store.save_artifact(
+        _artifact().model_copy(
+            update={
+                "id": "echo_wrapper",
+                "version": 2,
+                "kind": "wrapper",
+                "title": "Echo Wrapper",
+                "description": "Reusable echo wrapper.",
+            }
+        )
+    )
+    artifact_store.save_artifact(
+        _artifact().model_copy(
+            update={
+                "id": "browser_click",
+                "title": "Browser Click",
+                "description": "Open a page and wait for a click.",
+            }
+        )
+    )
+    handlers = _handlers(artifact_store)
+
+    first_page = asyncio.run(handlers.list_artifacts(limit=2))
+    second_page = asyncio.run(
+        handlers.list_artifacts(cursor=first_page["next_cursor"], limit=2)
+    )
+    wrappers = asyncio.run(handlers.list_artifacts(kind="wrapper", query="echo"))
+
+    assert first_page["total"] == 3
+    assert first_page["next_cursor"] == "2"
+    assert len(first_page["nodes"]) == 2
+    assert len(second_page["nodes"]) == 1
+    assert second_page["next_cursor"] is None
+    assert wrappers["total"] == 1
+    assert wrappers["nodes"][0]["artifact_id"] == "echo_wrapper"
+    assert wrappers["nodes"][0]["kind"] == "wrapper"
+    assert "plan" not in wrappers["nodes"][0]
+
+
 def test_workflow_surface_lists_planner_visible_capabilities() -> None:
     handlers = _handlers(FileWorkflowArtifactStore(local_temp_root() / "surface_caps"))