LocalData MCP Tools Reference

Complete reference documentation for all 70 MCP tools. Organized by category for quick navigation.

Table of Contents

Core Database (8 tools)
Streaming & Memory (9 tools)
Tree/Structured Data (10 tools)
Graph Operations (7 tools)
Search & Transform (2 tools)
Schema & Audit (3 tools)
System (1 tool)
Data Science (12 tools)
Sampling & Estimation (4 tools)
Optimization (4 tools)
Geospatial (10 tools)

The tree tools in section 3 double as the node-level graph API: get_node, set_node, delete_node, list_keys, get_value, set_value, and delete_key detect a graph connection and read their path argument as a node ID. get_children and move_node work on trees only.

Core Database (8 tools)

connect_database

Open a connection to a database.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Unique connection identifier (e.g., “analytics_db”, “user_data”)
`db_type`	string	Yes	Database type: sqlite, postgresql, mysql, duckdb, csv, json, yaml, toml, excel, ods, numbers, xml, ini, tsv, parquet, feather, arrow, hdf5, dot, gml, graphml, mermaid, turtle, ntriples, sparql
`conn_string`	string	Yes	Connection string or file path
`sheet_name`	string	No	Sheet name for Excel/ODS/Numbers or dataset name for HDF5
`auth`	string	No	JSON authentication config (e.g., `{"method": "wallet", "wallet_path": "/path"}`)

Returns: Connection summary with metadata (JSON)

Example:

# SQL database
connect_database("mydb", "postgresql", "postgresql://user:pass@localhost/dbname")

# CSV file
connect_database("data", "csv", "/path/to/file.csv")

# Graph file
connect_database("network", "graphml", "/path/to/network.graphml")

Composition hints: Use with execute_query, describe_database, or data manipulation tools.

disconnect_database

Close a connection to a database. All connections close automatically on script termination.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Connection name to close

Returns: Success/error message with cleanup details (JSON)

Example:

disconnect_database("mydb")

Composition hints: Call after completing work with a database to free resources.

execute_query

Execute a SQL query and return results as JSON with memory-aware streaming.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Database connection name
`query`	string	Yes	SQL query to execute
`chunk_size`	integer	No	Results per chunk for pagination
`enable_analysis`	boolean	No	Perform pre-query analysis (default: true)
`include_blobs`	boolean	No	Base64-encode BLOBs in results (default: false)
`preflight`	boolean	No	Run EXPLAIN only (default: false)

Returns: Query results as JSON or streaming metadata (JSON)

Example:

execute_query("mydb", "SELECT * FROM users WHERE active = true", chunk_size=100)

Composition hints: Use with next_chunk for large result sets, get_query_metadata for analysis.

analyze_query_preview

Analyze a query without executing it to preview resource requirements.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Database connection name
`query`	string	Yes	SQL query to analyze

Returns: Analysis including estimated rows, memory, execution time, and risks (JSON)

Example:

analyze_query_preview("mydb", "SELECT * FROM large_table JOIN other_table ON ...")

Composition hints: Use before execute_query on complex queries to assess feasibility.

list_databases

List all available database connections with their SQL flavor information.

Parameters:

Name	Type	Required	Description
`include_staging`	boolean	No	Include active staging databases (default: false)

Returns: Array of connection objects with names and types (JSON)

Example:

list_databases()

Composition hints: Use to discover available connections for workflow orchestration.

describe_database

Get detailed information about a database including its schema in JSON format.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Database connection name

Returns: Database schema with tables, columns, types, and relationships (JSON)

Example:

describe_database("mydb")

Composition hints: Use with find_table to locate specific tables, or describe_table for details.

find_table

Find which database contains a specific table by name.

Parameters:

Name	Type	Required	Description
`table_name`	string	Yes	Name of table to locate

Returns: Connection name containing the table, or error if not found (JSON)

Example:

find_table("users")

Composition hints: Use in multi-database workflows to locate data without knowing connection.

describe_table

Get detailed schema information for a specific table.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Database connection name
`table_name`	string	Yes	Name of table to describe

Returns: Table schema with columns, types, constraints, and indexes (JSON)

Example:

describe_table("mydb", "users")

Composition hints: Use before writing queries to understand table structure and column types.

Streaming & Memory (9 tools)

next_chunk

Retrieve the next chunk of rows from a buffered query result.

Parameters:

Name	Type	Required	Description
`query_id`	string	Yes	ID of buffered query result
`start_row`	integer	Yes	Starting row number (1-based)
`chunk_size`	string	Yes	Number of rows or “all” for remaining

Returns: Chunk of rows with metadata (JSON)

Example:

next_chunk("mydb_12345_abc1", 1, "100")

Composition hints: Chain multiple calls to paginate through large result sets.

manage_memory_bounds

Monitor and manage memory usage across all streaming operations.

Parameters: None

Returns: Memory status, usage statistics, and cleanup actions taken (JSON)

Example:

manage_memory_bounds()

Composition hints: Call when memory warnings appear or before large operations.

get_streaming_status

Get detailed status of all active streaming operations and memory usage.

Parameters: None

Returns: Active buffers, memory usage, performance metrics (JSON)

Example:

get_streaming_status()

Composition hints: Monitor streaming workloads and identify bottlenecks.

clear_streaming_buffer

Clear a specific streaming result buffer to free memory immediately.

Parameters:

Name	Type	Required	Description
`query_id`	string	Yes	ID of buffer to clear

Returns: Confirmation message (JSON)

Example:

clear_streaming_buffer("mydb_12345_abc1")

