Skip to main content
Glama
opendata-atlas

opendata-atlas

Query dataset

atlas_query_dataset
Read-only

Run bounded read-only queries and aggregates on Socrata open-data datasets to retrieve filtered rows, counts, and grouped breakdowns with cursor paging.

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 portal, dataset_id, cursor, and optionally page_size or detail. For all rows, give the user download_url (clauses mode, detail="full") instead of paging. Honor coverage_warnings and knowledge_notice in the answer; take relative dates from source.now_local. Illustrative example: {"portal": "example-city", "dataset_id": "abcd-1234", "select": ["type", "count() AS n"], "group_by": ["type"], "order_by": ["n DESC"]}. Typically 1-5 s; fails with query_timeout after 30 s.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "portal": "<portal>",
      "dataset_id": "<dataset_id>"
    },
    "name": "atlas_query_dataset"
  }
}

Input Schema

NameRequiredDescriptionDefault
modeNoclauses (default): built from the clause arguments, paged by cursor. soql: run `soql` verbatim, one page.
nearNoRows within radius_m meters of a point; omit for no distance filter.
soqlNoFull SoQL statement; set mode='soql' and no clause arguments. Not paged: use LIMIT <= page_size and advance OFFSET.
whereNoSoQL predicate, e.g. "datetime >= '2026-09-01T00:00:00'". Never append Z or call now(); both fail. Omit for all rows.
cursorNonext_cursor from the previous page; omit for page one.
detailNosummary (default) or full: adds query_url and, in clauses mode, download_url (CSV of all matching rows).
havingNoPredicate on aggregated rows, e.g. "n > 10"; omit for none.
portalYesPortal id (its hostname) or alias, from atlas_find_portals. Repeat it on every page of a paged call.
selectNoColumns or expressions, e.g. ["type", "count(*) AS n"]. Omit for all data columns.
group_byNoe.g. ["type"]; omit for no grouping.
order_byNoe.g. ["n DESC"]; omit for arbitrary order. DESC lists nulls first: for most recent, add `col IS NOT NULL` to where.
page_sizeNoMost rows to return (default 100; wide rows may return fewer). Omit on a continuation to keep the first page's size.
dataset_idYesSocrata dataset id, e.g. abcd-1234 (from atlas_search_datasets).
search_textNoFull-text search across text columns; omit for none.

Output Schema

NameRequiredDescriptionDefault
rowsYes
hintsNo
sourceYes
columnsYes
has_moreYes
query_urlNo
truncatedYes
dataset_idYes
consistencyYes
next_cursorNo
download_urlNo
returned_rowsYes
effective_queryNo
truncation_hintNo
knowledge_noticeNoWhat this result relies on that no reviewed claim covers; level is the dataset's.
coverage_warningsNo
query_url_omittedNo
truncation_reasonNo
download_url_omittedNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv0.3.0
    • changedInput schema / properties / detail / description
      Previous value: -"summary (default) or full: adds query_url and download_url (CSV of all matching rows)."New value: +"summary (default) or full: adds query_url and, in clauses mode, download_url (CSV of all matching rows)."
    • removedOutput schema / properties / consistency / type
      Removed value: -"string"
    • removedOutput schema / properties / coverage_warnings / items / properties / reliability / type
      Removed value: -"string"
    • removedOutput schema / properties / coverage_warnings / items / properties / validation / type
      Removed value: -"string"
    • removedOutput schema / properties / knowledge_notice / properties / level / type
      Removed value: -"string"
    • removedOutput schema / properties / source / properties / now_local_reason / type
      Removed value: -"string"
    • removedOutput schema / properties / source / properties / portal / properties / tier / type
      Removed value: -"string"
  2. First observedv0.1.0

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare readOnlyHint and openWorldHint, and the description goes well beyond them: the 10,000-row paging ceiling, typical 1-5 s latency, failure mode query_timeout after 30 s, and the instruction to honor coverage_warnings/knowledge_notice and derive relative dates from source.now_local. This is behavioral context the structured fields cannot convey.

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 paging limit is front-loaded in the first clause, followed by imperative rules grouped by use case, then a compact example and a latency note. Every sentence is actionable; nothing is 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 14-parameter query tool with a nested geo object, the description covers routing, continuation protocol, output-detail behavior, warning handling, and timing/failure. With an output schema and full schema coverage present, nothing material 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 coverage is 100%, so the baseline is 3; the description adds cross-parameter semantics by pairing count(*) with group_by and tying detail="full" to download_url in clauses mode, plus the cursor-continuation parameter set. It does not restate per-parameter formats, but the added interaction rules are genuine value.

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 with scope: "Run a bounded read or aggregate on one dataset; paging stops at 10,000 rows." The aggregation and paging framing immediately distinguishes it from the sibling tools (find portals, search datasets, describe dataset, get reference), which are all metadata-oriented rather than data-returning.

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?

Explicit routing rules: use count(*) with group_by for counts/breakdowns rather than row paging, and hand the user download_url for all rows. It also constrains continuation calls ("With cursor, send only portal, dataset_id, cursor, and optionally page_size or detail"), which is exactly the kind of when/how 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.