MapSmith

Official

Overview Schema Source Related Servers Discussions Admin

run_sql

Destructive

Execute spatial SQL queries with DuckDB and ST_* functions to preview results or write full outputs as GeoParquet with provenance metadata.

Instructions

Run spatial SQL (DuckDB dialect, ST_* functions, read_parquet/ST_Read for files).

Without output_path: returns up to 50 preview rows. With output_path (.parquet): materializes the full result as GeoParquet with a provenance manifest. input_paths declares every dataset read; when omitted, the engine derives them from the query. Under MAPSMITH_WORKSPACE only SELECT runs, and coordinate systems (ST_Transform, ST_SetCRS) and dataset paths (ST_Read, read_parquet) must be string literals, so they can be checked before anything opens them; ST_Read takes there the formats whose coordinate system MapSmith reads first (GeoPackage, OGR SQLite and SpatiaLite with MapSmith-read SRS catalogues, shapefile, GeoParquet, GeoJSON, GML, FlatGeobuf, GeoTIFF, CSV...).

Input Schema

Name	Required	Description	Default
`query`	Yes
`input_paths`	No
`output_path`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.12.1Nov 3, 2026

addedInput schema / properties / input_paths

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Input Paths"
+}

First observedv0.3.0Aug 29, 2026

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations: 50-row preview cap, GeoParquet output plus provenance manifest, input_paths auto-derivation, and the sandbox rule that only SELECT runs and that CRS/path arguments must be string literals so they can be validated pre-execution. It does not disclose that writes/DDL are possible outside the workspace, which is why destructiveHint=true is set, so the destructive profile is only half explained.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and output behavior are front-loaded and the sentences are dense with real content, but the final ST_Read sentence degenerates into a rambling parenthetical format list ('GeoPackage, OGR SQLite and SpatiaLite with MapSmith-read SRS catalogues, shapefile, ... CSV...') that is hard to parse and adds little call-time value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex, high-blast-radius SQL executor, the description covers modes, sandbox constraints, literal-argument requirements, and format support; the output schema means return values need not be spelled out. Remaining gaps are error behavior and explicit warning about write/DDL statements outside the workspace.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must carry the load and largely does: query (dialect and function families), input_paths (declare every dataset read, engine derives them when omitted), output_path (controls preview vs full GeoParquet materialization). It stops short of syntax examples or a path-format example, leaving some inference.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ('Run spatial SQL') plus the dialect ('DuckDB, ST_* functions, read_parquet/ST_Read'), which instantly separates it from the single-purpose siblings (buffer_layer, spatial_join, reproject_layer). An agent knows this is the escape hatch for arbitrary spatial SQL rather than a fixed operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It distinguishes the two execution modes (preview without output_path vs full materialization with output_path) and states the MAPSMITH_WORKSPACE restriction, but never says when to reach for run_sql rather than a dedicated sibling like overlay_layers. Usage is implied by the SQL escape-hatch nature rather than explicitly routed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.