Server definition

Hash: sha256:afaa0b97bc424f314fb4dcf7fa6c6407fae65c8ddb1ae4a4c06b472077333657
What it is: What a remote MCP server returned when asked what it offers: 6 tools

The blob, as servednamed by its sha256

{
  "instructions": "Government open-data server wrapping the Socrata SODA 2.1 API and Discovery API.\nWorkflow: socrata_list_portals → socrata_find_datasets → socrata_get_dataset (inspect schema) → socrata_query_dataset.\nA dataset ID is only valid on its own portal: pass it with the domain from the same socrata_find_datasets result. Domains are bare hostnames (data.cityofnewyork.us); URL forms are reduced to the host.\nSoQL references columns by API field name (field_name from socrata_get_dataset, e.g. cuisine_description), never the display label.\nAll SODA 2.1 row values are strings. Column data_type from socrata_get_dataset determines WHERE quoting:\n  Number columns: bare literals (year=2023)\n  Text columns: single-quoted strings (year='2023')\nSet SOCRATA_APP_TOKEN for higher rate limits. Set CANVAS_PROVIDER_TYPE=duckdb for SQL analytics on large result sets.",
  "tools": [
    {
      "description": "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.",
      "inputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "properties": {
          "canvas_id": {
            "description": "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.",
            "pattern": "^[A-Za-z0-9_-]{10}$",
            "type": "string"
          }
        },
        "type": "object"
      },
      "name": "socrata_dataframe_describe",
      "outputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "anyOf": [
          {
            "not": {
              "required": [
                "error"
              ]
            },
            "required": [
              "tables"
            ]
          },
          {
            "required": [
              "error"
            ]
          }
        ],
        "properties": {
          "canvas_id": {
            "description": "Canvas ID resolved, when canvas is enabled.",
            "type": "string"
          },
          "error": {
            "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. `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"
          },
          "notice": {
            "description": "Status message when canvas is not enabled or no tables are registered. Absent when tables are present.",
            "type": "string"
          },
          "tables": {
            "description": "Tables available for SQL queries. Empty when none registered.",
            "items": {
              "additionalProperties": false,
              "description": "A registered DataCanvas table.",
              "properties": {
                "columns": {
                  "description": "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).",
                  "items": {
                    "additionalProperties": false,
                    "description": "Column name and DuckDB type.",
                    "properties": {
                      "name": {
                        "description": "Column name.",
                        "type": "string"
                      },
                      "type": {
                        "description": "DuckDB column type (e.g. VARCHAR, DOUBLE, BOOLEAN, JSON). SODA number columns are DOUBLE; text and timestamp columns are VARCHAR.",
                        "type": "string"
                      }
                    },
                    "required": [
                      "name",
                      "type"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                },
                "row_count": {
                  "description": "Number of rows in this table.",
                  "type": "number"
                },
                "table_id": {
                  "description": "Table name registered on the canvas.",
                  "type": "string"
                }
              },
              "required": [
                "table_id",
                "row_count",
                "columns"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "type": "object"
      }
    },
    {
      "description": "Run SELECT-only SQL against a DataCanvas table populated by socrata_query_dataset. Columns SODA types as number (including aggregate aliases like count(*) as n) are staged as DOUBLE, so numeric comparisons work without a cast (year > 2020, amount < 500). Text and timestamp columns stay VARCHAR — compare times with CAST(date AS TIMESTAMP). Only works when CANVAS_PROVIDER_TYPE=duckdb is set. Use socrata_dataframe_describe to see registered tables and their schemas.",
      "inputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "properties": {
          "canvas_id": {
            "description": "Canvas ID returned from socrata_query_dataset or socrata_dataframe_describe.",
            "pattern": "^[A-Za-z0-9_-]{10}$",
            "type": "string"
          },
          "limit": {
            "default": 1000,
            "description": "Max rows to return (1–10000). Default 1000.",
            "maximum": 10000,
            "minimum": 1,
            "type": "integer"
          },
          "sql": {
            "description": "SELECT-only SQL to run against registered canvas tables. DDL, DML, and file-reading functions are rejected. Use table names from socrata_dataframe_describe.",
            "type": "string"
          }
        },
        "required": [
          "canvas_id",
          "sql"
        ],
        "type": "object"
      },
      "name": "socrata_dataframe_query",
      "outputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "anyOf": [
          {
            "not": {
              "required": [
                "error"
              ]
            },
            "required": [
              "rows",
              "row_count",
              "sql",
              "canvas_id"
            ]
          },
          {
            "required": [
              "error"
            ]
          }
        ],
        "properties": {
          "canvas_id": {
            "description": "Canvas ID queried.",
            "type": "string"
          },
          "cap": {
            "description": "The row limit that was applied when capped.",
            "type": "number"
          },
          "error": {
            "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_disabled`: CANVAS_PROVIDER_TYPE is not set to duckdb — DataCanvas is unavailable. `canvas_not_found`: canvas_id does not match any registered canvas. `table_not_found`: The SQL referenced a canvas table that does not exist — expired, dropped, or a mistyped name. `sql_rejected`: SQL was not a SELECT statement, referenced a system catalog, or contained disallowed functions. Other values are possible when a failure originates below the handler.",
                    "examples": [
                      "canvas_disabled",
                      "canvas_not_found",
                      "table_not_found",
                      "sql_rejected"
                    ],
                    "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"
          },
          "notice": {
            "description": "Guidance when the SQL returned zero rows. Absent when rows are present.",
            "type": "string"
          },
          "row_count": {
            "description": "Number of rows returned.",
            "type": "number"
          },
          "rows": {
            "description": "Query result rows. DuckDB may return native JS types (number, boolean, null) for numeric/boolean columns.",
            "items": {
              "additionalProperties": {},
              "propertyNames": {
                "type": "string"
              },
              "type": "object"
            },
            "type": "array"
          },
          "shown": {
            "description": "Rows returned in this response when capped.",
            "type": "number"
          },
          "sql": {
            "description": "SQL that was executed.",
            "type": "string"
          },
          "truncated": {
            "description": "True when results were capped at the limit — more rows match the query.",
            "type": "boolean"
          }
        },
        "type": "object"
      }
    },
    {
      "description": "Search for datasets across all Socrata-powered government open-data portals, or scope to one portal with the domain parameter. Returns dataset IDs, names, domains, update timestamps, and column_names — the API field names SoQL takes, not display labels. Use socrata_get_dataset to fetch the typed column schema before writing queries — column_names carry no type information.",
      "inputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "properties": {
          "categories": {
            "description": "Filter by domain categories (e.g. [\"Public Safety\", \"Transportation\"]).",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "domain": {
            "description": "Scope search to a single portal by bare hostname (e.g. data.seattle.gov, data.cityofnewyork.us); URL forms like https://data.seattle.gov/ are accepted and reduced to the host. Omit to search all portals.",
            "type": "string"
          },
          "limit": {
            "default": 10,
            "description": "Number of results to return (1–100). Default 10.",
            "maximum": 100,
            "minimum": 1,
            "type": "integer"
          },
          "offset": {
            "default": 0,
            "description": "Pagination offset. Default 0.",
            "maximum": 9007199254740991,
            "minimum": 0,
            "type": "integer"
          },
          "only": {
            "description": "Filter by asset type. Omit to include all types. Usually \"datasets\" is what you want.",
            "enum": [
              "datasets",
              "maps",
              "files",
              "calendars",
              "stories"
            ],
            "type": "string"
          },
          "order": {
            "description": "Sort order. Defaults to relevance. Use updated_at to surface recently-refreshed datasets.",
            "enum": [
              "relevance",
              "page_views_total",
              "created_at",
              "updated_at"
            ],
            "type": "string"
          },
          "query": {
            "description": "Full-text search across dataset names and descriptions. Omit to browse without filtering.",
            "type": "string"
          },
          "tags": {
            "description": "Filter by tags (e.g. [\"covid19\", \"permits\"]).",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "name": "socrata_find_datasets",
      "outputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "anyOf": [
          {
            "not": {
              "required": [
                "error"
              ]
            },
            "required": [
              "results",
              "totalCount"
            ]
          },
          {
            "required": [
              "error"
            ]
          }
        ],
        "properties": {
          "effectiveQuery": {
            "description": "Search query applied, for reference.",
            "type": "string"
          },
          "error": {
            "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: `rate_limited`: Discovery API returned 429. `unknown_domain`: The Discovery catalog does not index the domain (\"Domain not found\"). `invalid_domain`: The domain is not a hostname, even after dropping a URL scheme, path, or query. Other values are possible when a failure originates below the handler.",
                    "examples": [
                      "rate_limited",
                      "unknown_domain",
                      "invalid_domain"
                    ],
                    "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"
          },
          "notice": {
            "description": "Recovery hint when results are empty — echoes filters and suggests how to broaden. Absent on non-empty result pages.",
            "type": "string"
          },
          "results": {
            "description": "Matching datasets. Empty when no results.",
            "items": {
              "additionalProperties": false,
              "description": "A single matching dataset.",
              "properties": {
                "category": {
                  "description": "Domain category when available.",
                  "type": "string"
                },
                "column_names": {
                  "description": "API field names — the identifiers SoQL takes in select/where/group/order (e.g. cuisine_description), not display labels. Computed-region system columns are dropped; empty when the catalog lists no field names. No type info — call socrata_get_dataset for the typed schema.",
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                "data_updated_at": {
                  "description": "ISO 8601 timestamp of last data update when available.",
                  "type": "string"
                },
                "dataset_id": {
                  "description": "Four-by-four dataset ID (e.g. kzjm-xkqj). Pass to socrata_get_dataset or socrata_query_dataset.",
                  "type": "string"
                },
                "description": {
                  "description": "Dataset description when available.",
                  "type": "string"
                },
                "domain": {
                  "description": "Portal domain hosting this dataset (e.g. data.seattle.gov).",
                  "type": "string"
                },
                "license": {
                  "description": "Dataset license when available.",
                  "type": "string"
                },
                "name": {
                  "description": "Dataset display name.",
                  "type": "string"
                },
                "tags": {
                  "description": "Associated tags.",
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                "view_count": {
                  "description": "Total page views when available.",
                  "type": "number"
                }
              },
              "required": [
                "dataset_id",
                "domain",
                "name",
                "tags",
                "column_names"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "totalCount": {
            "description": "Total matches before pagination. 0 when empty.",
            "type": "number"
          }
        },
        "type": "object"
      }
    },
    {
      "description": "Fetch full metadata and column schema for a Socrata dataset by ID. Returns field names, data types, descriptions, row count, and licensing. Always call this before writing a socrata_query_dataset — the column types determine correct WHERE clause syntax: Number columns accept bare literals (year=2023) while Text columns require single-quoted strings (year='2023').",
      "inputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "properties": {
          "dataset_id": {
            "description": "Four-by-four dataset ID matching pattern like kzjm-xkqj. IDs are portal-scoped: take it from socrata_find_datasets together with that result’s domain.",
            "type": "string"
          },
          "domain": {
            "description": "Portal the dataset lives on, as a bare hostname (e.g. data.cityofnewyork.us); URL forms like https://data.cityofnewyork.us/ are accepted and reduced to the host. Pass the domain from the same socrata_find_datasets result as dataset_id. Defaults to SOCRATA_DEFAULT_DOMAIN or data.seattle.gov, which is wrong for another portal’s ID.",
            "type": "string"
          }
        },
        "required": [
          "dataset_id"
        ],
        "type": "object"
      },
      "name": "socrata_get_dataset",
      "outputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "anyOf": [
          {
            "not": {
              "required": [
                "error"
              ]
            },
            "required": [
              "dataset_id",
              "domain",
              "name",
              "tags",
              "columns"
            ]
          },
          {
            "required": [
              "error"
            ]
          }
        ],
        "properties": {
          "category": {
            "description": "Domain category when available.",
            "type": "string"
          },
          "columns": {
            "description": "Column schema. Computed region columns (:@computed_region_*) are excluded to reduce noise.",
            "items": {
              "additionalProperties": false,
              "description": "A single column in the dataset schema.",
              "properties": {
                "data_type": {
                  "description": "Socrata data type (e.g. Number, Text, Calendar date). Determines WHERE clause quoting: Number → bare literal, Text → single-quoted string.",
                  "type": "string"
                },
                "description": {
                  "description": "Column description when available.",
                  "type": "string"
                },
                "field_name": {
                  "description": "Column field name as used in SoQL queries.",
                  "type": "string"
                },
                "non_null_count": {
                  "description": "Non-null row count for this column when available.",
                  "type": "number"
                }
              },
              "required": [
                "field_name",
                "data_type"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "data_updated_at": {
            "description": "ISO 8601 timestamp of last data update when available.",
            "type": "string"
          },
          "dataset_id": {
            "description": "Four-by-four dataset ID.",
            "type": "string"
          },
          "description": {
            "description": "Dataset description when available.",
            "type": "string"
          },
          "domain": {
            "description": "Portal domain hosting this dataset.",
            "type": "string"
          },
          "error": {
            "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: `invalid_id`: Dataset ID does not match the four-by-four pattern. `not_found`: Valid ID format but the dataset does not exist on the domain queried — including a gateway HTTP 403 for an ID the portal does not serve. `unknown_domain`: The domain does not serve the Socrata API to this server: its hostname does not resolve (DNS ENOTFOUND), its API answered HTTP 404 without a Socrata error body, it redirected the request to another host that did not answer with Socrata data, or a gateway refused a dataset the Discovery catalog lists there. `invalid_domain`: The domain is not a hostname, even after dropping a URL scheme, path, or query. `rate_limited`: SODA endpoint returned 429. Other values are possible when a failure originates below the handler.",
                    "examples": [
                      "invalid_id",
                      "not_found",
                      "unknown_domain",
                      "invalid_domain",
                      "rate_limited"
                    ],
                    "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"
          },
          "license": {
            "description": "License name when available.",
            "type": "string"
          },
          "name": {
            "description": "Dataset display name.",
            "type": "string"
          },
          "row_count": {
            "description": "Approximate row count when available. See row_count_source for provenance.",
            "type": "number"
          },
          "row_count_source": {
            "description": "How row_count was obtained: 'top_level_cached_contents' — reported directly by the portal's views metadata; 'column_cached_contents' — derived as the maximum per-column cached count when the top-level value is absent. Absent when row_count is absent.",
            "enum": [
              "top_level_cached_contents",
              "column_cached_contents"
            ],
            "type": "string"
          },
          "tags": {
            "description": "Associated tags.",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "type": "object"
      }
    },
    {
      "description": "List known Socrata-powered government open-data portals with their domain, organization name, and approximate dataset count. The catalog is a curated list of 39 well-known portals; dataset counts are fetched from the Discovery API and cached for ~24 hours. Filtering is client-side substring match on the query parameter. Use this first when you do not know which portal to target, then pass the domain to socrata_find_datasets.",
      "inputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "properties": {
          "limit": {
            "default": 50,
            "description": "Max portals to return (1–200). Default 50.",
            "maximum": 200,
            "minimum": 1,
            "type": "integer"
          },
          "offset": {
            "default": 0,
            "description": "Pagination offset. Default 0.",
            "maximum": 9007199254740991,
            "minimum": 0,
            "type": "integer"
          },
          "query": {
            "description": "Keyword to filter portal names or organization names (case-insensitive substring match). Omit to list all portals.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "name": "socrata_list_portals",
      "outputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "anyOf": [
          {
            "not": {
              "required": [
                "error"
              ]
            },
            "required": [
              "portals",
              "totalCount"
            ]
          },
          {
            "required": [
              "error"
            ]
          }
        ],
        "properties": {
          "error": {
            "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.",
                    "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"
          },
          "notice": {
            "description": "Recovery hint when no portals matched the filter. Absent on non-empty pages.",
            "type": "string"
          },
          "portals": {
            "description": "Matching portals. Empty when no results.",
            "items": {
              "additionalProperties": false,
              "description": "A single Socrata portal.",
              "properties": {
                "dataset_count": {
                  "description": "Approximate count of dataset-type assets on this portal from the Discovery API catalog (point-in-time, refreshed ~daily). 0 means the portal exposes no dataset assets to the catalog; null means the live count is temporarily unavailable.",
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "domain": {
                  "description": "Portal domain (e.g. data.seattle.gov). Pass to socrata_find_datasets.",
                  "type": "string"
                },
                "organization": {
                  "description": "Organization name when available (e.g. City of Seattle).",
                  "type": "string"
                }
              },
              "required": [
                "domain",
                "dataset_count"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "totalCount": {
            "description": "Total portals before pagination. 0 when empty.",
            "type": "number"
          }
        },
        "type": "object"
      }
    },
    {
      "description": "Execute a SoQL query against any dataset on any Socrata portal. Use the search parameter for quick full-text lookup, or combine select/where/group/having/order for full analytical control. Returns rows plus the assembled SoQL string so you can learn the pattern. Columns are referenced by API field name (field_name from socrata_get_dataset, e.g. cuisine_description), never the display label. All SODA 2.1 row values are strings even for numeric columns — check data_type from socrata_get_dataset to determine correct WHERE quoting: Number columns use bare literals (year=2023), Text columns use single-quoted strings (year='2023'). To enumerate distinct values, use select=\"col, count(*) as n\" with group=\"col\" and order=\"n DESC\". When CANVAS_PROVIDER_TYPE=duckdb and rows fill limit, up to 50,000 matching rows spill to a DataCanvas table whatever the limit: list its columns with socrata_dataframe_describe, then run SQL with socrata_dataframe_query.",
      "inputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "properties": {
          "canvas_id": {
            "description": "Optional 10-char DataCanvas token from a prior socrata_query_dataset or socrata_dataframe_describe call. Omit on first call when CANVAS_PROVIDER_TYPE=duckdb to mint a fresh canvas. Large result sets spill here automatically.",
            "pattern": "^[A-Za-z0-9_-]{10}$",
            "type": "string"
          },
          "dataset_id": {
            "description": "Four-by-four dataset ID (e.g. kzjm-xkqj). IDs are portal-scoped: take it from socrata_find_datasets together with that result’s domain.",
            "type": "string"
          },
          "domain": {
            "description": "Portal the dataset lives on, as a bare hostname (e.g. data.cityofnewyork.us); URL forms like https://data.cityofnewyork.us/ are accepted and reduced to the host. Pass the domain from the same socrata_find_datasets result as dataset_id. Defaults to SOCRATA_DEFAULT_DOMAIN or data.seattle.gov, which is wrong for another portal’s ID.",
            "type": "string"
          },
          "group": {
            "description": "SoQL GROUP BY clause over API field names (field_name from socrata_get_dataset). Requires an aggregate function in select.",
            "type": "string"
          },
          "having": {
            "description": "SoQL HAVING clause. Filters on aggregated results, e.g. count > 100.",
            "type": "string"
          },
          "limit": {
            "default": 100,
            "description": "Max rows to return (1–5000). Default 100. Use with offset for pagination. When the canvas is enabled and the page fills limit, up to 50,000 matching rows are staged on it whatever the limit — pass a small limit (e.g. 10) to stage a large match without a large inline page.",
            "maximum": 5000,
            "minimum": 1,
            "type": "integer"
          },
          "offset": {
            "default": 0,
            "description": "Row offset for pagination. Default 0.",
            "maximum": 9007199254740991,
            "minimum": 0,
            "type": "integer"
          },
          "order": {
            "description": "SoQL ORDER BY clause over API field names or select aliases, e.g. \"total_deaths DESC\" or \"date ASC\".",
            "type": "string"
          },
          "search": {
            "description": "Full-text search across all text columns ($q). For field-specific filtering, use where instead.",
            "type": "string"
          },
          "select": {
            "description": "SoQL SELECT clause — API field names (field_name from socrata_get_dataset, not display labels), aliases, aggregates: \"state, sum(deaths) as total_deaths\". Omit for all columns.",
            "type": "string"
          },
          "where": {
            "description": "SoQL WHERE clause over API field names (field_name from socrata_get_dataset). Check column data_type there first — Number columns: year=2023, Text columns: year='2023'; an unquoted text value is read as a column name. Operators: =, !=, >, <, LIKE, IN(...), BETWEEN, IS NULL, starts_with(), contains(), AND, OR, NOT.",
            "type": "string"
          }
        },
        "required": [
          "dataset_id"
        ],
        "type": "object"
      },
      "name": "socrata_query_dataset",
      "outputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "anyOf": [
          {
            "not": {
              "required": [
                "error"
              ]
            },
            "required": [
              "rows",
              "row_count",
              "assembled_query",
              "domain",
              "dataset_id"
            ]
          },
          {
            "required": [
              "error"
            ]
          }
        ],
        "properties": {
          "assembled_query": {
            "description": "SoQL clauses assembled for this request — useful for learning the syntax.",
            "type": "string"
          },
          "canvas_id": {
            "description": "DataCanvas token when results spilled (requires CANVAS_PROVIDER_TYPE=duckdb). Pass to socrata_dataframe_query to run SQL over the staged rows in table_name — a bounded copy of the matching set (up to 50,000 rows, reported in canvas_row_count), not the full set when total_count exceeds that cap. Page with offset to reach rows beyond it.",
            "type": "string"
          },
          "canvas_row_count": {
            "description": "Rows staged onto the DataCanvas — a bounded copy of the matching result set (capped at 50,000). Fewer than total_count when the match exceeds the cap. Present only when canvas_id is.",
            "type": "number"
          },
          "cap": {
            "description": "The row limit that was applied when capped.",
            "type": "number"
          },
          "dataset_id": {
            "description": "Dataset ID queried.",
            "type": "string"
          },
          "domain": {
            "description": "Portal hostname queried, normalized from the domain input.",
            "type": "string"
          },
          "error": {
            "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: `invalid_id`: Dataset ID does not match the four-by-four pattern. `not_found`: The dataset does not exist on the domain queried — including a gateway HTTP 403 for an ID the portal does not serve. `unknown_domain`: The domain does not serve the Socrata API to this server: its hostname does not resolve (DNS ENOTFOUND), its API answered HTTP 404 without a Socrata error body, it redirected the request to another host that did not answer with Socrata data, or a gateway refused a dataset the Discovery catalog lists there. `invalid_domain`: The domain is not a hostname, even after dropping a URL scheme, path, or query. `soql_error`: SoQL syntax error, unknown column, or literal/column type mismatch. data.socrataCode carries the upstream code and data.column the offending token when upstream names one. `rate_limited`: SODA endpoint returned 429. Other values are possible when a failure originates below the handler.",
                    "examples": [
                      "invalid_id",
                      "not_found",
                      "unknown_domain",
                      "invalid_domain",
                      "soql_error",
                      "rate_limited"
                    ],
                    "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"
          },
          "notice": {
            "description": "Guidance when the query returned zero rows (review the SoQL or broaden the filter), or when rows filled the limit (how to page, and the staged table to query when the result spilled). Absent otherwise.",
            "type": "string"
          },
          "row_count": {
            "description": "Rows returned in this response.",
            "type": "number"
          },
          "rows": {
            "description": "Result rows. Scalar values are strings (SODA 2.1); geo/location columns return nested objects. Use column schema from socrata_get_dataset for type context.",
            "items": {
              "additionalProperties": {},
              "propertyNames": {
                "type": "string"
              },
              "type": "object"
            },
            "type": "array"
          },
          "shown": {
            "description": "Rows returned in this response when capped.",
            "type": "number"
          },
          "table_name": {
            "description": "Canvas table holding the staged rows; present when canvas_id is. Use it as the FROM target in socrata_dataframe_query SQL; list its columns with socrata_dataframe_describe.",
            "type": "string"
          },
          "total_count": {
            "description": "Total matching source rows when a plain row query is truncated (row_count < total_count). Absent when the full result fits and for grouped/aggregate queries (group set), where a source-row count would not describe the returned groups.",
            "type": "number"
          },
          "truncated": {
            "description": "True when rows filled the limit — more rows may match (see total_count when present). Spills to canvas when enabled; table_name names the staged table.",
            "type": "boolean"
          }
        },
        "type": "object"
      }
    }
  ]
}

Verify it yourself

curl -s https://api.teppi.xyz/v1/evidence/sha256:afaa0b97bc424f314fb4dcf7fa6c6407fae65c8ddb1ae4a4c06b472077333657 | sha256sum