Wherobots

Describe a specific table.

⚠️ WORKFLOW: ALWAYS call this before writing queries that reference a table. Understanding the schema is essential for writing correct SQL queries.

📋 PREREQUISITES:

• Call search_documentation_tool first

• Use list_catalogs_tool, list_databases_tool, list_tables_tool to find the table

📋 NEXT STEPS after this tool:

1. Use generate_spatial_query_tool to create SQL using the schema

2. Use execute_query_tool to test the query

This tool retrieves the schema of a specified table, including column names and types. It is used to understand the structure of a table before querying or analysis.

Parameters

catalog : str The name of the catalog. database : str The name of the database. table : str The name of the table. ctx : Context FastMCP context (injected automatically)

Returns

TableDescriptionOutput A structured object containing the table schema information. - 'schema': The schema of the table, which may include column names, types, and other metadata.

Example Usage for LLM:

• When user asks for the schema of a specific table.

• Example User Queries and corresponding Tool Calls:

• User: "What is the schema of the 'users' table in the 'default' database of the 'wherobots' catalog?"

• Tool Call: describe_table('wherobots', 'default', 'users')

• User: "Describe the buildings table structure"

• Tool Call: describe_table('wherobots_open_data', 'overture', 'buildings')

Run the SQL query on a Wherobots catalog.

⚠️ WORKFLOW: ALWAYS test queries with this tool before generating code. Use limit=10 or limit=100 for initial testing to validate query logic.

📋 PREREQUISITES (required for reliable results):

• search_documentation_tool: Understand correct SQL syntax

• describe_table_tool: Verify table schema and column names

• generate_spatial_query_tool: Generate the SQL (recommended)

📋 NEXT STEPS after this tool:

• If query SUCCEEDS: Increase limit or remove it for full results

• If query FAILS: Use sql_debug_workflow prompt, check schema, retry

• Only generate application code AFTER SQL is validated and working

This tool allows users to execute SQL queries against the Wherobots catalog. It is typically used for data retrieval and analysis. Supports pagination for large result sets.

Remember:

• Ensure the output can be serialized to JSON.

• If query execution fails, analyze the error and provide a meaningful message to the user.

• Use limit and offset parameters for large result sets to avoid timeouts.

• Queries have a maximum execution time (configurable via settings or x-query-timeout header).

• The runtime ID can be customized via the x-runtime-id header (default: tiny).

• The runtime region can be customized via the x-runtime-region header (default: aws-us-west-2).

• The server sends periodic heartbeat messages during long-running queries to keep the connection alive.

• If the client disconnects, the query will be cancelled to avoid wasting resources.

Parameters

query : str The SQL query to be executed. ctx : Context FastMCP context (injected automatically) limit : int | None Optional maximum number of rows to return (default: 1000, max: 10000) offset : int | None Optional number of rows to skip for pagination (default: 0)

Returns

QueryExecutionOutput A structured object containing the results of the query execution. - 'success': Whether the query executed successfully - 'row_count': Number of rows returned - 'data': Query results as a list of dictionaries - 'query': The executed SQL query - 'error': Whether an error occurred - 'error_type': Type of error (if any) - 'error_message': Error message (if any) - 'execution_status': Status of execution

Example Usage for LLM:

• When user asks to run a specific SQL query.

• Example User Queries and corresponding Tool Calls:

• User: "Run the following SQL query: SELECT * FROM buildings WHERE state = 'California';"

• Tool Call: execute_query('SELECT * FROM buildings WHERE state = 'California';')

• User: "Execute this query with only the first 100 results"

• Tool Call: execute_query('SELECT * FROM large_table;', limit=100)

• User: "Get the next page of results"

• Tool Call: execute_query('SELECT * FROM large_table;', limit=100, offset=100)

Generate a spatial query based on the provided content.

⚠️ WORKFLOW: Call this ONLY after exploring docs and catalog. For best results, ensure you have already:

1. Called search_documentation_tool for relevant spatial functions

2. Used catalog tools to identify available tables

3. Called describe_table_tool for tables you want to query

📋 PREREQUISITES (strongly recommended):

• search_documentation_tool: Understand available spatial functions

• list_catalogs_tool / list_tables_tool: Find relevant tables

• describe_table_tool: Know the schema of tables you'll query