Composition hints: Use after finishing with a large result set.

get_query_metadata

Get comprehensive metadata for a query result including quality metrics and processing recommendations.

Parameters:

Name	Type	Required	Description
`query_id`	string	Yes	ID of query result

Returns: LLM-friendly summary, quality metrics, complexity analysis (JSON)

Example:

get_query_metadata("mydb_12345_abc1")

Composition hints: Use with LLM-based analysis workflows for decision making.

request_data_chunk

Retrieve a specific chunk of data using the LLM communication protocol.

Parameters:

Name	Type	Required	Description
`query_id`	string	Yes	ID of query result
`chunk_id`	integer	Yes	Chunk ID to retrieve (0-based)

Returns: Chunk data with metadata (JSON)

Example:

request_data_chunk("mydb_12345_abc1", 0)

Composition hints: Use for targeted chunk retrieval in progressive loading workflows.

request_multiple_chunks

Retrieve multiple chunks efficiently in a single call.

Parameters:

Name	Type	Required	Description
`query_id`	string	Yes	ID of query result
`chunk_ids`	string	Yes	Comma-separated chunk IDs (e.g., “0,1,2”)

Returns: Multiple chunks with metadata (JSON)

Example:

request_multiple_chunks("mydb_12345_abc1", "0,1,2,3,4")

Composition hints: Use to load specific chunks in parallel.

cancel_query_operation

Cancel an ongoing query operation and free resources.

Parameters:

Name	Type	Required	Description
`query_id`	string	Yes	ID of query to cancel
`reason`	string	No	Reason for cancellation (default: “User requested”)

Returns: Cancellation status message (JSON)

Example:

cancel_query_operation("mydb_12345_abc1", "User interrupt")

Composition hints: Use on long-running queries to stop execution.

get_data_quality_report

Get comprehensive data quality assessment for a query result.

Parameters:

Name	Type	Required	Description
`query_id`	string	Yes	ID of query to assess

Returns: Detailed quality report including nulls, duplicates, outliers (JSON)

Example:

get_data_quality_report("mydb_12345_abc1")

Composition hints: Use before analytics to understand data cleanliness.

Tree/Structured Data (10 tools)

get_node

Get node details or summary for tree, graph, or RDF connections.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Connection name
`path`	string	No	Node path (tree), node_id (graph), or subject URI (RDF)

Returns: Node details or root summary (JSON)

Example:

get_node("config", "server/host")
get_node("network", "node-123")

Composition hints: Use with get_children to traverse hierarchies.

get_children

Get children of a node with pagination.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Connection name
`path`	string	No	Parent node path (null for root)
`offset`	integer	No	Pagination offset (default: 0)
`limit`	integer	No	Rows per page (default: 50)

Returns: Array of child nodes with metadata (JSON)

Example:

get_children("config", "database", offset=0, limit=20)

Composition hints: Chain calls with different offsets to paginate through large hierarchies.

set_node

Create a node in tree or graph connection.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Connection name
`path`	string	Yes	Path for new node
`label`	string	No	Display label (graph only)

Returns: Confirmation with node details (JSON)

Example:

set_node("config", "app/features/new_feature", "New Feature")

Composition hints: Use with set_value to add properties to nodes.

move_node

Move a node and its subtree under a new parent or to root.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Connection name
`path`	string	Yes	Node path to move
`new_parent`	string	No	New parent path (null for root)

Returns: Confirmation with new location (JSON)

Example:

move_node("config", "old/location/node", "new/location")

Composition hints: Use for reorganizing hierarchical structures.

delete_node

Delete a node and all its descendants.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Connection name
`path`	string	Yes	Node path to delete

Returns: Confirmation with deletion details (JSON)

Example:

delete_node("config", "deprecated/feature")

Composition hints: Use carefully as deletion cascades to all children.

list_keys

List key-value pairs at a node with pagination.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Connection name
`path`	string	Yes	Node path
`offset`	integer	No	Pagination offset (default: 0)
`limit`	integer	No	Results per page (default: 50)

Returns: Array of key-value pairs (JSON)

Example:

list_keys("config", "database")

Composition hints: Use with get_value to inspect node properties.

get_value

Get a specific property value from a node.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Connection name
`path`	string	Yes	Node path
`key`	string	Yes	Property key to retrieve

Returns: Property value and metadata (JSON)

Example:

get_value("config", "database", "host")

Composition hints: Use to read individual node properties.

set_value

Set a property on a node (auto-creates node if needed).

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Connection name
`path`	string	Yes	Node path
`key`	string	Yes	Property key
`value`	string	Yes	Property value
`value_type`	string	No	Data type hint

Returns: Confirmation with updated node (JSON)

Example:

set_value("config", "database", "host", "localhost", "string")

Composition hints: Use to modify node properties.

delete_key

Delete a property from a node.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Connection name
`path`	string	Yes	Node path
`key`	string	Yes	Property key to delete

Returns: Confirmation with remaining properties (JSON)

Example:

delete_key("config", "database", "deprecated_setting")

Composition hints: Use to remove obsolete node properties.

export_structured

Export tree data as TOML, JSON, YAML, or Markdown — or RDF data as Turtle or N-Triples. The accepted formats depend on the connection type; passing an RDF format to a tree connection (or the reverse) returns an error.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Connection name
`format`	string	Yes	Tree connections: `json`, `yaml`, `toml`, `markdown` (alias `md`). RDF connections: `turtle` (alias `ttl`), `ntriples` (alias `nt`)
`path`	string	No	Root path to export (null for all). Ignored for RDF connections, which always serialize the whole graph

