Skip to main content
Glama
opendata-atlas

opendata-atlas

Describe dataset

atlas_describe_dataset
Read-only

Inspect a Socrata dataset's columns, live row count, data coverage, place-field values, and geo columns before querying data whose schema you do not know.

Instructions

Decide whether and how to query a dataset: columns, live row count, data_coverage (actual time range), place fields for "in " questions (with reliability), and geo columns for near.

Call before querying a dataset whose columns you do not know. For area questions, use detail="full". Filter a place field on its value, never its label; an area may span several values. Illustrative example: {"portal": "example-city", "dataset_id": "abcd-1234", "detail": "full"}. With column_cursor, send only portal, dataset_id, column_query, detail, column_cursor. Typically 1-3 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_describe_dataset"
  }
}

Input Schema

NameRequiredDescriptionDefault
detailNosummary (default) or full: adds place-field values and column stats.
portalYesPortal id (its hostname) or alias, from atlas_find_portals. Repeat it on every page of a paged call.
dataset_idYesSocrata dataset id, e.g. abcd-1234 (from atlas_search_datasets).
sample_rowsNoExample rows to include. Default 0.
column_queryNoOnly columns whose name or description contains this; omit for all.
column_cursorNonext_column_cursor from the previous page; omit for page one.

Output Schema

