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. Meaningful when the server has a DataCanvas. Use after socrata_query_dataset spills a large result set to canvas.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "socrata_dataframe_describe"
  }
}

Input 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

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.5/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so safety and side-effect profile need no repeating. The description adds genuine context beyond that: the tool is only meaningful when a DataCanvas exists, and it is meant to be called after a spill event. The canvas_id_required failure mode is left to the schema rather than surfaced here, which keeps it from a 5.

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?

Three short sentences, each earning its place: what it returns, what it is for, and when it becomes relevant. The return contents are front-loaded before the usage conditions.

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?

The tool is a single-parameter read with full schema coverage and an output schema, so return-value detail need not be described. The description supplies the prerequisite context (DataCanvas present) and the upstream trigger (a spill from socrata_query_dataset), leaving nothing an agent needs in order to call it correctly.

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?

Schema description coverage is 100%, and the canvas_id description already explains the pattern, provenance, and the canvas_id_required failure when omitted. The tool description adds only an indirect hint about canvas usage, so the baseline 3 applies — the schema does the heavy lifting.

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?

States a specific verb and resource ('List registered tables in a DataCanvas session') and immediately scopes what each entry contains (schema, row count, column names). It also differentiates from siblings by naming socrata_dataframe_query as the consumer of what this tool lists, so an agent can separate discovery from querying.

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

Usage Guidelines5/5

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

Gives explicit triggering context — 'Meaningful when the server has a DataCanvas' and 'Use after socrata_query_dataset spills a large result set to canvas' — plus the alternative workflow (query via socrata_dataframe_query). The when-to-use condition and the sibling relationship are both spelled out rather than inferred.

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.