seattle-open-data

Seattle Data Query Dataset

seattle_data_query_dataset

Read-only

Query one Seattle open dataset by ID to return bounded rows or aggregate counts; use filters, grouping, and sorted paging for analysis without downloading all rows.

Instructions

Run a bounded read or aggregate on one dataset; paging stops at 10,000 rows.

For counts and breakdowns, use count() with group_by, not row paging. With cursor, send only dataset_id, cursor, and optionally page_size or detail. For all rows, give the user download_url (detail="full") instead of paging. Example: {"dataset_id": "kzjm-xkqj", "select": ["type", "count() AS n"], "group_by": ["type"], "order_by": ["n DESC"]}. Typically 1-5 s; fails with query_timeout after 30 s.

Input Schema

TableJSON Schema

Name	Required	Description
`mode`	No	clauses (default): built from the clause arguments, paged by cursor. soql: run `soql` verbatim, one page.
`near`	No	Rows within radius_m meters of a point.
`soql`	No	Full SoQL statement; set mode='soql' and no clause arguments. Not paged: use LIMIT <= page_size and advance OFFSET.
`where`	No	SoQL predicate, e.g. "datetime >= '2026-09-01T00:00:00'". Never append Z or call now(); both fail. Omit for all rows.
`cursor`	No	next_cursor from the previous page; omit for page one.
`detail`	No	summary (default) or full: adds query_url and download_url (CSV of all matching rows).
`having`	No	Predicate on aggregated rows, e.g. "n > 10"; omit for none.
`select`	No	Columns or expressions, e.g. ["type", "count(*) AS n"]. Omit for all data columns.
`group_by`	No	e.g. ["type"]; omit for no grouping.
`order_by`	No	e.g. ["n DESC"]; omit for arbitrary order. DESC lists nulls first: for most recent, add `col IS NOT NULL` to where.
`page_size`	No	Most rows to return (default 100; wide rows may return fewer). Omit on a continuation to keep the first page's size.
`dataset_id`	Yes	Socrata dataset id, e.g. kzjm-xkqj (from seattle_data_search_datasets).
`search_text`	No	Full-text search across text columns.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`rows`	Yes
`source`	Yes
`columns`	Yes
`has_more`	Yes
`query_url`	No
`truncated`	Yes
`dataset_id`	Yes
`consistency`	Yes
`next_cursor`	No
`download_url`	No
`returned_rows`	Yes
`effective_query`	No
`truncation_hint`	No
`coverage_warnings`	No
`query_url_omitted`	No
`truncation_reason`	No
`download_url_omitted`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 16, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations only cover read-only and open-world status; the description adds the operational traits that matter: a 10,000-row paging ceiling, typical latency of 1-5 s, and a hard failure mode ('query_timeout after 30 s'). The cursor continuation constraint is a behavioral rule not derivable from the schema alone.

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?

Front-loads the core operation and row cap, then layers paging rules, an alternative path, a compact JSON example, and timing. Every sentence carries actionable information with no filler.

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?

For a 13-parameter query tool with an output schema, the description covers the things the schema and annotations cannot: aggregation-vs-paging guidance, continuation semantics, row limits, and timeout behavior. Nothing an agent needs before invoking it is missing.

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 description coverage is 100%, so the baseline is 3; the description still adds value by constraining continuation payloads (only dataset_id, cursor, and optionally page_size or detail) and by pairing count(*) with group_by in the worked example.

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 ('run a bounded read or aggregate on one dataset') plus an explicit scope limit ('paging stops at 10,000 rows'). This cleanly separates it from the sibling search/describe/reference tools, which don't execute queries against a dataset.

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 routing rules: use count(*) with group_by for counts and breakdowns rather than paging, and hand the user download_url with detail='full' instead of paging for all rows. It also states what to send on a continuation call with cursor, which is exactly the when/when-not guidance an agent needs.

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

Deploy Server