address additional comments, add some shortcuts, better documentation, additional testing, better naming

Author: bcallender

docs/topics/fenic-mcp.md

@@ -136,7 +136,7 @@ session.catalog.drop_tool("users_by_name_regex", ignore_if_not_exists=True)
 
 ### Step 2a: Auto-generate system tools from catalog tables
 
-You can generate a suite of reusable data tools (Schema, Profile, Read, Search Summary, Search Content, Analyze) directly from catalog tables and their descriptions. This is helpful for quickly exposing exploratory and read/query capabilities to MCP.
+You can generate a suite of reusable data tools (Schema, Profile, Read, Search Summary, Search Content, Analyze) directly from catalog tables and their descriptions. This is helpful for quickly exposing exploratory and read/query capabilities to MCP. Available tools include: - Schema: list columns/types for any or all tables - Profile: column statistics (counts, basic numeric analysis [min, max, mean, etc.], contextual information for text columns [average_length, etc.]) - Read: read a selection of rows from a single table. These rows can be paged over, filtered and can use column projections. - Search Summary: regex search across all text columns in all tables -- returns back dataframe names with result counts. - Search Content: regex search across a single table, specifying one or more text columns to search across -- returns back rows corresponding to the query. - Analyze: Write raw SQL to perform complex analysis on one or more tables.
 
 Requirements:
 
