get_grid_details
Retrieve full metadata for a grid, including column definitions, settings, and data sources. Use this to inspect a grid's schema before running it.
Instructions
Get full metadata for a specific Grid, including all column definitions, grid settings, and attached data sources.
Use this to inspect a grid's schema before running it — especially to understand the grid's input labels and output column UUIDs needed for the run_grid tool.
Args: grid_id: UUID of the grid. Found in the grid URL at app.bitscale.ai/grid/{gridId}, or from list_grids results.
Returns: grid id, name, description, row_count, created_at, updated_at, settings (auto_run, auto_dedupe, visibility, dedupe_column_id), columns (all columns including text, enrichment, formula, merge types with their id/key and name), and sources (data sources with schedule info).
NOTE on columns vs run_grid inputs:
The column 'id' values here are UUIDs — use these for the 'output_columns' parameter of run_grid to filter which outputs you want.
The 'inputs' parameter of run_grid uses human-readable LABELS (e.g. "company_name", "website"), NOT column UUIDs. These labels are derived from the API data source columns configured on the grid. You can find the exact input labels in the BitScale app under the grid's Data Source → BitScale API panel, or by inspecting the source column names.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| grid_id | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- main.py:124-156 (handler)The get_grid_details tool handler function. It takes a grid_id (UUID string), validates it's not empty, performs a GET request to /grids/{grid_id}, and returns the full grid metadata as formatted JSON. This includes column definitions, grid settings, and attached data sources.
def get_grid_details(grid_id: str) -> str: """ Get full metadata for a specific Grid, including all column definitions, grid settings, and attached data sources. Use this to inspect a grid's schema before running it — especially to understand the grid's input labels and output column UUIDs needed for the run_grid tool. Args: grid_id: UUID of the grid. Found in the grid URL at app.bitscale.ai/grid/{gridId}, or from list_grids results. Returns: grid id, name, description, row_count, created_at, updated_at, settings (auto_run, auto_dedupe, visibility, dedupe_column_id), columns (all columns including text, enrichment, formula, merge types with their id/key and name), and sources (data sources with schedule info). NOTE on columns vs run_grid inputs: - The column 'id' values here are UUIDs — use these for the 'output_columns' parameter of run_grid to filter which outputs you want. - The 'inputs' parameter of run_grid uses human-readable LABELS (e.g. "company_name", "website"), NOT column UUIDs. These labels are derived from the API data source columns configured on the grid. You can find the exact input labels in the BitScale app under the grid's Data Source → BitScale API panel, or by inspecting the source column names. """ if not grid_id: raise ValueError("grid_id must not be empty") data = _get(f"/grids/{grid_id}") return json.dumps(data, indent=2) - main.py:123-124 (registration)The tool is registered via the @mcp.tool() decorator on line 123, which registers it with the FastMCP server instance as a callable tool named 'get_grid_details'.
@mcp.tool() def get_grid_details(grid_id: str) -> str: - main.py:124-124 (schema)The schema/type for the input is defined in the function signature: grid_id is a required string (str type annotation). The return type is str (JSON-formatted string).
def get_grid_details(grid_id: str) -> str: - main.py:47-53 (helper)The _get helper function performs authenticated GET requests using the BitScale API base URL, auth headers, and optional query params/timeout. It's called by get_grid_details to fetch the grid data.
def _get(path: str, params: dict | None = None, timeout: int = 30) -> dict: """Perform an authenticated GET request against the BitScale API.""" url = f"{BITSCALE_API_BASE}{path}" with httpx.Client(timeout=timeout) as client: response = client.get(url, headers=_headers(), params=params) response.raise_for_status() return response.json()