Returns: {"format": ..., "content": ...}. Output above 100 KB is halved and returned with truncated: true and a notice

Example:

export_structured("config", "yaml", "server")

Composition hints: Use for data portability and backup.

Graph Operations (7 tools)

get_neighbors

Get neighbors of a graph node with edge information.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Connection name
`node_id`	string	Yes	Node ID
`direction`	string	No	Direction: “in”, “out”, or “both” (default: both)
`offset`	integer	No	Pagination offset (default: 0)
`limit`	integer	No	Results per page (default: 50)

Returns: Array of neighbors with edge information (JSON)

Example:

get_neighbors("network", "user-123", direction="out")

Composition hints: Use for network analysis and traversal.

get_edges

List edges in a graph, optionally filtered by node.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Connection name
`node_id`	string	No	Filter by node (null for all edges)
`offset`	integer	No	Pagination offset (default: 0)
`limit`	integer	No	Results per page (default: 50)

Returns: Array of edges with source, target, and properties (JSON)

Example:

get_edges("network", node_id="user-123")

Composition hints: Use for graph structure analysis and export.

add_edge

Add an edge to a graph (auto-creates nodes if needed).

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Connection name
`source`	string	Yes	Source node ID
`target`	string	Yes	Target node ID
`label`	string	No	Edge label or relationship type
`weight`	number	No	Edge weight (for weighted graphs)

Returns: Confirmation with edge details (JSON)

Example:

add_edge("network", "user-1", "user-2", "follows", weight=1.0)

Composition hints: Use to build or modify graphs programmatically.

remove_edge

Remove an edge from a graph.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Connection name
`source`	string	Yes	Source node ID
`target`	string	Yes	Target node ID
`label`	string	No	Edge label (for filtering)

Returns: Confirmation of removal (JSON)

Example:

remove_edge("network", "user-1", "user-2", "follows")

Composition hints: Use to modify graph topology.

find_path

Find path(s) between two graph nodes.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Connection name
`source`	string	Yes	Start node ID
`target`	string	Yes	End node ID
`algorithm`	string	No	Algorithm: “shortest” (default) or “all”

Returns: Path(s) with nodes and edges (JSON)

Example:

find_path("network", "user-1", "user-5", algorithm="shortest")

Composition hints: Use for network analysis and influence tracing.

get_graph_stats

Get advanced graph statistics including centrality measures.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Connection name

Returns: Graph metrics: node count, edge count, density, diameter, clustering (JSON)

Example:

get_graph_stats("network")

Composition hints: Use to characterize network properties.

export_graph

Export a graph in a machine-readable or agent-readable format.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Connection name
`format`	string	Yes	`dot`, `gml`, `graphml`, `mermaid` (alias `mmd`), `markdown` (alias `md`), `hierarchy`, `adjacency`, or `detailed`
`node_id`	string	No	Export the ego subgraph around this node (null for the whole graph). Ignored by the Markdown styles, which always render the full graph

hierarchy, adjacency, and detailed are Markdown styles: an indented tree for DAGs, a compact A -> B [label] list, and full per-node property sections respectively. Output above 100 KB is truncated and flagged with truncated: true plus a notice. For the non-Markdown formats, pass node_id to export a smaller subgraph instead.

Returns: {"format": ..., "content": ...}, or {"error": ...} for an unknown format or missing node

Example:

export_graph("network", "graphml")
export_graph("network", "adjacency")
export_graph("network", "mermaid", node_id="root")

Composition hints: Use for graph visualization and portability.

Search & Transform (2 tools)

search_data

Search query results for regex pattern matches.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Database connection name
`query`	string	Yes	SQL query to search within
`pattern`	string	Yes	Regex pattern to find
`columns`	string	No	Comma-separated column names (null for all)
`case_sensitive`	boolean	No	Case-sensitive search (default: true)
`max_matches`	integer	No	Maximum matches to return (default: 100)

Returns: Matching rows with metadata (JSON)

Example:

search_data("mydb", "SELECT * FROM emails", ".*@company\\.com", columns="email", case_sensitive=False)

Composition hints: Use for content discovery and data validation.

transform_data

Apply regex find/replace to a column in query results.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Database connection name
`query`	string	Yes	SQL query to transform
`column`	string	Yes	Column name to apply transformation
`find`	string	Yes	Regex pattern to find
`replace`	string	Yes	Replacement string (supports capture groups)
`max_rows`	integer	No	Maximum rows to process (default: 1000)

Returns: Transformed data preview (JSON)

Example:

transform_data("mydb", "SELECT * FROM logs", "message", "ERROR: (.*)", "CRITICAL: $1")

Composition hints: Use for data cleaning and standardization.

Schema & Audit (3 tools)

export_schema

Export database schema in various formats.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Database connection name
`format`	string	No	Format: json_schema, python, typescript, sql_ddl (default: json_schema)
`tables`	string	No	Comma-separated table names (null for all)

Returns: Schema in requested format (string/JSON)

Example:

export_schema("mydb", format="typescript", tables="users,posts")

Composition hints: Use for code generation and documentation.

get_query_log

Get recent query execution history.

Parameters:

Name	Type	Required	Description
`database`	string	No	Filter by database (null for all)
`status`	string	No	Filter by status: success, error, timeout
`since_minutes`	integer	No	Look back this many minutes (default: 60)
`limit`	integer	No	Maximum entries to return (default: 50)

Returns: Query history entries with execution details (JSON)