@@ -147,15 +147,15 @@ Example:
 ```python
 from fenic import Session
 from fenic.api.mcp.server import create_mcp_server
-from fenic.api.mcp.tools import ToolGenerationConfig
+from fenic.api.mcp.tools import SystemToolConfig
 
 session = Session.get_or_create(...)
 server = create_mcp_server(
     session,
     server_name="Fenic MCP",
-    system_tools=ToolGenerationConfig(
+    system_tools=SystemToolConfig(
         table_names=["orders", "users"],
-        tool_group_name="Dataset Exploration",
+        tool_namespace="Dataset Exploration",
         max_result_rows=200,
     ),
 )

src/fenic/__init__.py

@@ -23,7 +23,7 @@
     SemanticExtensions,
     Session,
     SessionConfig,
-    ToolGenerationConfig,
+    SystemToolConfig,
     array,
     array_agg,
     array_contains,
@@ -239,7 +239,7 @@
     "BoundToolParam",
     "UserDefinedTool",
     "SystemTool",
-    "ToolGenerationConfig",
+    "SystemToolConfig",
     "create_mcp_server",
     "run_mcp_server_asgi",
     "run_mcp_server_async",

src/fenic/api/__init__.py

@@ -44,7 +44,7 @@
 from fenic.api.io import DataFrameReader, DataFrameWriter
 from fenic.api.lineage import Lineage
 from fenic.api.mcp import (
-    ToolGenerationConfig,
+    SystemToolConfig,
     create_mcp_server,
     run_mcp_server_asgi,
     run_mcp_server_async,
@@ -137,5 +137,5 @@
     "run_mcp_server_sync",
     "run_mcp_server_async",
     "run_mcp_server_asgi",
-    "ToolGenerationConfig",
+    "SystemToolConfig",
 ]

src/fenic/api/mcp/__init__.py

@@ -1,7 +1,7 @@
 """MCP Tool Creation/Server Management API."""
 
 from fenic.api.mcp.server import (
-    ToolGenerationConfig,
+    SystemToolConfig,
     create_mcp_server,
     run_mcp_server_asgi,
     run_mcp_server_async,
@@ -13,5 +13,5 @@
     "run_mcp_server_sync",
     "run_mcp_server_async",
     "run_mcp_server_asgi",
-    "ToolGenerationConfig",
+    "SystemToolConfig",
 ]

src/fenic/api/mcp/_tool_generation_utils.py

@@ -8,25 +8,23 @@
 import polars as pl
 from typing_extensions import Annotated
 
-from fenic import (
+from fenic.api import col
+from fenic.api.dataframe import DataFrame
+from fenic.api.functions import avg, stddev
+from fenic.api.functions import max as max_
+from fenic.api.functions import min as min_
+from fenic.api.session import Session
+from fenic.core._logical_plan import LogicalPlan
+from fenic.core._logical_plan.plans import InMemorySource
+from fenic.core.error import ConfigurationError, ValidationError
+from fenic.core.mcp.types import SystemTool
+from fenic.core.types.datatypes import (
     BooleanType,
-    DataFrame,
     DoubleType,
     FloatType,
     IntegerType,
-    Session,
     StringType,
-    SystemTool,
-    avg,
-    col,
-    stddev,
 )
-from fenic import max as max_
-from fenic import min as min_
-from fenic.core._logical_plan import LogicalPlan
-from fenic.core._logical_plan.plans import InMemorySource
-from fenic.core._utils.schema import convert_custom_dtype_to_polars
-from fenic.core.error import ConfigurationError, ValidationError
 
 PROFILE_MAX_SAMPLE_SIZE = 10_000
 
@@ -44,11 +42,11 @@ class DatasetSpec:
     description: str
     df: DataFrame
 
-def auto_generate_system_tools(
+def _auto_generate_system_tools(
     datasets: List[DatasetSpec],
     session: Session,
     *,
-    tool_group_name: str,
+    tool_namespace: Optional[str],
     max_result_limit: int = 100,
 ) -> List[SystemTool]:
     """Generate core tools spanning all datasets: Schema, Profile, Analyze.
@@ -67,7 +65,7 @@ def auto_generate_system_tools(
     schema_tool = _auto_generate_schema_tool(
         datasets,
         session,
-        tool_name=f"{tool_group_name} - Schema",
+        tool_name=f"{tool_namespace} - Schema" if tool_namespace else "Schema",
         tool_description="\n\n".join([
             "Show the schema (column names and types) for any or all of the datasets listed below. This call should be the first step in exploring the available datasets.",
             group_desc,
@@ -77,7 +75,7 @@ def auto_generate_system_tools(
     profile_tool = _auto_generate_profile_tool(
         datasets,
         session,
-        tool_name=f"{tool_group_name} - Profile",
+        tool_name=f"{tool_namespace} - Profile" if tool_namespace else "Profile",
         tool_description="\n".join([
             "Return dataset data profile: row_count and per-column stats for any or all of the datasets listed below.",
             "This call should be used as a follow up after calling the `Schema` tool."
@@ -91,8 +89,8 @@ def auto_generate_system_tools(
     read_tool = _auto_generate_read_tool(
         datasets,
         session,
-        tool_name=f"{tool_group_name} - Read",
-        tool_description="\n\n".join([
+        tool_name=f"{tool_namespace} - Read" if tool_namespace else "Read",
+        tool_description="\n".join([
             "Read rows from a single dataset. Use to sample data, or to execute simple queries over the data that do not require filtering or grouping.",
             "Use `include_columns` and `exclude_columns` to filter columns by name -- this is important to conserve token usage. Use the `Profile` tool to understand the columns and their sizes.",
             "Available datasets:",
@@ -104,8 +102,8 @@ def auto_generate_system_tools(
     search_summary_tool = _auto_generate_search_summary_tool(
         datasets,
         session,
-        tool_name=f"{tool_group_name} - Search Summary",
-        tool_description="\n\n".join([
+        tool_name=f"{tool_namespace} - Search Summary" if tool_namespace else "Search Summary",
+        tool_description="\n".join([
             "Perform a substring/regex search across all datasets and return a summary of the number of matches per dataset.",
             "Available datasets:",
             group_desc,
@@ -114,8 +112,8 @@ def auto_generate_system_tools(
     search_content_tool = _auto_generate_search_content_tool(
         datasets,
         session,
-        tool_name=f"{tool_group_name} - Search Content",
-        tool_description="\n\n".join([
+        tool_name=f"{tool_namespace} - Search Content" if tool_namespace else "Search Content",
+        tool_description="\n".join([
             "Return matching rows from a single dataset using substring/regex across string columns.",
             "Available datasets:",
             group_desc,
@@ -126,8 +124,8 @@ def auto_generate_system_tools(
     analyze_tool = _auto_generate_sql_tool(
         datasets,
         session,
-        tool_name=f"{tool_group_name} - Analyze",
-        tool_description="\n\n".join([
+        tool_name=f"{tool_namespace} - Analyze" if tool_namespace else "Analyze",
+        tool_description="\n".join([
             "Execute Read-Only (SELECT) SQL over the provided datasets using fenic's SQL support.",
             "DDL/DML and multiple top-level queries are not allowed.",
             "For text search, prefer regular expressions (REGEXP_MATCHES()/REGEXP_EXTRACT()).",
@@ -142,14 +140,11 @@ def auto_generate_system_tools(
     return [schema_tool, profile_tool, read_tool, search_summary_tool, search_content_tool, analyze_tool]
 
 
-def build_datasets_from_tables(table_names: List[str], session: Session) -> List[DatasetSpec]:
+def _build_datasets_from_tables(table_names: List[str], session: Session) -> List[DatasetSpec]:
     """Resolve catalog table names into DatasetSpec list with validated descriptions.
 
     Raises ConfigurationError if any table is missing or lacks a non-empty description.
     """
-    if len(table_names) == 0:
-        raise ConfigurationError("No tables provided for tool generation.")
-
     missing_desc: List[str] = []
     missing_tables: List[str] = []
     specs: List[DatasetSpec] = []
@@ -398,8 +393,7 @@ async def schema_func(
 
         for name, d in selected.items():
             # Build a single-row DataFrame with a common list<struct{column,type}> schema column
-            schema_entries = [{"column": f.name, "type": str(convert_custom_dtype_to_polars(f.data_type))} for f in
-                              d.schema.column_fields]
+            schema_entries = [{"column": f.name, "type": str(f.data_type)} for f in d.schema.column_fields]
             dataset_names.append(name)
             dataset_schemas.append(schema_entries)
 
@@ -768,3 +762,27 @@ async def _compute_profile_rows(
                     stats.string_example_values = sampled
         rows_list.append(stats)
     return rows_list
+
+
+def auto_generate_system_tools_from_tables(
+    table_names: Optional[List[str]],
+    session: Session,
+    *,
+    tool_namespace: Optional[str],
+    max_result_limit: int = 100,
+) -> List[SystemTool]:
+    """Generate Schema/Profile/Read/Search [Content/Summary]/Analyze tools from catalog tables.
+
+    Validates that each table exists and has a non-empty description in catalog metadata.
+    """
+    if table_names is None:
+        table_names = session.catalog.list_tables()
+        if not table_names:
+            raise ConfigurationError("No tables provided for tool generation and no existing tables found in the catalog.")
+    datasets = _build_datasets_from_tables(table_names, session)
+    return _auto_generate_system_tools(
+        datasets,
+        session,
+        tool_namespace=tool_namespace,
+        max_result_limit=max_result_limit,
+    )

src/fenic/api/mcp/server.py

@@ -6,9 +6,9 @@
 """
 from typing import List, Optional
 
+from fenic.api.mcp._tool_generation_utils import auto_generate_system_tools_from_tables
 from fenic.api.mcp.tools import (
-    ToolGenerationConfig,
-    auto_generate_system_tools_from_tables,
+    SystemToolConfig,
 )
 from fenic.api.session.session import Session
 from fenic.core.error import ConfigurationError
@@ -21,7 +21,7 @@ def create_mcp_server(
     server_name: str,
     *,
     user_defined_tools: Optional[List[UserDefinedTool]] = None,
-    system_tools: Optional[ToolGenerationConfig] = None,
+    system_tools: Optional[SystemToolConfig] = None,
     concurrency_limit: int = 8,
 ) -> FenicMCPServer:
     """Create an MCP server from datasets and tools.
@@ -37,11 +37,13 @@ def create_mcp_server(
     generated_system_tools = []
     user_defined_tools = user_defined_tools or []
     if system_tools:
-        generated_system_tools.extend(auto_generate_system_tools_from_tables(
-            system_tools.table_names,
-            session,
-            tool_group_name=system_tools.tool_group_name,
-            max_result_limit=system_tools.max_result_rows)
+        generated_system_tools.extend(
+            auto_generate_system_tools_from_tables(
+                system_tools.table_names,
+                session,
+                tool_namespace=system_tools.tool_namespace,
+                max_result_limit=system_tools.max_result_rows
+            )
         )
     if not (user_defined_tools or system_tools):
         raise ConfigurationError("No tools provided. Either provide tools or set generate_automated_tools=True and provide datasets.")

src/fenic/api/mcp/tools.py

@@ -14,46 +14,67 @@
 from dataclasses import dataclass
 from typing import (
     List,
+    Optional,
 )
 
-from fenic.api.mcp._tool_generation_utils import (
-    auto_generate_system_tools,
-    build_datasets_from_tables,
-)
-from fenic.api.session.session import Session
-from fenic.core.mcp.types import SystemTool
-
 
 @dataclass
-class ToolGenerationConfig:
-    """Configuration for automated tool generation.
+class SystemToolConfig:
+    """Configuration for canonical system tools.
 
-    Attributes:
-        table_names: List of table names.
-        tool_group_name: Name of the tool group.
-        max_result_rows: Maximum number of rows to be returned from Read/Analyze tools.
-    """
+    fenic can automatically generate a set of canonical tools for operating on one or more fenic tables.
 
-    table_names: List[str]
-    tool_group_name: str
-    max_result_rows: int = 100
+    - Schema: list columns/types for any or all tables
+    - Profile: column statistics (counts, basic numeric analysis [min, max, mean, etc.], contextual information for text columns [average_length, etc.])
+    - Read: read a selection of rows from a single table. These rows can be paged over, filtered and can use column projections.
+    - Search Summary: regex search across all text columns in all tables -- returns back dataframe names with result counts.
+    - Search Content: regex search across a single table, specifying one or more text columns to search across -- returns back rows corresponding to the query.
+    - Analyze: Write raw SQL to perform complex analysis on one or more tables.
 
+    Attributes:
+        table_names: List of the fenic table names the tools should be able to access. If not provided, the generated tools will be able to access all tables in the catalog.
+        tool_namespace: If provided, will prefix the names of the generated tools with this namespace value.
+            For example, by default the generated tools will be named `read`, `profile`, etc. With multiple fenic
+            MCP servers, these tool names will clash, which can be confusing. In order to disambiguate, the `tool_namespace`
+            is prefixed to the tool name (in snake case), so a `tool_namespace` of `fenic` would create the tools `fenic_read`,
+            `fenic_profile`, etc.
+        max_result_rows: Maximum number of rows to be returned from Read/Analyze tools.
 
-def auto_generate_system_tools_from_tables(
-    table_names: List[str],
-    session: Session,
-    *,
-    tool_group_name: str,
-    max_result_limit: int = 100,
-) -> List[SystemTool]:
-    """Generate Schema/Profile/Read/Search/Analyze tools from catalog tables.
+    Example:
+    ```python
+        from fenic import SystemToolConfig
+        from fenic.api.mcp.tools import SystemToolConfig
+        from fenic.api.mcp.server import create_mcp_server
+        from fenic.api.session.session import Session
+        session = Session.get_or_create(...)
+        df = session.create_dataframe({
+            "c1": [1, 2, 3],
+            "c2": [4, 5, 6]
+        })
+        df.write.save_as_table("table1", mode="overwrite")
+        session.catalog.set_table_description("table1", "Table 1 Description")
+        server = create_mcp_server(session, "Test Server", system_tools=SystemToolConfig(
+            table_names=["table1"],
+            tool_namespace="Auto",
+            max_result_rows=100
+        ))
+    ```
 
-    Validates that each table exists and has a non-empty description in catalog metadata.
+    Example: Allow generated tools to access all tables in the catalog. Equivalent to passing `table_names=session.catalog.list_tables()`
+    ```python
+        from fenic import SystemToolConfig
+        from fenic.api.mcp.tools import SystemToolConfig
+        from fenic.api.mcp.server import create_mcp_server
+        from fenic.api.session.session import Session
+        session = Session.get_or_create(...)
+        # Assuming you already have one or more tables saved to the catalog, with descriptions.
+        server = create_mcp_server(session, "Test Server", system_tools=SystemToolConfig(
+            tool_namespace="Auto",
+            max_result_rows=100
+        ))
+    ```
     """
-    datasets = build_datasets_from_tables(table_names, session)
-    return auto_generate_system_tools(
-        datasets,
-        session,
-        tool_group_name=tool_group_name,
-        max_result_limit=max_result_limit,
-    )
+
+    table_names: Optional[List[str]] = None
+    tool_namespace: Optional[str] = None
+    max_result_rows: int = 100