Skip to main content
Glama

Georgia Civic Data

by org.georgiacivicdata
OverviewDiscussionsAdmin

Describe a Dataset

describe_dataset
Read-onlyIdempotent

The full schema of one dataset: every column (type, role, unit, value range, what a NULL means), the exact filters with their valid values (the keys query_dataset and aggregate accept), how the code columns join to the lookup tables (foreign_keys), example queries, usage notes, limitations, and null semantics. key_metric names the headline figure most answers want. Per column, key_metric_grain_contributor marks a category the headline figure is only comparable within (pin it or group by it) and metric_component marks the numerator and denominator of a rate. recommended_query is a safe default query (headline figure, the filters to pin, required single-value choices) plus a ranking recipe for top or bottom N. filter_hints lists paired filters. non_additive lists columns whose rows overlap, so summing across them double counts; value_implications lists values that imply another column's value. year_meaning, when set, says what year labels when it is not when the figures were measured. pooled_rates lists rates whose figure for several rows is SUM(numerator) / SUM(denominator) (aggregate with agg='weighted_rate'), not an average of the rows' rates. series_breaks lists years from which figures are not comparable with earlier years (each with its reason; metrics, when present, limits it to those columns), so the step into such a year is not a trend. Each category filter carries has_total and requires_single_value. verbosity='schema' drops the prose (descriptions, usage, limitations, examples) for a much smaller payload that still has everything needed to build a query; the limitations prose in the default 'full' carries the caveats. An unknown dataset returns an error listing the available ones with a 'did you mean'.

Input Schema

NameRequiredDescriptionDefault
topicYesDataset name, e.g. 'act_scores' (the last part of a key from list_datasets or search_datasets). The full key, e.g. 'education/gosa/act_scores', also works and sets main_topic.
verbosityNo'full' (default) or 'schema' (drops the prose; keeps columns, filters and valid values, key_metric, and recommended_query).full
main_topicNoSubject area: 'education' (the default), 'census', or 'immigration'. A dataset's key starts with it.education

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / topic / description
      Previous value: -"Dataset name, e.g. 'act_scores' (the last part of a key from list_datasets or search_datasets)."New value: +"Dataset name, e.g. 'act_scores' (the last part of a key from list_datasets or search_datasets). The full key, e.g. 'education/gosa/act_scores', also works and sets main_topic."
  2. Changed5 schema fields changed
    • addedInput schema / properties / main_topic / description
      Added value: +"Subject area: 'education' (the default), 'census', or 'immigration'. A dataset's key starts with it."
    • addedInput schema / properties / main_topic / enum
      Added value: +[
+  "census",
+  "education",
+  "immigration"
+]
    • addedInput schema / properties / topic / description
      Added value: +"Dataset name, e.g. 'act_scores' (the last part of a key from list_datasets or search_datasets)."
    • changedInput schema / properties / verbosity / description
      Previous value: -"'full' (default) or 'schema' (drops prose; keeps columns/filters/enums/key_metric/recommended_query)."New value: +"'full' (default) or 'schema' (drops the prose; keeps columns, filters and valid values, key_metric, and recommended_query)."
    • addedInput schema / properties / verbosity / enum
      Added value: +[
+  "full",
+  "schema"
+]
  3. First observed

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so credit goes to what the description adds: the error behavior for an unknown dataset ('did you mean' with available ones listed) and the payload-size tradeoff of verbosity='schema' versus the caveat-bearing 'full'. That is meaningful operational context beyond the annotations.

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

Conciseness3/5

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

It is front-loaded with the core purpose, but the body is a single dense paragraph running many unrelated field semantics together with no segmentation, making it hard to scan. Most sentences carry real information, yet the wall-of-text form costs readability for a tool that could list its fields as separate lines.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only, three-parameter lookup with full schema coverage, full annotations, and an output schema, the description covers the gaps that matter: error behavior, verbosity tradeoffs, and the interpretation traps (non_additive, pooled_rates, series_breaks, year_meaning). It stops short of the tool's place in the overall workflow, which is the remaining hole.

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 baseline is 3, but the description goes further on verbosity by spelling out what 'schema' actually drops (descriptions, usage, limitations, examples) and why 'full' matters (the limitations prose carries the caveats). It does not add anything for main_topic beyond the schema's enum explanation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first clause names the resource and scope precisely ('The full schema of one dataset') and then enumerates exactly what is returned: columns, filters with valid values, foreign keys, examples, limitations, null semantics. It clearly positions itself as the schema-discovery step feeding query_dataset/aggregate, but it never contrasts itself with the sibling describe_dimension, so the boundary between the two describe tools is left to inference.

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

Usage Guidelines3/5

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

Usage is only implied: 'everything needed to build a query' and 'the filters the keys query_dataset and aggregate accept' suggest calling this before querying, and the topic param references list_datasets/search_datasets. There is no explicit when-to-use statement, no when-not, and no direct pointer to describe_dimension or get_contract as alternatives.

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

All Georgia Civic Data toolsInspect
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.

Resources