Example:

get_query_log(database="mydb", status="error", since_minutes=30)

Composition hints: Use for debugging and performance analysis.

get_error_log

Get recent error and timeout history.

Parameters:

Name	Type	Required	Description
`database`	string	No	Filter by database (null for all)
`since_minutes`	integer	No	Look back this many minutes (default: 60)
`limit`	integer	No	Maximum entries to return (default: 50)

Returns: Error entries with context and suggestions (JSON)

Example:

get_error_log(database="mydb", since_minutes=60)

Composition hints: Use for troubleshooting connection and query issues.

System (1 tool)

check_compatibility

Check backward compatibility status and get migration recommendations.

Parameters:

Name	Type	Required	Description
`generate_migration_script`	boolean	No	Generate migration script for legacy config (default: false)

Returns: Compatibility report and migration guidance (JSON)

Example:

check_compatibility(generate_migration_script=True)

Composition hints: Use during upgrades or configuration migrations.

Data Science (12 tools)

Every tool in this section has the same first two parameters: the name of a live connection and a SQL query. The query selects the data; there is no separate load step and no data-frame parameter. Column parameters name columns in the query’s result set.

Where a parameter takes a list of columns, it is a genuine list (["price", "sqft"]), not a comma-separated string. Where a parameter selects a method, only the values listed below are accepted; anything else raises ValueError.

analyze_hypothesis_test

Run a statistical hypothesis test on query results.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`query`	string	Yes	SQL query returning data
`test_type`	string	No	`auto`, `ttest_1samp`, `ttest_ind`, `ttest_rel`, `chi2`, `normality`, `correlation` (default: `auto`)
`column`	string	No	Column to test (default: empty, meaning all numeric columns)
`group_column`	string	No	Grouping column for two-sample tests
`alpha`	number	No	Significance level (default: 0.05)
`alternative`	string	No	`two-sided`, `less`, or `greater` (default: `two-sided`)

Returns: A test_results list, one entry per test performed, each with test_name, statistic, p_value, and an interpretation string (JSON).

Example:

analyze_hypothesis_test("mydb", "SELECT score FROM experiments", test_type="ttest_1samp")

Composition hints: With test_type="auto" and no column named, this reports normality and correlation checks across the numeric columns — a reasonable first call before choosing a specific test.

analyze_anova

Compare group means with a one-way ANOVA.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`query`	string	Yes	SQL query with the dependent and grouping columns
`dependent_var`	string	Yes	Column holding the numeric values being compared
`group_var`	string	Yes	Column defining the groups
`alpha`	number	No	Significance level (default: 0.05)

Returns: F-statistic, p-value, per-group means, and effect size (JSON)

Example:

analyze_anova("mydb", "SELECT revenue, region FROM sales", "revenue", "region")

Composition hints: Follow a significant result with analyze_effect_sizes to judge whether the difference matters in practice.

analyze_effect_sizes

Calculate effect sizes for a comparison between groups.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`query`	string	Yes	SQL query returning the value and grouping columns
`column`	string	Yes	Numeric column to compare
`group_column`	string	Yes	Column defining the groups

There is no effect_type parameter; the measure follows from the data. The tool takes four arguments, not five.

Returns: Effect size value and interpretation (JSON)

Example:

analyze_effect_sizes("mydb", "SELECT score, treatment FROM experiments", "score", "treatment")

Composition hints: Pair with a hypothesis test — significance answers “is there a difference”, effect size answers “is it worth acting on”.

analyze_regression

Fit a regression model to query results.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`query`	string	Yes	SQL query with the feature and target columns
`target_column`	string	Yes	Column to predict
`feature_columns`	list of strings	No	Columns to use as features. Omit to use every numeric column except the target
`model_type`	string	No	`linear`, `ridge`, `lasso`, `elastic_net`, `logistic`, `polynomial` (default: `linear`)
`regularization`	string	No	`l1`, `l2`, `elastic_net`, or empty for none (default: empty)

Returns: model_type, the resolved pipeline_config, a regression_analysis block with coefficients and fit statistics, and a residual_analysis block for non-logistic models (JSON)

Example:

analyze_regression("mydb", "SELECT * FROM properties", "price", ["sqft", "bedrooms", "year_built"], model_type="ridge")

Composition hints: Use model_type="logistic" for a binary target. Pass the model’s predictions back through evaluate_model_performance to score them.

evaluate_model_performance

Score predictions that are already stored alongside their actual values.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`query`	string	Yes	SQL query returning both the actual and the predicted column
`target_column`	string	Yes	Column with the actual values
`prediction_column`	string	Yes	Column with the predicted values
`model_type`	string	No	`regression` or `classification` (default: `regression`)

The metric set follows from model_type; there is no metric_type parameter.

Returns: Performance metrics and diagnostics for the chosen model type (JSON)

Example:

evaluate_model_performance("mydb", "SELECT actual_price, predicted_price FROM test_results", "actual_price", "predicted_price")

Composition hints: Use after scoring a model whose predictions you have written back to the database.

analyze_clusters

Group rows by similarity across numeric columns.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`query`	string	Yes	SQL query returning the columns to cluster on
`columns`	list of strings	No	Columns to cluster on. Omit to use every numeric column
`method`	string	No	`kmeans`, `dbscan`, `hierarchical`, `gaussian_mixture` (default: `kmeans`)
`n_clusters`	integer	No	Number of clusters. Omit to let the method choose

Returns: Cluster assignments, centroids, and a silhouette score (JSON)

Example:

