socrata-mcp-server

Describe DataCanvas Tables

socrata_dataframe_describe

Read-onlyIdempotent

List registered tables in a DataCanvas session — schema, row count, and column names. Shows what datasets are available for SQL queries via socrata_dataframe_query. Only meaningful when CANVAS_PROVIDER_TYPE=duckdb is set. Use after socrata_query_dataset spills a large result set to canvas.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`canvas_id`	No	Canvas ID returned by socrata_query_dataset when a large result spills to canvas. Required in practice when canvas is enabled — canvases cannot be enumerated, so omitting it fails with canvas_id_required instead of listing tables.

Output Schema

TableJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Status message when canvas is not enabled or no tables are registered. Absent when tables are present.
`tables`	No	Tables available for SQL queries. Empty when none registered.
`canvas_id`	No	Canvas ID resolved, when canvas is enabled.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 22, 2026

changedOutput schema / properties / tables / items / properties / columns / description

Previous value: -"Column names and DuckDB types. Numeric SODA columns become queryable with numeric comparisons after spillover."New value: +"Column names and DuckDB types. SODA number columns are staged as DOUBLE, so numeric comparisons (year > 2020) need no cast; compare timestamps with CAST(col AS TIMESTAMP)."

changedOutput schema / properties / tables / items / properties / columns / items / properties / type / description

Previous value: -"DuckDB inferred type (e.g. VARCHAR, DOUBLE, BIGINT)."New value: +"DuckDB column type (e.g. VARCHAR, DOUBLE, BOOLEAN, JSON). SODA number columns are DOUBLE; text and timestamp columns are VARCHAR."

Changed2 schema fields changedSep 20, 2026

addedInput schema / properties / canvas_id / pattern
```
Added value: +"^[A-Za-z0-9_-]{10}$"
```

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `canvas_id_required`: Canvas is enabled but canvas_id was omitted or blank. `canvas_not_found`: Provided canvas_id does not match any registered canvas. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `canvas_id_required`: Canvas is enabled but canvas_id was omitted. `canvas_not_found`: Provided canvas_id does not match any registered canvas. Other values are possible when a failure originates below the handler."

Changed6 schema fields changedAug 22, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "tables"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `canvas_id_required`: Canvas is enabled but canvas_id was omitted or blank. `canvas_not_found`: Provided canvas_id does not match any registered canvas. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "canvas_id_required",
+            "canvas_not_found"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required
```
Removed value: -[
-  "tables"
-]
```

Changed1 schema field changedJul 4, 2026

changedInput schema / properties / canvas_id / description

Previous value: -"Canvas ID returned from socrata_query_dataset. Omit to list all tables visible in the current session."New value: +"Canvas ID returned by socrata_query_dataset when a large result spills to canvas. Required in practice when canvas is enabled — canvases cannot be enumerated, so omitting it fails with canvas_id_required instead of listing tables."

Changed2 schema fields changedMay 30, 2026

removedOutput schema / properties / message

Removed value: -{
-  "description": "Status message when canvas is not enabled or no tables are registered. Absent when tables are present.",
-  "type": "string"
-}

addedOutput schema / properties / notice

Added value: +{
+  "description": "Status message when canvas is not enabled or no tables are registered. Absent when tables are present.",
+  "type": "string"
+}

First observedMay 25, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare readOnlyHint and idempotentHint, so the read-only, safe nature is covered. The description adds behavioral context beyond annotations: the environmental dependency on CANVAS_PROVIDER_TYPE=duckdb and the recommended usage after a spill event, which helps an agent understand when this tool will actually work.

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

Conciseness5/5

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

The description is three sentences with no fluff: the first states the core function, the second clarifies what it shows, and the third gives the environmental condition and usage trigger. Every sentence earns its place and the information is front-loaded.

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

Completeness5/5

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

Given the simple one-parameter design, the presence of an output schema, and annotations covering safety, the description is complete. It tells the agent what the tool does, when it is meaningful, and after which event to use it, leaving no critical gaps for correct invocation.

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

Parameters3/5

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

The input schema has 100% coverage, with a detailed description for canvas_id explaining its pattern, practical requirement, and failure mode. The tool description itself provides no additional parameter semantics, so the baseline score of 3 is appropriate since the schema already carries the parameter meaning.

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?

The description states a specific action ('List registered tables in a DataCanvas session') with concrete output details (schema, row count, column names). It clearly distinguishes the tool from siblings by referencing its role for socrata_dataframe_query and the spill-triggering relationship with socrata_query_dataset.

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

Usage Guidelines4/5

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

The description explicitly gives a condition ('Only meaningful when CANVAS_PROVIDER_TYPE=duckdb is set') and a specific trigger ('Use after socrata_query_dataset spills a large result set to canvas'). It also frames the tool as a precursor to socrata_dataframe_query, which conveys when it is appropriate, though it does not name alternative tools to avoid.

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

All socrata-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.