Georgia education, Census, and immigration data: query, filter, aggregate, and link datasets.
Compute a grouped aggregate over one topic — the aggregation-first path. agg is one of avg/sum/min/max/count/weighted_rate; metric is a metric column (DEFAULTS to the topic key_metric; ignored for count); group_by is a list of grain columns (year, FK codes like district_code or county_fips, or categoricals — see describe_dataset). weighted_rate computes a true population-weighted SUM(numerator)/SUM(denominator) for a rate key metric (when the contract declares the components) — prefer it over avg for a rate across multiple places/years, since avg means the per-row rates and ignores population. Supports the same filters / year / year_min-year_max / detail as query_dataset, plus order_by+order for top-N (order_by 'value' for the aggregated column; NULL cells sort LAST in either direction). Returns one small row per group with <metric>_<agg> (or row_count) plus coverage diagnostics (input_rows / non-null counts) so suppression is visible; aggregation_scope flags whether rows are source-published at this grain or recomputed from a finer detail (prefer source-published — see the advisory). Aggregates SKIP NULLs and NULL means SUPPRESSED not zero. No raw SQL: all identifiers are contract-allowlisted.
| Name | Required | Description | Default |
|---|---|---|---|
| agg | No | avg | |
| year | No | ||
| limit | No | ||
| order | No | asc | |
| topic | Yes | ||
| detail | No | ||
| metric | No | ||
| offset | No | ||
| filters | No | ||
| group_by | No | ||
| order_by | No | ||
| year_max | No | ||
| year_min | No | ||
| main_topic | No | education |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden — and it is exceptional: it discloses NULL handling ("SKIP NULLs and NULL means SUPPRESSED not zero"), the true population-weighted SUM(numerator)/SUM(denominator) semantics of weighted_rate versus avg's per-row rates, NULL sort placement ("sort LAST in either direction"), and output behaviors like aggregation_scope flagging source-published vs recomputed grains with coverage diagnostics so suppression is visible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose, then moves through agg semantics, shared-parameter cross-reference, output shape, and interpretation warnings. Every sentence earns its place — param semantics, weighted_rate vs avg, NULL behavior, aggregation_scope, and the allowlisting constraint are all non-redundant. The density is justified by 14 params and 0% schema coverage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 14-param tool with no annotations and a bare schema, this is complete: it covers all functional parameters, output structure (even exceeding the requirement since an output schema exists), interpretation of suppression, and the security model ("No raw SQL: all identifiers are contract-allowlisted"). Cross-references to describe_dataset, query_dataset, the advisory, and the contract give the agent precise next steps. Only main_topic and limit/offset are left implicit, which is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description is the sole source of parameter meaning and it compensates thoroughly: it enumerates all agg values, explains weighted_rate's formula, states that metric "DEFAULTS to the topic key_metric; ignored for count", defines group_by grain types with concrete FK examples (district_code, county_fips), and specifies order_by/order usage including 'value' and NULL ordering. Pagination params (limit/offset) are left implicit but are standard.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"Compute a grouped aggregate over one topic — the aggregation-first path" names a specific verb (compute), a resource (grouped aggregate), and a scope (one topic). The "aggregation-first path" phrasing positions it against sibling query_dataset, and the detailed agg/group_by semantics make it clearly distinct from describe_dataset, distinct_values, and query_dataset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives rich routing guidance: "prefer it over `avg` for a rate across multiple places/years", "prefer source-published — see the advisory", and "Supports the same filters/year/year_min-year_max/detail as query_dataset", which cross-references the sibling and reuses its parameter semantics. However, it never states an explicit when-not-to-use rule against query_dataset (e.g., "use query_dataset for raw rows"), so it earns 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full schema for one topic: every column (name/type/role/unit/value range/null-meaning), the exact filters list with enum values (read this before query_dataset — it is the authoritative set of filter keys), the FK→dimension join shape (foreign_keys), example queries, usage, limitations, null semantics, tags, and schema_hash (for cache/drift detection). The top-level key_metric names the single headline column most answers want; each column carries key_metric_grain_contributor (a grain axis the key metric is only comparable within — pin or group by it) and metric_component (numerator/denominator of a rate/average metric). recommended_query gives the safe default query shape (key metric + filters to pin + required single-selects) plus a ranking recipe for top/bottom-N asks; filter_hints lists paired filters; each categorical filter carries has_total / requires_single_value. Pass verbosity='schema' for a much smaller payload that drops the prose (description/usage/limitations/example queries/column descriptions) but keeps every field needed to compose a correct query — use it when you only need the filter keys and enums; prefer the default 'full' before reporting conclusions (the limitations prose carries the caveats). On an unknown topic returns a self-describing error listing available topics + a 'did you mean' hint. main_topic defaults to 'education'; pass 'census' for Census topics.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | ||
| verbosity | No | 'full' (default) or 'schema' (drops prose; keeps columns/filters/enums/key_metric/recommended_query). | full |
| main_topic | No | education |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the behavioral burden. It discloses the precise output contents, the payload difference between verbosity modes, the self-describing error behavior on unknown topics (including topic list and 'did you mean' hints), and the main_topic default behavior. No annotations are present to contradict it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and every sentence earns its place, but it is one long unbroken paragraph that could be hard to scan. It is front-loaded with the core purpose and then layers detail, which is good, but formatting with paragraph breaks would improve readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a tool of this complexity. It covers all parameters, defaults, verbosity modes, error behavior, usage before query_dataset, and important output fields like key_metric, recommended_query, and filter_hints. The output schema exists, but the description still adds interpretive context, making it self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, but the description compensates thoroughly. It explains the 'topic' parameter via the error/topic-list behavior, defines 'verbosity' values with concrete tradeoffs, and specifies 'main_topic' defaults and valid inputs ('education' default, 'census' alternative). This adds substantial meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's job: returning the full schema for one topic, including columns, filters, foreign keys, example queries, and limitations. It is clearly distinguished from siblings like query_dataset by positioning itself as the schema-reading counterpart ('read this before query_dataset') and from list_datasets by focusing on a single topic rather than enumerating datasets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use the tool: read it before query_dataset, use verbosity='schema' when only filter keys/enums are needed, and prefer 'full' before reporting conclusions. It also tells the user to pass 'census' for Census topics, making the selection between default and alternative topics explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Schema for one dimension (districts / schools / counties / demographics): the (possibly composite) primary key, the attribute columns a join attaches, the cross-dataset link_keys (e.g. districts.district_census_id → Census via the crosswalk — a 5-digit school-district code, NOT a county FIPS), and demographics semantics (within a category the values are mutually exclusive; all is the denominator). Read this before writing a link_query join.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It explains what the returned schema contains, including cross-dataset link_keys and semantics constraints, and even warns that the district code is 'NOT a county FIPS.' This is valuable context beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-packed into a single informative block. It front-loads the core purpose ('Schema for one dimension') and then adds necessary detail, examples, and a critical caveat. It is not overly long given the complexity of the domain.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the key concepts needed to understand what will be returned and when to call it, and an output schema exists to fill in structural return details. The warning about the 5-digit code versus county FIPS and the semantics explanation make this complete for an agent preparing a link_query join.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a 'name' parameter with 0% description coverage, so the description must compensate. It implies that 'name' identifies a dimension such as districts, schools, counties, or demographics, but it never explicitly states how to format or supply the value. Some meaning is added, but the parameter guidance remains indirect.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns the schema for a dimension, enumerating the primary key, attribute columns, link_keys, and semantics. It is specific about the resource type, but it does not explicitly differentiate itself from siblings like describe_dataset or get_dimension, relying on context rather than naming them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: 'Read this before writing a link_query join.' This tells the agent when to invoke it, though it does not explicitly state when not to use it or name alternatives such as describe_dataset.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the distinct values of ONE filterable column of a topic — the fast way to learn valid filter values before query_dataset, especially for FREE categoricals and FK codes (district_code/school_code/county_fips/demographic) that carry no enum in describe_dataset (a wrong guess otherwise returns an empty page with no error). column must be a filterable column (see describe_dataset's filters). Optional prefix does a case-insensitive starts-with filter; limit caps results (default 50). Enum-bearing columns return their contract enum directly; others run a capped SELECT DISTINCT over the gold data. truncated flags when the list is capped.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| topic | Yes | ||
| column | Yes | ||
| detail | No | ||
| prefix | No | ||
| main_topic | No | education |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it reveals the two execution paths (enum return vs capped SELECT DISTINCT), explains `truncated` as a cap flag, and notes case-insensitive prefix matching. It does not mention whether the operation is read-only or any error/rate-limit behavior, but 'List' implies a safe read and the behavioral details add meaningful value beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and front-loaded with the purpose and key usage context, followed by parameter behavior and execution details. Every sentence earns its place, though it could be slightly more structured for scanning. Overall it is well-organized and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For the primary workflow of discovering valid filter values before querying, the description is complete: it states prerequisites, parameter constraints, and behavior. The output schema exists, so return values need no explanation. However, the roles of `main_topic` and `detail` remain under-specified, so a fully autonomous agent might still need extra inference for those optional parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clarifies `column` (must be filterable), `prefix` (case-insensitive starts-with), and `limit` (caps results, default 50). However, optional parameters like `topic`, `main_topic`, and `detail` are not explained, leaving gaps for a full understanding of all six parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb+resource statement: 'List the distinct values of ONE filterable column of a topic.' It then differentiates itself from related siblings like query_dataset and describe_dataset by framing itself as 'the fast way to learn valid filter values before query_dataset.' No ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent when to use it: before query_dataset, especially for free-form categoricals and FK codes lacking enums in describe_dataset. It warns that guessing wrongly yields an empty page with no error, and points the agent to describe_dataset's `filters` for column eligibility. This gives strong when/why context and names alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the authoritative ODCS v3.1 data contract for a topic (kind='topic') or a dimension (kind='dimension') so you can consume the machine-readable schema without cloning the repo. fmt='yaml' (default) returns the document verbatim as text; fmt='json' returns it parsed. Only approved topics and loaded dimensions expose a contract.
| Name | Required | Description | Default |
|---|---|---|---|
| fmt | No | yaml | |
| kind | No | topic | |
| name | Yes | ||
| main_topic | No | education |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses the default format, the two output behaviors (yaml verbatim text vs. json parsed), and the access constraint of approved topics and loaded dimensions. It does not explicitly state side effects, but as a read-style retrieval tool this is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no filler. The core purpose is front-loaded, followed by format behavior and the availability constraint. Each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main selection criteria and format behavior, and an output schema exists so return-structure details are not required. However, the main_topic parameter is not explained, and the relationship between name/kind/main_topic is left ambiguous, making the definition incomplete for fully confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains fmt and kind, and implicitly ties name to the topic or dimension, but main_topic is entirely unmentioned. With four parameters, missing one key semantic is a significant gap for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the authoritative ODCS v3.1 data contract for a topic or dimension, which is a specific verb-resource pair. It also distinguishes the tool's purpose from schema-exploration siblings by framing it as a way to consume the machine-readable schema without cloning the repo.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this to get the machine-readable contract for a topic/dimension, and only approved topics/loaded dimensions expose one. It also implies the alternative of cloning the repo. It does not explicitly name sibling tools or state when not to use it, but the intended scenario is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Paginated read of a dimension table — the label lookups (district names, school names, county names, demographic labels). Rows are ordered by the dimension's primary key so paging is stable. Use describe_dimension for the schema and link keys. Small page defaults; truncated + a bulk_export pointer signal when to pull the full table elsewhere.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden—which it meets. Discloses ordering by primary key for stable paging, small page defaults, and the truncated flag with bulk_export pointer. This makes behavior fully predictable for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, then pagination, then alternatives. Extremely efficient with no wasted words. Slightly dense but still well-structured; earns a 4 rather than 5 due to the packed phrasing requiring careful reading.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a paginated read tool with an output schema, the description covers all necessary context: purpose, pagination mechanics, and the bulk-export escape hatch. Nothing an agent needs in order to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It implies pagination via 'Paginated read' and 'Rows are ordered by primary key', but doesn't explicitly explain limit and offset parameters or the default limit value. While it gives a hint of page size defaults, it's not as explicit as needed for full compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Paginated read') and resource ('dimension table'), then clarifies it provides label lookups. Distinguishes itself from siblings like describe_dimension and query_dataset by focusing on read-only label retrieval, so an agent can immediately tell this from the other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes to describe_dimension for schema and link keys, and mentions bulk_export for pulling the full table. This gives clear when-to-use and when-to-use-elsewhere guidance, leaving no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a cross-dataset / cross-topic analytical SQL query that the per-topic query_dataset filters can't express — e.g. join education or Census facts to a dimension (or another dataset) on shared geography. READ-ONLY, SANDBOXED DuckDB: one SELECT (or WITH … SELECT); no DDL/DML/COPY/ATTACH/INSTALL/PRAGMA/SET/CALL; you may only read_parquet() the curated gold paths returned by link_tables (call it first and paste the snippets) — querying a file path directly is rejected. Joins use the keys from describe_dimension's link_keys (districts.district_census_id bridges to Census via the crosswalk — it is a school-district code, not a county FIPS, so a district is not 1:1 with a county). Results are row- and byte-capped and time-limited; truncated flags when capped — add aggregation or a tighter WHERE rather than dumping rows. NULL means suppressed, not zero. On a violation you get a self-describing error naming the offending token/path.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully discloses the tool's behavior: it is READ-ONLY, sandboxed, limited to one SELECT (or WITH...SELECT), prohibits certain SQL commands, restricts file access to curated paths, enforces join keys, caps results, and defines NULL semantics. It also mentions error handling. This is comprehensive and leaves no ambiguity about side effects or constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long and detailed, but every sentence provides essential information about usage, constraints, and semantics. It is structured with dashes and semicolons to separate distinct points, making it scannable. While not terse, the density of critical details justifies the length; no significant redundancy is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all necessary context: the type of query, prerequisites, restrictions, join-key requirements, result limitations, NULL handling, and error behavior. It also mentions the 'truncated' flag, which aligns with the output schema (though the output schema is not shown explicitly). An agent has sufficient information to use the tool correctly and anticipate outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only provides types and defaults for 'sql' and 'limit'. The description adds context by specifying the acceptable SQL form (one SELECT or WITH...SELECT) and mentions result caps, which indirectly clarifies the limit parameter. However, it does not explicitly tie 'limit' to row/byte caps or explain 'sql' beyond the allowed syntax. The description adds moderate value beyond the schema, so it scores slightly above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: running cross-dataset analytical SQL queries that per-topic filters cannot express. It uses the verb 'Run', specifies the resource (analytical SQL), and distinguishes it from per-topic query_dataset filters, making its role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it names the prerequisite (call link_tables first, use only read_parquet on returned paths), restrictions (no direct file paths, no DDL/DML/COPY/ATTACH/INSTALL/PRAGMA/SET/CALL), and behavioral expectations (joins use link_keys, results are capped, NULL means suppressed). This gives an agent clear instructions on when and how to invoke the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the tables link_query can read (curated gold paths only) and the join keys that bridge facts → dimensions → Census geography. Call this BEFORE writing a link_query. Two-tier to stay context-cheap: with NO arguments it returns a LEAN index — every table's name, grain, detail levels, default read_parquet(...) snippet, and join keys (enough to pick tables and write a single-detail join). To get every column and a snippet per detail level for the few tables you actually need, call again with tables=["<name>", ...] (a name from the index, e.g. 'education/gosa/attendance' or 'attendance', or a dimension like 'districts'). Paste the read_parquet(...) snippets verbatim into your SQL — they are exactly what the sandbox accepts.
| Name | Required | Description | Default |
|---|---|---|---|
| tables | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It thoroughly discloses the two-tier behavior, the exact contents of each response level, and even the practical detail that read_parquet snippets must be pasted verbatim because the sandbox accepts them. This is strong behavioral transparency beyond the name and schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Although the description is long, every sentence earns its place by adding operational detail: purpose, call timing, two-tier behavior, parameter examples, and usage instruction. It is front-loaded with the core purpose and structured logically, so the length is justified by the tool's richness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's entire workflow, parameter semantics, output contents at both tiers, and integration with link_query. Since an output schema exists, return values need not be enumerated. The only possible missing detail would be error conditions, but they are not necessary for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully explain the tables parameter. It does: no arguments returns the lean index, supplying tables=['<name>', ...] returns full columns and snippets, and it provides concrete example values like 'education/gosa/attendance', 'attendance', or 'districts'. This fully compensates for the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource ('tables link_query can read'), the scope ('curated gold paths only'), and the output (join keys bridging facts → dimensions → Census geography). It distinguishes itself from sibling tools like list_datasets and link_query by specifying it is the metadata lookup to use with link_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit directive: 'Call this BEFORE writing a link_query.' It further specifies a clear two-tier invocation pattern: first call with no arguments to get the lean index, then call again with tables to get detailed columns. This leaves no ambiguity about when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enumerate every approved Georgia dataset (topic) and the shared dimensions. Each topic entry is a LEAN summary — name/keys, year coverage (year_min/year_max + year_gaps), detail levels + default detail, a has_demographic flag (false = no demographic axis, so there is no all-students demographic row to filter), tags, contract version, and a one-line description — enough to pick a topic; call describe_dataset for its full schema (columns, filters, grain, source, example queries). Each dimension entry carries its primary key, attribute columns, and (for districts) cross-dataset link keys. Call this first to learn what exists — but for a NAMED task (you already know roughly the topic), prefer search_datasets, which returns far fewer bytes than this full catalog.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses substantial output behavior: LEAN summaries, year coverage fields, the has_demographic flag semantics, dimension keys, and the fact that this is a large full catalog. It does not mention pagination or rate limits, but for a read-only enumeration tool the disclosed detail is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place: it front-loads the purpose, details the exact content of each entry, and closes with routing guidance. The structure is organized around what an agent needs to know before invoking the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter discovery tool, the description is remarkably complete: it specifies output contents for both topics and dimensions, explains the meaning of key flags, and gives clear alternative routes. The presence of an output schema reduces the need to explain return values, yet the description still provides useful semantic context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and 100% schema coverage, so the schema already makes it clear no arguments are needed. The description adds value by explaining what the no-argument call returns, which is beyond the empty schema, but there are no parameter semantics to clarify.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Enumerate every approved Georgia dataset (topic) and the shared dimensions.' It clearly distinguishes this catalog-listing tool from siblings by naming search_datasets and describe_dataset as alternatives for different needs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: 'Call this first to learn what exists' and explicitly warns against using it for named tasks, directing the agent to search_datasets instead because it returns fewer bytes. It also routes to describe_dataset for full schema details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query one topic's gold facts with dimension labels joined in (the district/school/county/demographic names come back on every row). filters is a dict of column → value or list-of-values: FK codes (district_code, school_code, county_fips, demographic) and any categorical column — see describe_dataset's filters for the exact keys and enum values. Use year (exact) OR year_min/year_max (range), never both. detail picks the grain (default is the finest available). Returns rows plus a columns descriptor array (type/role/unit/null-meaning, and is_key_metric flagging the headline column) so you interpret values and NULLs correctly — NULL usually means SUPPRESSED, not zero (see null_semantics). The top-level key_metric echoes which column is the answer. Use columns to project a subset, include_labels=false to skip the joined name columns (codes only), and order_by+order for server-side top-N instead of over-fetching. Pages are small (default 100, max 500); when truncated is true a bulk_export block points at the REST CSV/Parquet endpoint and the source path for the full pull — do not loop pagination to dump a table. A bad filter returns a self-describing error listing the valid keys/values.
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | Exact year. Use this OR year_min/max. | |
| limit | No | Page size (default 100, max 500). | |
| order | No | Sort direction for order_by: 'asc' or 'desc'. | asc |
| topic | Yes | Topic name, e.g. 'act_scores'. | |
| detail | No | Grain (e.g. schools/districts/states); default finest. | |
| offset | No | Row offset for paging (>= 0). | |
| columns | No | Project only these output columns (fact columns + joined label columns). Smaller pages / fewer column reads. Omit for all columns. | |
| filters | No | Column → value (or list of values) filters. Keys are FK columns (district_code, school_code, county_fips, demographic) and categorical columns; read describe_dataset's `filters` for the exact keys and enum values FIRST. A value list is a union (OR); multiple keys AND together. A wrong key/value returns a self-describing error listing the valid ones. | |
| order_by | No | Order by one fact column or joined label column (for server-side top-N). Default order is the row grain. NULL (suppressed) cells sort LAST in either direction, so a metric top-N is never polluted by suppressed rows. | |
| year_max | No | Inclusive upper year bound (range). | |
| year_min | No | Inclusive lower year bound (range). | |
| main_topic | No | Main topic: 'education' or 'census'. | education |
| include_labels | No | Join district/school/county/demographic name columns (default true); false = codes only (faster, leaner). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it excels: NULL usually means SUPPRESSED not zero, bad filters return a self-describing error, NULL cells sort last, pages are small with max 500, and truncated responses point to a bulk_export endpoint. It also explains the columns descriptor array and key_metric echo, giving an agent a clear picture of what the call will do and what the response means. There is no contradiction with annotations because no annotations exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place. It opens with the core purpose, then flows through filters, year selection, grain, return shape, projection, sorting, pagination, and error behavior in a logical order. There is no filler, repetition, or vague phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 13-parameter tool with no annotations, this description is remarkably complete. It covers return semantics, null semantics, sorting, pagination limits, bulk export, label joining, and error handling, and it points to describe_dataset for filter vocabulary. The presence of an output schema means it need not restate the full return shape, and the description still goes beyond that requirement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds substantial meaning beyond the schema: filters is a dict of column to value/list-of-values with OR/AND semantics, year vs year_min/year_max are mutually exclusive, detail defaults to finest grain, columns projects a subset, and order_by sorts NULL-suppressed rows last. It also directs the agent to describe_dataset for the exact valid filter keys and enum values, which is exactly the kind of cross-tool semantic glue the schema cannot provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair: 'Query one topic's gold facts with dimension labels joined in.' It clearly distinguishes the tool's read/query role from siblings like aggregate, describe_dataset, and distinct_values, and states what comes back on each row. This is far above a tautology and gives an agent an accurate mental model immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives strong in-tool usage rules: use year OR year_min/year_max never both, use order_by+order for server-side top-N, set include_labels=false for leaner pulls, and prefer bulk_export over pagination when truncated. It references describe_dataset for valid filter keys. It does not explicitly say 'use aggregate instead when you need aggregations' or otherwise compare against sibling tools, so it stops just short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a place or demographic NAME or CODE to its stable keys + labels — the right way to turn 'Atlanta Public Schools' / 'Fulton' / a raw code into the district_code / school_code / county_fips / demographic to filter by (a wrong code guess otherwise returns an empty query_dataset page). kind is district / school / county / demographic ('Fulton' as kind='county' → the county; as kind='district' → the school district — they are different things). Fuzzy-matches and ranks candidates, flags ambiguous when several tie, and reads only the small dimension table (no fact scan).
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| limit | No | ||
| query | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses fuzzy matching, candidate ranking, ambiguity flagging when ties occur, and read-only access to a small dimension table with no fact scan. This gives the agent a strong safety and behavior profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences deliver purpose, kind disambiguation, and behavior with no filler. The examples and parentheticals add meaning rather than clutter, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with an output schema and no annotations, this description is nearly complete. The only notable gaps are that limit semantics and no-match behavior are not addressed, but the schema default covers limit and the overall guidance is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the kind parameter's allowed values with a concrete 'Fulton' example and defines query as a name or code. The limit parameter is not described, though its default value is visible in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: resolving place/demographic names or codes into stable keys and labels. It clearly distinguishes from siblings by warning that a wrong code guess would otherwise return an empty query_dataset page, and notes this reads only the dimension table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly frames this as 'the right way' to convert names/codes into filter keys before querying, and warns about the empty-result failure mode of guessing codes. It does not enumerate when to prefer siblings like describe_dimension or distinct_values, but the context is clear enough for an agent to select it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Keyword search over the catalog metadata (topic names, descriptions, tags, AND column names/descriptions) — the discovery entry point when you don't know the exact topic name. Returns lean topic summaries per hit with a relevance score and which fields matched, plus a dimension_matches list when the query also hits a dimension (e.g. 'district'). Most acronyms work; the short ones ap/el/ib are recognized. Follow up with describe_dataset. limit caps results (default 20, max 100).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it delivers: discloses return structure (lean summaries, relevance score, matched fields, dimension_matches list), acronym matching behavior, which short acronyms are recognized, and the result-limiting behavior. This is rich behavioral context beyond what schema or annotations would show.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense paragraph with zero filler: purpose is front-loaded, followed by return details, acronym edge behavior, next-step guidance, and limit semantics. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool that already has an output schema, the description covers the discovery context, when to use it, what to do next, return details, acronym edge cases, and limit behavior. Nothing needed for correct invocation or interpretation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the parameters. It does: 'query' is defined as keyword search across catalog metadata with a dimension example, and 'limit' is explicitly described as capping results with default 20 and max 100. This adds meaning far beyond the bare schema names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('search'), resource ('catalog metadata'), and explicitly lists the fields searched (topic names, descriptions, tags, AND column names/descriptions). Positions itself as 'the discovery entry point when you don't know the exact topic name,' which clearly distinguishes it from describe_dataset and other siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear condition for use ('when you don't know the exact topic name') and a follow-up instruction ('Follow up with describe_dataset'). While it doesn't explicitly name an alternative or say 'don't use this when you know the exact name,' the guidance implies it strongly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
aggregatedescribe_datasetdescribe_dimensiondistinct_valuesget_contractget_dimensionlink_querylink_tableslist_datasetsquery_datasetresolve_entitysearch_datasetsClaiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
School enrollment, graduation rates, demographics, finance, and Title I data
Query US Census Bureau data: demographics, economics, and housing statistics.
Read-only public data on Georgia's prisons: population, facilities, deaths, contraband, statutes.
K-12 school district data for all 50 US states. Enrollment, demographics, and academics.
Add one secure layer between your agents and this server.
Each tool maps to a distinct capability: discovery, schema, values, entity resolution, row query, aggregation, cross-dataset joins, and dimension reads. Even the pairs that sound closest (list_datasets vs search_datasets, describe_dataset vs get_contract) are explicitly differentiated by behavior and use case.
Names are uniformly lowercase snake_case and mostly follow a clear verb_noun pattern (describe_dataset, query_dataset, resolve_entity, link_tables). Only aggregate (bare verb) and distinct_values (noun phrase without a verb) deviate slightly from that pattern.
Twelve tools is a well-scoped size for a data-access MCP server. Each tool adds a non-redundant capability, supporting the full workflow from discovery and schema inspection to querying, aggregation, and cross-dataset joins.
The surface covers the complete read-only lifecycle: catalog discovery, schema/dimension inspection, value and entity lookup, row-level queries, grouped aggregation, cross-dataset analysis, and dimension table reads. Bulk data access is handled via pointers in query results rather than a dedicated tool, which is a deliberate non-gap for this query-focused server.