analyze_clusters("mydb", "SELECT * FROM customers", ["spending", "frequency", "recency"], method="kmeans", n_clusters=5)

Composition hints: Reduce dimensionality first when clustering on more than a handful of columns.

detect_anomalies

Flag rows that do not fit the rest of the data.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`query`	string	Yes	SQL query returning the columns to examine
`columns`	list of strings	No	Columns to examine. Omit to use every numeric column
`method`	string	No	`isolation_forest`, `local_outlier_factor`, `one_class_svm` (default: `isolation_forest`)
`contamination`	number	No	Expected proportion of anomalies, 0.0 to 0.5 (default: 0.1)

These are multivariate detectors over a set of columns. There is no single column parameter, no threshold, and no z-score or IQR method.

Returns: Anomaly flags, scores, and the flagged rows (JSON)

Example:

detect_anomalies("mydb", "SELECT * FROM transactions", ["amount", "item_count"], method="isolation_forest", contamination=0.05)

Composition hints: Use for data quality screening and fraud detection. Lower contamination when false positives are expensive.

reduce_dimensions

Project numeric columns onto fewer dimensions.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`query`	string	Yes	SQL query returning the columns to reduce
`columns`	list of strings	No	Columns to include. Omit to use every numeric column
`method`	string	No	`pca`, `tsne`, `umap` (default: `pca`)
`n_components`	integer	No	Target number of dimensions (default: 2)

Returns: The reduced components and, for PCA, explained variance (JSON)

Example:

reduce_dimensions("mydb", "SELECT * FROM gene_data", ["gene_a", "gene_b", "gene_c"], method="pca", n_components=3)

Composition hints: Run before analyze_clusters on wide data. pca is reversible and cheap; tsne and umap are for visualization, not for feeding another model.

analyze_time_series

Decompose a series and test it for stationarity.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`query`	string	Yes	SQL query returning the date and value columns
`date_column`	string	Yes	Column with datetime values
`value_column`	string	Yes	Column with numeric values
`frequency`	string	No	`D`, `W`, `M`, `Q`, `Y`, or empty to infer (default: empty)

The frequency codes are the pandas offset aliases, not words like daily.

Returns: Trend, seasonal and residual components, plus a stationarity test (JSON)

Example:

analyze_time_series("mydb", "SELECT date, price FROM stock_prices", "date", "price", frequency="D")

Composition hints: Run before forecast_time_series — a non-stationary series usually needs differencing or a different model.

forecast_time_series

Project a series forward.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`query`	string	Yes	SQL query returning the historical date and value columns
`date_column`	string	Yes	Column with datetime values
`value_column`	string	Yes	Column with numeric values
`horizon`	integer	No	Number of periods to forecast (default: 10)
`method`	string	No	`arima`, or `ets` / `exponential_smoothing` (default: `arima`)

Those are the only accepted values. There is no automatic model selection, and prophet and sarima both raise ValueError: Unknown forecast method: <name>. Use 'arima' or 'ets'. The SARIMA and ensemble forecasters in localdata_mcp.domains.time_series_analysis are reachable from Python but are exposed by no MCP tool.

Returns: Forecast values with confidence intervals (JSON)

Example:

forecast_time_series("mydb", "SELECT date, sales FROM sales_history", "date", "sales", horizon=30, method="arima")

Composition hints: Use for demand and capacity planning. Compare arima against ets on a held-out tail rather than trusting either by default.

analyze_rfm

Segment customers by recency, frequency, and monetary value.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`query`	string	Yes	SQL query returning transaction rows
`customer_column`	string	Yes	Column identifying the customer
`date_column`	string	Yes	Column with the transaction date
`value_column`	string	Yes	Column with the transaction value

Returns: RFM scores, customer segments, and value tiers (JSON)

Example:

analyze_rfm("mydb", "SELECT * FROM transactions", "customer_id", "order_date", "order_value")

Composition hints: Feed the resulting segments back into a query to size or target each one.

analyze_ab_test

Compare an experiment’s variants.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`query`	string	Yes	SQL query returning the variant and metric columns
`variant_column`	string	Yes	Column identifying control and treatment
`metric_column`	string	Yes	Column with the metric being compared
`alpha`	number	No	Significance level (default: 0.05)

The threshold is alpha, the significance level — not a confidence_level. For a 95% interval, pass alpha=0.05.

Returns: Test statistics, p-value, sample sizes, and power analysis (JSON)

Example:

analyze_ab_test("mydb", "SELECT variant, converted FROM experiment_results", "variant", "converted", alpha=0.05)

Composition hints: Pair with analyze_effect_sizes on the same columns to report lift alongside significance.

Sampling & Estimation (4 tools)

Tools for working with a subset of the data, and for putting an interval around a number rather than reporting it bare. Like the Data Science tools, each takes a connection name and a SQL query.

generate_sample

Draw a representative sample from query results.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`query`	string	Yes	SQL query returning the rows to sample from
`sampling_method`	string	No	`simple_random`, `stratified`, `systematic`, `cluster` (default: `simple_random`)
`sample_size`	number	No	A fraction when below 1, a row count when 1 or above (default: 0.1)
`columns`	list	No	Columns to keep in the sample (default: all)
`stratify_column`	string	No	Column defining the strata; required for `stratified`

Returns: The sampled rows plus a sampling_results summary giving the method, the realised sample size and the population size (JSON).

Example:

generate_sample("mydb", "SELECT * FROM customers", sampling_method="stratified",
                sample_size=500, stratify_column="region")