NameRequiredDescriptionDefault
titleYes
sourceYes
columnsYes
guide_uriNo
knowledgeYes
row_countYes
dataset_idYes
geo_columnsYes
sample_rowsNo
geo_unusableNo
place_fieldsYes
queryabilityYes
columns_totalYesColumns matching column_query, across all pages.
data_coverageYes
time_semanticsYes
example_queriesNo
stats_availableYes
has_more_columnsYes
next_column_cursorNoSend as column_cursor for the next columns; omitted on the last.
unit_of_observationNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed46 schema fields changedv0.3.0
    • addedOutput schema / $defs
      Added value: +{
      +  "Knowledge": {
      +    "additionalProperties": false,
      +    "description": "Level none (nothing recorded), profiled (observations only) or reviewed (interpretations).",
      +    "properties": {
      +      "level": {
      +        "enum": [
      +          "none",
      +          "profiled",
      +          "reviewed"
      +        ]
      +      },
      +      "validation": {
      +        "enum": [
      +          "unchecked",
      +          "passed",
      +          "stale",
      +          "contradicted",
      +          "inconclusive"
      +        ]
      +      }
      +    },
      +    "required": [
      +      "level",
      +      "validation"
      +    ],
      +    "type": "object"
      +  },
      +  "PlaceValue": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "label": {
      +        "type": "string"
      +      },
      +      "value": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "label",
      +      "value"
      +    ],
      +    "type": "object"
      +  },
      +  "PlaceholderValue": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "rows": {
      +        "type": "integer"
      +      },
      +      "value": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "value",
      +      "rows"
      +    ],
      +    "type": "object"
      +  }
      +}
    • addedOutput schema / properties / columns / items / properties / knowledge / $ref
      Added value: +"#/$defs/Knowledge"
    • removedOutput schema / properties / columns / items / properties / knowledge / additionalProperties
      Removed value: -false
    • removedOutput schema / properties / columns / items / properties / knowledge / description
      Removed value: -"Level none (nothing recorded), profiled (observations only) or reviewed (interpretations)."
    • removedOutput schema / properties / columns / items / properties / knowledge / properties
      Removed value: -{
      -  "level": {
      -    "enum": [
      -      "none",
      -      "profiled",
      -      "reviewed"
      -    ],
      -    "type": "string"
      -  },
      -  "validation": {
      -    "enum": [
      -      "unchecked",
      -      "passed",
      -      "stale",
      -      "contradicted",
      -      "inconclusive"
      -    ],
      -    "type": "string"
      -  }
      -}
    • removedOutput schema / properties / columns / items / properties / knowledge / required
      Removed value: -[
      -  "level",
      -  "validation"
      -]
    • removedOutput schema / properties / columns / items / properties / knowledge / type
      Removed value: -"object"
    • removedOutput schema / properties / columns / items / properties / stats / properties / origin / default
      Removed value: -"cached_metadata"
    • removedOutput schema / properties / columns / items / properties / stats / properties / origin / type
      Removed value: -"string"
    • removedOutput schema / properties / data_coverage / items / properties / origin / type
      Removed value: -"string"
    • removedOutput schema / properties / data_coverage / items / properties / status / default
      Removed value: -"ok"
    • removedOutput schema / properties / data_coverage / items / properties / status / type
      Removed value: -"string"
    • addedOutput schema / properties / knowledge / $ref
      Added value: +"#/$defs/Knowledge"
    • removedOutput schema / properties / knowledge / additionalProperties
      Removed value: -false
    • removedOutput schema / properties / knowledge / description
      Removed value: -"Level none (nothing recorded), profiled (observations only) or reviewed (interpretations)."
    • removedOutput schema / properties / knowledge / properties
      Removed value: -{
      -  "level": {
      -    "enum": [
      -      "none",
      -      "profiled",
      -      "reviewed"
      -    ],
      -    "type": "string"
      -  },
      -  "validation": {
      -    "enum": [
      -      "unchecked",
      -      "passed",
      -      "stale",
      -      "contradicted",
      -      "inconclusive"
      -    ],
      -    "type": "string"
      -  }
      -}
    • removedOutput schema / properties / knowledge / required
      Removed value: -[
      -  "level",
      -  "validation"
      -]
    • removedOutput schema / properties / knowledge / type
      Removed value: -"object"
    • addedOutput schema / properties / place_fields / items / properties / candidate_placeholders / items / $ref
      Added value: +"#/$defs/PlaceholderValue"
    • removedOutput schema / properties / place_fields / items / properties / candidate_placeholders / items / additionalProperties
      Removed value: -false
    • removedOutput schema / properties / place_fields / items / properties / candidate_placeholders / items / properties
      Removed value: -{
      -  "rows": {
      -    "type": "integer"
      -  },
      -  "value": {
      -    "type": "string"
      -  }
      -}
    • removedOutput schema / properties / place_fields / items / properties / candidate_placeholders / items / required
      Removed value: -[
      -  "value",
      -  "rows"
      -]
    • removedOutput schema / properties / place_fields / items / properties / candidate_placeholders / items / type
      Removed value: -"object"
    • removedOutput schema / properties / place_fields / items / properties / kind / type
      Removed value: -"string"
    • addedOutput schema / properties / place_fields / items / properties / layer_features
      Added value: +{
      +  "description": "When stats_status is not ok: every feature of the region layer as label and feature id, read from the layer; not which features rows use. Omitted for a layer of over 100 features or when the result budget is short.",
      +  "items": {
      +    "$ref": "#/$defs/PlaceValue"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / properties / place_fields / items / properties / placeholder_values / items / $ref
      Added value: +"#/$defs/PlaceholderValue"
    • removedOutput schema / properties / place_fields / items / properties / placeholder_values / items / additionalProperties
      Removed value: -false
    • removedOutput schema / properties / place_fields / items / properties / placeholder_values / items / properties
      Removed value: -{
      -  "rows": {
      -    "type": "integer"
      -  },
      -  "value": {
      -    "type": "string"
      -  }
      -}
    • removedOutput schema / properties / place_fields / items / properties / placeholder_values / items / required
      Removed value: -[
      -  "value",
      -  "rows"
      -]
    • removedOutput schema / properties / place_fields / items / properties / placeholder_values / items / type
      Removed value: -"object"
    • removedOutput schema / properties / place_fields / items / properties / reliability / type
      Removed value: -"string"
    • removedOutput schema / properties / place_fields / items / properties / source / type
      Removed value: -"string"
    • removedOutput schema / properties / place_fields / items / properties / stats_status / type
      Removed value: -"string"
    • removedOutput schema / properties / place_fields / items / properties / validation / type
      Removed value: -"string"
    • addedOutput schema / properties / place_fields / items / properties / values / items / $ref
      Added value: +"#/$defs/PlaceValue"
    • removedOutput schema / properties / place_fields / items / properties / values / items / additionalProperties
      Removed value: -false
    • removedOutput schema / properties / place_fields / items / properties / values / items / properties
      Removed value: -{
      -  "label": {
      -    "type": "string"
      -  },
      -  "value": {
      -    "type": "string"
      -  }
      -}
    • removedOutput schema / properties / place_fields / items / properties / values / items / required
      Removed value: -[
      -  "label",
      -  "value"
      -]
    • removedOutput schema / properties / place_fields / items / properties / values / items / type
      Removed value: -"object"
    • removedOutput schema / properties / queryability / type
      Removed value: -"string"
    • removedOutput schema / properties / row_count / properties / origin / type
      Removed value: -"string"
    • removedOutput schema / properties / row_count / properties / status / default
      Removed value: -"ok"
    • removedOutput schema / properties / row_count / properties / status / 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"
    • removedOutput schema / properties / time_semantics / items / properties / validation / type
      Removed value: -"string"
  2. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered; the description adds what annotations cannot — typical latency (1-3 s), the failure mode and threshold (query_timeout after 30 s), and paging semantics via column_cursor. The warning that a place field's label may map to multiple values is genuine domain behavior an agent could not infer from structured fields.

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

Conciseness4/5

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

Front-loaded with the decision and the returned content, then supporting rules in short sentences; the example object earns its place by showing a realistic call. Some clauses are telegraphic fragments ("Illustrative example:", the cursor rule), which reads efficient but slightly clipped.

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 6-parameter read tool with a full output schema, the description covers the decision to call, the mode selection, the paging path, downstream filtering guidance, latency, and the timeout failure mode. Nothing an agent needs in order to invoke it correctly 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, but the description adds real meaning on top: it ties detail="full" to the area-question use case and constrains which parameters to resend when column_cursor is present. The remaining parameters (sample_rows, column_query) are left entirely to the schema, so it stops short of full coverage.

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?

Opens with a specific decision-oriented verb ("Decide whether and how to query a dataset") and enumerates exactly what the response contains: columns, live row count, data_coverage time range, place fields with reliability, and geo columns for `near`. This clearly separates it from atlas_query_dataset, which executes the query rather than describing the 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 an explicit trigger ("Call before querying a dataset whose columns you do not know"), a conditional mode switch ("For area questions, use detail=\"full\""), and a concrete downstream rule ("Filter a place field on its `value`, never its label; an area may span several values"). The paging instruction also names the exact parameter subset to send on continuation calls, leaving nothing to inference.

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