M4

Instructions

Implementation Reference

• src/m4/core/tools/tabular.py:94-162 (handler)

  Core handler: GetTableInfoTool class implements the tool logic, invoking backend methods to retrieve table schema and optional sample data.

  class GetTableInfoTool:
      """Tool for inspecting table structure and sample data.
  
      Shows column names, data types, and optionally sample rows for a
      specified table.
      """
  
      name = "get_table_info"
      description = "Get detailed information about a specific table"
      input_model = GetTableInfoInput
      output_model = ToolOutput
  
      required_modalities: frozenset[Modality] = frozenset({Modality.TABULAR})
      supported_datasets: frozenset[str] | None = None
  
      def invoke(
          self, dataset: DatasetDefinition, params: GetTableInfoInput
      ) -> ToolOutput:
          """Get table structure and sample data using the backend."""
          backend = get_backend()
          backend_info = backend.get_backend_info(dataset)
  
          # Validate table name
          if not validate_table_name(params.table_name):
              return ToolOutput(
                  result=f"{backend_info}\nError: Invalid table name '{params.table_name}'"
              )
  
          try:
              # Get table schema
              schema_result = backend.get_table_info(params.table_name, dataset)
              if not schema_result.success:
                  return ToolOutput(result=f"{backend_info}\n{schema_result.error}")
  
              result_parts = [
                  backend_info,
                  f"**Table:** {params.table_name}",
                  "",
                  "**Column Information:**",
                  schema_result.data,
              ]
  
              # Get sample data if requested
              if params.show_sample:
                  sample_result = backend.get_sample_data(
                      params.table_name, dataset, limit=3
                  )
                  if sample_result.success:
                      result_parts.extend(
                          [
                              "",
                              "**Sample Data (first 3 rows):**",
                              sample_result.data,
                          ]
                      )
  
              return ToolOutput(result="\n".join(result_parts))
          except Exception as e:
              return ToolOutput(
                  result=f"{backend_info}\nError examining table '{params.table_name}': {e}"
              )
  
      def is_compatible(self, dataset: DatasetDefinition) -> bool:
          """Check compatibility."""
          if self.supported_datasets and dataset.name not in self.supported_datasets:
              return False
          if not self.required_modalities.issubset(dataset.modalities):
              return False
          return True

• src/m4/core/tools/tabular.py:32-39 (schema)

  Input schema: Defines parameters table_name (str) and show_sample (bool) for the tool.

  @dataclass
  class GetTableInfoInput(ToolInput):
      """Input for get_table_info tool."""
  
      table_name: str
      show_sample: bool = True

• src/m4/core/tools/__init__.py:65-65 (registration)

  Internal ToolRegistry registration of GetTableInfoTool instance during init_tools().

  ToolRegistry.register(GetTableInfoTool())

• src/m4/mcp_server.py:126-151 (handler)

  MCP protocol handler: Thin wrapper that registers the tool via @mcp.tool() and delegates execution to the internal ToolRegistry tool.

  @mcp.tool()
  @require_oauth2
  def get_table_info(table_name: str, show_sample: bool = True) -> str:
      """🔍 Explore a specific table's structure and see sample data.
  
      **When to use:** After identifying relevant tables from get_database_schema().
  
      Args:
          table_name: Exact table name (case-sensitive).
          show_sample: Whether to include sample rows (default: True).
  
      Returns:
          Table structure with column names, types, and sample data.
      """
      dataset = DatasetRegistry.get_active()
  
      # Proactive capability check
      result = _tool_selector.check_compatibility("get_table_info", dataset)
      if not result.compatible:
          return result.error_message
  
      tool = ToolRegistry.get("get_table_info")
      return tool.invoke(
          dataset, GetTableInfoInput(table_name=table_name, show_sample=show_sample)
      ).result

• src/m4/mcp_server.py:52-52 (registration)

  MCP tool name listed in _MCP_TOOL_NAMES set for filtering and snapshots.

  "get_table_info",