Composition hints: Sample first, then run an expensive analysis on the sample. Stratify on the column you intend to group by, so every group survives.

bootstrap_statistic

Estimate a statistic’s sampling distribution and confidence interval.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`query`	string	Yes	SQL query returning the column to resample
`column`	string	No	Numeric column (default: the first numeric column)
`statistic`	string	No	`mean`, `median`, `std`, `var`, `min`, `max` (default: `mean`)
`n_bootstrap`	integer	No	Resamples to draw (default: 1000)
`confidence_level`	number	No	Interval width, e.g. 0.95 (default: 0.95)

Returns: The observed statistic, its bootstrap standard error, and the confidence interval bounds (JSON).

Composition hints: Use when the sampling distribution is unknown or the sample is small — it makes no normality assumption, unlike analyze_effect_sizes.

monte_carlo_simulate

Run a Monte Carlo simulation parameterised by query results.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`query`	string	Yes	SQL query supplying the simulation’s parameters
`simulation_type`	string	No	`integration`, `optimization`, `risk_analysis` (default: `integration`)
`n_simulations`	integer	No	Iterations to run (default: 10000)
`columns`	list	No	Columns to draw parameters from (default: all numeric)

Returns: The simulation estimate, its standard error, and a convergence summary (JSON).

bayesian_estimate

Estimate a posterior distribution and credible interval from query results.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`query`	string	Yes	SQL query returning the observed data
`column`	string	No	Numeric column (default: the first numeric column)
`estimation_type`	string	No	`posterior`, `credible_interval`, `model_comparison` (default: `posterior`)
`prior_distribution`	string	No	`normal`, `uniform`, `beta`, `gamma` (default: `normal`)
`confidence_level`	number	No	Credible-interval width (default: 0.95)

Returns: Posterior parameters and the credible interval (JSON).

Composition hints: A credible interval answers “where does the value lie, given this data”, where bootstrap_statistic’s confidence interval answers “how would this estimate vary across repeated samples”. Choose by which question was asked.

Optimization (4 tools)

These four tools differ from every other analytical tool in one way: they take a table name, not a query. The solvers read the columns they need from the table directly. Node and cost identifiers must be numeric — a text column is rejected by name rather than failing inside a float conversion.

solve_linear_program

Minimise a linear objective subject to linear constraints.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`table_name`	string	Yes	Table holding the objective coefficients
`objective_column`	string	Yes	Numeric column, one coefficient per variable
`constraint_columns`	list	No	Columns forming the constraint matrix
`constraint_values`	list	No	Right-hand side per constraint; required with `constraint_columns`
`constraint_types`	list	No	Per constraint: `<=`, `>=` or `=` (default: `<=`)
`method`	string	No	Solver method (default: `highs`)
`integer_variables`	list	No	Indices of variables constrained to integers

Returns: The optimal variable values, the objective value, and solver status (JSON).

optimize_constrained

Optimize a nonlinear objective from a starting point stored in a column.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`table_name`	string	Yes	Table holding the starting point and any bounds
`objective_function`	string	Yes	Python expression in `x`, e.g. `np.sum(x**2)`
`initial_guess_column`	string	Yes	Numeric column giving the starting point
`constraint_functions`	list	No	Constraints as expressions in `x`
`constraint_types`	list	No	Per constraint: `eq` or `ineq`
`bounds_columns`	list	No	Two columns giving lower and upper bounds per variable
`method`	string	No	scipy.optimize method (default: `SLSQP`)

Returns: The optimal point, the objective value, iteration count and convergence status (JSON).

analyze_network

Analyze a graph stored as an edge table.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`table_name`	string	Yes	Table holding one edge per row
`source_column`	string	Yes	Numeric source-node column
`target_column`	string	Yes	Numeric target-node column
`weight_column`	string	No	Numeric edge weight (default: unweighted)
`directed`	boolean	No	Treat edges as directed (default: false)
`include_centrality`	boolean	No	Compute centrality measures (default: true)

Returns: Graph properties, centrality measures, shortest paths and a minimum spanning tree (JSON).

Composition hints: Distinct from the Graph Operations tools, which manage a stored graph. This one analyses an edge table that already exists as data.

solve_assignment_problem

Assign agents to tasks at optimal total cost.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`table_name`	string	Yes	Table holding the cost matrix, one agent per row
`cost_matrix_columns`	list	Yes	Numeric columns, one per task
`agent_id_column`	string	No	Column naming each agent (default: row index)
`task_id_column`	string	No	Column naming each task
`method`	string	No	`hungarian` or `greedy` (default: `hungarian`)
`maximize`	boolean	No	Maximise total value instead of minimising cost (default: false)

Returns: The chosen agent-to-task pairs and the total cost (JSON).

Geospatial (10 tools)

Spatial data reaches these tools in one of three shapes, and the parameters follow that split:

Point data — a pair of numeric coordinate columns, named by x_column and y_column (defaults x and y).
Geometry data — a single text column holding WKT, named by a *_geometry_column parameter (default geometry). WKT is how a geometry survives a database with no geometry type.
Network data — two queries, one for nodes and one for edges, which is how a graph is stored relationally.

perform_spatial_join accepts either of the first two on either side, because joining points to zones is the commonest spatial join and point tables rarely carry a WKT column.

check_geospatial_capabilities

Report which geospatial backends are installed and what they enable.

Parameters: none. This is the only tool in the reference that takes no connection.

Returns: Per-library availability and version, the list of missing libraries, and the feature set each enables (JSON).

