describe_table
Analyze spreadsheet structure to reveal column names, data types, row counts, and sample data for effective SQL query planning.
Instructions
Inspect the structure of a sheet treated as a database table.
Returns column names, inferred data types (text, integer, number, boolean, date), total row count, and sample values from the first 3 data rows. Use this before writing SQL queries to understand the available columns and their types.
When sheet is omitted, returns a list of descriptions for all sheets.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Path to the spreadsheet file | |
| sheet | No | Sheet name to describe. If omitted, describes all sheets in the workbook. | |
| header_row | No | 1-based row number containing column headers. Defaults to 1. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- The describe_table tool handler function, which inspects the structure of a sheet in a spreadsheet.
def describe_table( file: Annotated[str, Field(description="Path to the spreadsheet file")], sheet: Annotated[str | None, Field(description="Sheet name to describe. If omitted, describes all sheets in the workbook.")] = None, header_row: Annotated[int, Field(description="1-based row number containing column headers. Defaults to 1.")] = 1, ) -> list[dict] | dict: """Inspect the structure of a sheet treated as a database table. Returns column names, inferred data types (text, integer, number, boolean, date), total row count, and sample values from the first 3 data rows. Use this before writing SQL queries to understand the available columns and their types. When sheet is omitted, returns a list of descriptions for all sheets. """ wb = load_workbook(file) targets = [_resolve_sheet(wb, sheet)] if sheet else wb.worksheets results = [] for ws in targets: headers, rows = _sheet_to_records(ws, header_row) if not headers: results.append({"sheet": ws.title, "columns": [], "row_count": 0, "sample": []}) continue columns = [] for col_idx, header in enumerate(headers): col_values = [row[col_idx] for row in rows] columns.append({"name": header, "type": _infer_describe_type(col_values)}) sample = [dict(zip(headers, row)) for row in rows[:3]] results.append({ "sheet": ws.title, "columns": columns, "row_count": len(rows), "sample": sample, }) return results[0] if len(results) == 1 else results