📋 NEXT STEPS after this tool:

1. Use execute_query_tool with limit=10 to TEST the query first

2. Iterate on the query if results are incorrect

3. Only generate application code AFTER SQL is validated

This tool allows user to translate their request into a spatial query.

Parameters

user_prompt : str The user's request or description of the spatial query they want to generate. ctx : Context FastMCP context (injected automatically)

Returns

QueryGenerationSummaryOutput A structured object containing the generated spatial query.

Example Usage for LLM:

• When user asks to generate a spatial query based on their request.

• When a user asks for information, statistics or analysis on data that is in tables within one or more of the catalogs they have access to in Wherobots.

• Example User Queries and corresponding Tool Calls:

• User: "Generate a SQL query to count buildings in California using Overture data."

• Tool Call: generate_spatial_query("Generate a SQL query to count buildings in California using Overture data.")

• User: "How can I find all parks within 5km of downtown Seattle?"

• Tool Call: generate_spatial_query("How can I find all parks within 5km of downtown Seattle?")

List all catalogs available for users.

⚠️ WORKFLOW: Call this after search_documentation_tool. Start your catalog exploration here to discover available data sources.

📋 PREREQUISITES:

• Call search_documentation_tool first to understand what you're looking for

📋 NEXT STEPS after this tool:

1. Use list_databases_tool to explore databases in a catalog

2. Use list_tables_tool to find tables in a database

3. Use describe_table_tool to get table schemas

This tool retrieves all available catalogs accessible with the provided API key. It is typically used as the first step in exploring the data hierarchy. This tool will fetch both managed catalogs, as well as external catalogs. (e.g., on Databricks)

Parameters

ctx : Context FastMCP context (injected automatically)

Returns

CatalogListOutput A structured object containing catalog information. - 'catalogs': List of catalog names. - 'count': Number of catalogs found.

Example Usage for LLM:

• When user asks for available catalogs.

• Example User Queries and corresponding Tool Calls:

• User: "What catalogs are available?"

• Tool Call: list_catalogs()

• User: "Show me all the data sources"

• Tool Call: list_catalogs()

List all databases in a given catalog.

⚠️ WORKFLOW: Call this after list_catalogs_tool to explore a specific catalog.

📋 PREREQUISITES:

• Call search_documentation_tool first to understand what you're looking for

• Call list_catalogs_tool to discover available catalogs

📋 NEXT STEPS after this tool:

1. Use list_tables_tool to find tables in a database

2. Use describe_table_tool to get table schemas before writing queries

This tool retrieves all databases within a specified catalog.

Parameters

catalog : str The name of the catalog. ctx : Context FastMCP context (injected automatically)

Returns

DatabaseListOutput A structured object containing database information. - 'catalog': The catalog name. - 'databases': List of database names. - 'count': Number of databases found.

Example Usage for LLM:

• When user asks for a specific catalog's databases.

• Example User Queries and corresponding Tool Calls:

• User: "List all databases in the 'wherobots' catalog."

• Tool Call: list_databases('wherobots')

• User: "What databases are in the foursquare catalog?"

• Tool Call: list_databases('foursquare')

Get complete hierarchy of catalogs, databases, and tables.

⚠️ WORKFLOW: Use this for a quick overview of all managed catalogs. For external catalogs, use list_catalogs_tool instead.

📋 PREREQUISITES:

• Call search_documentation_tool first to understand what data you need

📋 NEXT STEPS after this tool:

1. Use describe_table_tool to get schemas of tables you want to query

2. Use list_catalogs_tool to discover external catalogs not shown here

This tool provides a comprehensive view of all available assets in the Wherobots system, including their hierarchical relationships. It can be used to retrieve information about all catalogs, list all databases within those catalogs, and enumerate all tables within each database.

IMPORTANT LIMITATION:

• This tool is being DEPRECATED, but is the only way to get a full hierarchy in one call.

• This tool ONLY shows catalogs managed within Wherobots.

• External catalogs (e.g., on Databricks, other cloud platforms) are NOT visible in this hierarchy.

• If the user mentions specific catalog names that don't appear in the results, they may be external catalogs that need to be accessed differently.

• ALWAYS call list_catalogs_tool before or after calling this tool.

Parameters

ctx : Context FastMCP context (injected automatically)