Composition hints: Call this before an analysis that needs an optional backend. geopandas, shapely, pyproj and fiona ship as required dependencies; scikit-gstat (advanced kriging) and rasterio (raster data) do not.

analyze_spatial_autocorrelation

Test whether nearby locations hold similar values.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`query`	string	Yes	SQL returning the coordinate columns and the value column
`value_column`	string	Yes	Numeric column whose spatial pattern is tested
`x_column`	string	No	Longitude or easting column (default: `x`)
`y_column`	string	No	Latitude or northing column (default: `y`)
`method`	string	No	`moran` for Moran’s I, `geary` for Geary’s C (default: `moran`)
`k_neighbors`	integer	No	Neighbours defining each location’s neighbourhood (default: 8)

The query must return more than k_neighbors rows, or the call raises ValueError.

Returns: The statistic, its expected value under no autocorrelation, the variance, z-score, p-value, is_significant, and an interpretation string (JSON).

Example:

analyze_spatial_autocorrelation("mydb", "SELECT lon, lat, price FROM listings",
                                "price", x_column="lon", y_column="lat")

Composition hints: Settle this before treating geography as meaningful in a model. Significant positive autocorrelation is what justifies find_spatial_hotspots; without it, apparent clusters are noise. Moran’s I above its expected value and Geary’s C below 1 both indicate clustering.

find_spatial_hotspots

Locate statistically significant hot and cold spots (Getis-Ord Gi*).

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`query`	string	Yes	SQL returning the coordinate columns and the value column
`value_column`	string	Yes	Numeric column whose local clustering is tested
`x_column`	string	No	Longitude or easting column (default: `x`)
`y_column`	string	No	Latitude or northing column (default: `y`)
`significance_level`	number	No	p-value threshold for calling a spot (default: 0.05)

Returns: Hot-spot and cold-spot counts, an interpretation string, and a points list carrying each location’s Gi* statistic, z-score, p-value and a cluster_id of 1 (hot spot), -1 (cold spot) or 0 (not significant) (JSON).

Composition hints: A hot spot is a location surrounded by unusually high values, which is not the same as a high value — a lone peak among low neighbours is not a hot spot.

calculate_spatial_distances

Measure how far apart points are, and what each one’s nearest neighbour is.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`query`	string	Yes	SQL returning the coordinate columns
`x_column`	string	No	Longitude or easting column (default: `x`)
`y_column`	string	No	Latitude or northing column (default: `y`)
`distance_type`	string	No	`euclidean` in coordinate units, or `haversine` in kilometres (default: `euclidean`)
`reference_query`	string	No	SQL for a second set; distances are then measured from the first set to this one
`include_pairs`	boolean	No	Also return every individual pair (default: false)

Returns: A summary (min, max, mean, median, and mean nearest-neighbour distance) plus each point’s nearest neighbour. include_pairs adds every pair (JSON).

The tool refuses more than 2,000 points, and include_pairs refuses more than 10,000 pairs: the matrix grows with the square of the row count.

Composition hints: Use haversine for longitude/latitude pairs — treating degrees as a plane understates distance badly away from the equator.

optimize_route

Order and connect waypoints into the cheapest route across a network.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`nodes_query`	string	Yes	SQL returning one node per row with an id and coordinates
`edges_query`	string	Yes	SQL returning one edge per row with source and target ids
`waypoints`	list	Yes	Node ids the route must visit, in any order
`node_id_column`	string	No	Node identifier column (default: `id`)
`x_column`	string	No	Node longitude or easting column (default: `x`)
`y_column`	string	No	Node latitude or northing column (default: `y`)
`source_column`	string	No	Edge source node column (default: `source`)
`target_column`	string	No	Edge target node column (default: `target`)
`weight_column`	string	No	Edge cost column (default: straight-line distance)
`return_to_start`	boolean	No	Close the route back to its first waypoint (default: false)
`optimization_method`	string	No	Waypoint ordering strategy (default: `greedy`)

Returns: The ordered node path, its coordinates, the total distance, and the path as a WKT LINESTRING (JSON).

An edge naming a node the nodes query did not return is rejected by name rather than silently building a broken graph.

analyze_accessibility

Score how well a set of service points covers a set of demand points.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`nodes_query`	string	Yes	SQL returning one node per row with an id and coordinates
`edges_query`	string	Yes	SQL returning one edge per row with source and target ids
`service_locations`	list	Yes	Node ids where the service sits
`demand_locations`	list	Yes	Node ids that need to reach it
`node_id_column`	string	No	Node identifier column (default: `id`)
`x_column`	string	No	Node longitude or easting column (default: `x`)
`y_column`	string	No	Node latitude or northing column (default: `y`)
`source_column`	string	No	Edge source node column (default: `source`)
`target_column`	string	No	Edge target node column (default: `target`)
`weight_column`	string	No	Edge travel-cost column (default: distance)
`max_travel_time`	number	No	Cost beyond which a demand point counts unreachable
`impedance_function`	string	No	How cost decays into a score (default: `linear`)

Returns: A per-demand-point accessibility score and travel time, the reachable and unreachable lists, and a coverage summary (JSON).

Composition hints: unreachable_locations is the answer to “who is left out” — the question a coverage percentage hides.

generate_service_isochrones

Draw the area reachable from service points within each travel-time band.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`nodes_query`	string	Yes	SQL returning one node per row with an id and coordinates
`edges_query`	string	Yes	SQL returning one edge per row with source and target ids
`service_locations`	list	Yes	Node ids the service operates from
`time_bands`	list	Yes	Travel-cost cutoffs, one polygon per band
`node_id_column`	string	No	Node identifier column (default: `id`)
`x_column`	string	No	Node longitude or easting column (default: `x`)
`y_column`	string	No	Node latitude or northing column (default: `y`)
`source_column`	string	No	Edge source node column (default: `source`)
`target_column`	string	No	Edge target node column (default: `target`)
`weight_column`	string	No	Edge travel-cost column (default: distance)
`resolution`	integer	No	Polygon smoothness (default: 50)

Returns: One entry per band with the band’s cutoff, its polygon as WKT, and its area (JSON).

Composition hints: Compare the areas between bands to see where coverage stops growing, or between candidate sites to choose one.

perform_spatial_join

Attach the attributes of one geometry set to another by spatial relation.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`left_query`	string	Yes	SQL for the features that receive attributes
`right_query`	string	Yes	SQL for the features that supply them
`left_geometry_column`	string	No	WKT column on the left (default: `geometry`)
`right_geometry_column`	string	No	WKT column on the right (default: `geometry`)
`join_type`	string	No	`intersects`, `within`, `contains`, `nearest` (default: `intersects`)
`how`	string	No	`inner` to keep matches only, `left` to keep every left feature (default: `inner`)
`x_column`	string	No	Coordinate column used when there is no WKT column (default: `x`)
`y_column`	string	No	Coordinate column used when there is no WKT column (default: `y`)
`crs`	string	No	Coordinate reference system (default: `EPSG:4326`)

A side with neither a WKT column nor a coordinate pair raises ValueError naming both encodings it looked for.

Returns: Match counts and the joined rows, with left and right columns suffixed _left and _right and geometries written back out as WKT (JSON).

Example:

perform_spatial_join("mydb", "SELECT * FROM readings", "SELECT * FROM districts")

perform_spatial_overlay

Combine two geometry sets with a set operation.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`left_query`	string	Yes	SQL returning the left geometries as WKT
`right_query`	string	Yes	SQL returning the right geometries as WKT
`operation`	string	No	`intersection`, `union`, `difference` (default: `intersection`)
`left_geometry_column`	string	No	WKT column on the left (default: `geometry`)
`right_geometry_column`	string	No	WKT column on the right (default: `geometry`)
`crs`	string	No	Coordinate reference system (default: `EPSG:4326`)

Both sides must supply WKT geometries; coordinate pairs are not accepted, since a set operation on points is not meaningful.

Returns: Input and output feature counts and the resulting rows, geometries as WKT (JSON).

aggregate_points_in_polygons

Summarise a point measurement within each polygon that contains it.

Parameters:

Name	Type	Required	Description
`connection_name`	string	Yes	Database connection name
`point_query`	string	Yes	SQL returning the points and the value column
`polygon_query`	string	Yes	SQL returning the polygons as WKT
`value_column`	string	Yes	Numeric point column to summarise
`x_column`	string	No	Point longitude or easting column (default: `x`)
`y_column`	string	No	Point latitude or northing column (default: `y`)
`polygon_geometry_column`	string	No	WKT column on the polygons (default: `geometry`)
`aggregation_functions`	list	No	Any of `mean`, `sum`, `count`, `min`, `max`, `median`, `std` (default: mean, sum and count)
`crs`	string	No	Coordinate reference system (default: `EPSG:4326`)

Returns: Each polygon with one column per requested aggregation, named <value_column>_<function>. Polygons containing no points are kept, with a count of zero (JSON).

Example:

aggregate_points_in_polygons("mydb", "SELECT * FROM sensors",
                             "SELECT * FROM districts", "reading")

Composition hints: This is the spatial equivalent of a GROUP BY, and the usual bridge from point measurements into the Data Science tools, which work on the resulting per-polygon table.

Quick Reference Summary

Category	Count	Purpose
Core Database	8	Connect, query, inspect databases
Streaming & Memory	9	Handle large results, memory management
Tree/Structured	10	Hierarchical JSON, YAML, TOML data
Graph	7	Network analysis and manipulation
Search & Transform	2	Pattern matching and text replacement
Schema & Audit	3	Introspection and query history
System	1	Compatibility and migration check
Data Science	12	Statistical analysis, modeling and forecasting
Sampling & Estimation	4	Sampling, bootstrap, simulation, Bayesian inference
Optimization	4	Linear and nonlinear programming, networks, assignment
Geospatial	10	Spatial statistics, distance, routing, geometry
Total	70	Complete LLM-native data platform

All seventy tools are registered unconditionally.

Parameter Type Reference

Type	Format	Example
`string`	UTF-8 text	“mydb”, “users”, “/path/to/file”
`integer`	Whole numbers	100, -1, 0
`number`	Float/decimal	0.05, 3.14, 2.5
`boolean`	true/false	true, false
`optional`	[ ] indicates optional	Parameter with `[No]` in Required column

Return Format Convention

All tools return JSON-formatted responses with:

{
  "status": "success|error|warning",
  "data": { },
  "metadata": { }
}

Successful queries return "status": "success". Errors include context in metadata for debugging.

Composition Patterns

Sequential Loading

execute_query() -> get_query_metadata() -> request_multiple_chunks()

Exploration Workflow

list_databases() -> describe_database() -> find_table() -> describe_table()

Data Transformation

execute_query() -> search_data() -> transform_data() -> export_schema()

Analysis Pipeline

execute_query() -> analyze_clusters() -> reduce_dimensions() -> get_graph_stats()

For integration examples and advanced workflows, see the main documentation.