Returns

HierarchyListOutput A structured object containing the hierarchy of catalogs, databases, and tables. - 'hierarchy': A dictionary representing the hierarchical structure, where keys are catalog names. Each catalog entry contains a dictionary of its databases. Each database entry includes a list of its tables. Each table entry contains its name. - 'summary': A dictionary providing counts of total catalogs, databases, and tables.

Example Usage for LLM:

• When user asks for a general overview of data, or specific items across multiple catalogs/databases.

• Example User Queries and corresponding Tool Calls:

• User: "List all tables in the 'default' database of the 'wherobots' catalog AND in the 'overture_maps_foundation' database of 'wherobots_open_data'."

• Tool Call: list_hierarchy()

• User: "Show me all databases in 'wherobots' and 'wherobots_open_data' catalogs."

• Tool Call: list_hierarchy()

• User: "What data is available?"

• Tool Call: list_hierarchy()

List all tables in a given database.

⚠️ WORKFLOW: Call this after list_databases_tool to find tables in a database.

📋 PREREQUISITES:

• Call search_documentation_tool first

• Call list_catalogs_tool and list_databases_tool to navigate to the database

📋 NEXT STEPS after this tool:

1. Use describe_table_tool to get the schema of tables you want to query

2. Use generate_spatial_query_tool to create SQL using the schema

3. Use execute_query_tool to test the query

This tool retrieves all tables within a specified database in a catalog. It is used to explore the final level of the data hierarchy before accessing table schemas.

Parameters

catalog : str The name of the catalog. database : str The name of the database. ctx : Context FastMCP context (injected automatically)

Returns

TableListOutput A structured object containing table information. - 'catalog': The catalog name. - 'database': The database name. - 'tables': List of table names. - 'count': Number of tables found.

Example Usage for LLM:

• When user asks for a specific database's tables.

• Example User Queries and corresponding Tool Calls:

• User: "List all tables in the 'default' database of the 'wherobots' catalog."

• Tool Call: list_tables('wherobots', 'default')

• User: "What tables are in the overture database?"

• Tool Call: list_tables('wherobots_open_data', 'overture')

Search the Wherobots documentation.

⚠️ WORKFLOW: This should be your FIRST tool call for any query task. Before writing queries, ALWAYS search documentation to understand:

• Available spatial functions and their syntax

• Best practices and common patterns

• Example queries for similar use cases

📋 NEXT STEPS after this tool:

1. Use catalog tools (list_catalogs, list_databases, list_tables) to find data

2. Use describe_table_tool to understand table schemas

3. Use generate_spatial_query_tool to create SQL queries

This tool searches the official Wherobots documentation to find relevant information about spatial functions, data formats, best practices, and more. It's useful when users need help understanding Wherobots features or syntax.

Parameters

query : str The search query string ctx : Context FastMCP context (injected automatically) page_size : int | None Optional number of results to return (default: 10)

Returns

DocumentationSearchOutput A structured object containing documentation search results. - 'results': List of DocumentResult objects, each containing: - 'content': The documentation content snippet - 'path': The URL path to the documentation page - 'metadata': Additional metadata about the result

Example Usage for LLM:

• When user asks about Wherobots features, functions, or syntax

• When generating queries and need context about spatial functions

• Example User Queries and corresponding Tool Calls:

• User: "How do I use ST_INTERSECTS in Wherobots?"

• Tool Call: search_documentation("ST_INTERSECTS spatial function")

• User: "What spatial functions are available for distance calculations?"

• Tool Call: search_documentation("spatial distance functions")

• User: "How do I connect to Wherobots from Python?"

• Tool Call: search_documentation("Python connection API")

For the best way to understand how to use spatial SQL in Wherobots, refer to the following Wherobots Documentation:

• Writing Effective Spatial Queries in Wherobots: https://docs.wherobots.com/develop/write-spatial-queries

• Writing Effective Spatial Queries in Wherobots complete example sub-section: https://docs.wherobots.com/develop/write-spatial-queries#complete-example:-counting-baseball-stadiums-in-the-us

The complete example demonstrates:

• Starting the SedonaContext

• Using wkls where applicable

• Loading spatial data from Wherobots tables

• Using the correct schema from wherobots_open_data spatial catalogs

• Writing spatial SQL queries effectively