Georgia Civic Data

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

With no annotations, the description carries the full burden and does so thoroughly: NULLs are skipped and NULL means SUPPRESSED not zero, aggregation_scope discloses source-published vs recomputed grains, a non_additive block and non_additive_sum advisory are emitted, coverage diagnostics expose suppression, and identifiers are contract-allowlisted (no raw SQL). This is well beyond what the schema conveys.

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?

Front-loads the core purpose before diving into agg/metric/group_by semantics, and every clause is substantive rather than filler. It is dense with stacked parentheticals, so a small readability cost, but no sentence is wasted.

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?

An output schema exists, so return values need not be described, yet the description usefully doubles down on return shape and suppression caveats. For a 14-parameter tool at 0% schema coverage it is nearly complete, with only offset and main_topic left unexplained.

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% across 14 parameters, so the description must compensate, and it largely does: it enumerates valid agg values, explains metric's key_metric default and its count behavior, defines group_by column types, maps filters/year/year_min-year_max/detail to query_dataset, and describes order_by/order plus top-N semantics. offset and main_topic (odd default 'education') are never mentioned, leaving two parameters undocumented.

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 and resource ('Compute a grouped aggregate over one topic') and positions itself as 'the aggregation-first path', which distinguishes it from the row-returning sibling query_dataset. An agent can tell what this does and which path it represents without opening the schema.

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?

Gives real routing guidance: prefer weighted_rate over avg for a rate across multiple places/years, prefer source-published grains, and group_by the column (or use the published total row) instead of summing a non_additive column. It also names the describe_dataset/query_dataset adjacents. It stops short of an explicit 'use this instead of query_dataset when...' exclusion statement.

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

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

No annotations, so the description carries the burden and does reasonably well: it discloses the error behavior for unknown topics, the schema_hash for cache/drift detection, and the full payload shape. It doesn't state read-only nature explicitly, but 'describe' plus the surface contents imply 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?

A single enormous sentence that crams column fields, filters, FKs, examples, usage, limitations, tags, and hash into one clause chain, then continues with more separate terms. It is front-loaded on output contents but poorly structured and hard to skim.

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?

Given an output schema exists it needn't explain return values, yet the description still enumerates every top-level field, so it is thorough. The explanation of key_metric, key_metric_grain_contributor, metric_component, pooled_rates, etc. makes it complete for a schema-discovery tool, though the size/readability tradeoffs slightly hurt.

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 only 33%, so the description must compensate and largely does: it explains verbosity's two modes and when to use each, and documents main_topic defaults and accepted values (education/census/immigration). The topic param's accepted values are only hinted at via the error message, not spelled out, keeping it from a 5.

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?

Clearly states it returns the full schema for a topic and enumerates the contents extensively. It's distinguishable from siblings like get_contract or describe_dimension, but the one-sentence firehose makes the core purpose slightly harder to extract than it should be.

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 says to read filters here before query_dataset and that this is the authoritative filter set, and gives exact conditions for verbosity='schema' vs 'full'. It also names alternatives via the error behavior (did you mean) and main_topic dispatch.

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

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.

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.

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

With no annotations, the description carries the full burden and does disclose real behavior: fmt='yaml' returns the document verbatim as text while fmt='json' returns it parsed, and contracts are gated on approved topics / loaded dimensions. It does not state what happens when the gate fails (error vs empty), whether any permission is required, or whether the output is cached/versioned, which are meaningful gaps for a no-annotation tool.

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 the resource and its primary use, then the fmt semantics and the availability constraint. No filler, though the final constraint sentence is slightly compacted and the fmt/kind semantics are packed into a semicolon clause.

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?

An output schema exists, so return-value structure need not be explained, and the description covers fmt output modes and the kind switch. The remaining gap is the unstated failure mode when a topic is not approved or a dimension is not loaded, plus the unexplained 'main_topic' parameter.

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 and it partially does: it defines the two meaningful values of fmt and both values of kind, including the default behavior. It says nothing about the meaning or format of the required 'name' parameter, nor about 'main_topic' (schema default 'education'), leaving half the parameters undocumented anywhere.

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 names a specific verb ('Return') and a precisely scoped resource ('authoritative ODCS v3.2 data contract') and explicitly disambiguates the two supported targets (kind='topic' vs kind='dimension'). It also frames the value proposition against an alternative approach ('without cloning the repo'), so an agent can tell this is the in-band way to fetch the contract document rather than a dataset/dimension description tool.

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?

It gives a clear motivation ('so you can consume the machine-readable schema without cloning the repo') and one usage boundary ('Only approved topics and loaded dimensions expose a contract'), which implies when the call will fail. However, it never names an alternative sibling (e.g. describe_dimension, get_dimension, describe_dataset) or states when an agent should prefer those over this tool, so routing between near-named siblings is left to inference.

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

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.

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 discharges much of it: read-only sandboxed DuckDB, single SELECT/WITH only, an explicit forbidden-verb list, required read_parquet on curated gold paths, row/byte caps with a `truncated` flag, time limits, NULL-as-suppressed semantics, and self-describing errors. That is unusually rich disclosure. It remains a 3 only because it does not state authentication/authorization requirements or the exact cap thresholds, and no annotations exist to cover that residual gap.

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?

Front-loaded with the purpose and the disambiguating contrast to query_dataset before diving into constraints. Dense and long, but nearly every clause carries operational information; only the parenthetical on district_census_id versus county FIPS is a mild digression from what an agent needs to form the first call.

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?

An output schema exists, so return values need not be explained, and the description still adds the non-obvious result semantics an agent needs: the `truncated` cap flag, NULL-as-suppression, and the format of violation errors. For a tool of this complexity, the definition is complete.

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 the description must compensate, and it does so thoroughly for the dominant `sql` parameter — single-statement restriction, forbidden operators, required read_parquet gold-path form, and join-key guidance. The optional `limit` parameter is never mentioned in the description or schema, leaving that one parameter's semantics and its interaction with the server-side cap undefined.

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 and resource ('cross-dataset / cross-topic analytical SQL query') and immediately distinguishes itself from the sibling query_dataset by naming the case it cannot handle (per-topic filters can't express joins). An agent can tell it apart from query_dataset and aggregate without opening any schema.

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?

Gives explicit sequencing and prerequisites: call link_tables first, paste its read_parquet snippets, and use describe_dimension's link_keys for joins. It names the rejected alternative (querying a file path directly) and directs capped-result cases toward aggregation or tighter WHERE. Explicit when/when-not routing.

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

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.

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

No annotations are provided, but the description carries the burden well: it discloses that entries are deliberately LEAN summaries, details the has_demographic flag semantics ('false = no demographic axis, so there is no all-students demographic row to filter'), and mentions a top-level license object with CC BY 4.0 attribution terms. It does not mention pagination or catalog size limits, so it stops short of full behavioral disclosure.

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?

Purpose is front-loaded and each clause carries information (entry fields, has_demographic meaning, routing to describe_dataset/search_datasets). It is a single dense block rather than scannable bullets, and the field enumeration borders on verbose, but nothing is truly wasted.

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?

With an output schema present, return shape needn't be detailed, yet the description still previews the entry structure. Zero params and no annotations mean little else is required, and the description covers purpose, contents, routing, and licensing terms.

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?

Zero parameters, so the schema carries nothing to explain and the baseline for an empty-parameter tool is 4. The description does not need to compensate for any parameter semantics.

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 (Enumerate) and resource (every approved Georgia dataset/topic plus shared dimensions) and makes its role explicit in the catalog workflow. It is clearly distinguishable from siblings: describe_dataset gives full schema, search_datasets is the named-task alternative.

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 says to call this first to learn what exists, and gives the when-not with a named alternative: 'for a NAMED task ... prefer search_datasets, which returns far fewer bytes.' Both the selection condition and the trade-off are stated, 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.

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

With no annotations, the description carries the full burden and does so richly: zones are "reconstructed from published sources of varying currency," are "NOT an official enrollment determination," and the user must "always confirm with the district." It also discloses negative/edge behavior (coverage_reason, gap, not_available, not_zoned for pre-K) and both warning types (currency_warning, overlap_warning), so an agent can anticipate outputs rather than being surprised.

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 lead sentence is front-loaded and clear, but the body is a single dense paragraph stuffed with parentheticals, and it spends substantial space enumerating return fields (district, provenance, level_status, coverage_status, geojson_url) that an output schema already covers. Informative but heavier than it needs to be.

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?

Given 8 loosely-typed params at 0% schema coverage and a high-complexity multi-modal tool, the description supplies the input contract, the grade vocabulary, the return semantics, the authoritative caveat, and the alternate-mode behavior. Nothing an agent needs 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the description explains every parameter: lat/lon coordinates, address (geocoded by the U.S. Census Geocoder), tract_geoid (2020 census tract, returning every covering zone with population share), grade values (pk, k, 01-12), lang ("es" for Spanish), year, and attendance_rules. It fully compensates for the missing schema documentation.

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 opening sentence names a specific verb+resource ("which Georgia public school attendance zones contain a place") and immediately states the alternate mode ("how attendance zones work in Georgia" with attendance_rules=true). It is unmistakably distinct from the generic dataset siblings (query_dataset, describe_dataset) with no schema inspection needed.

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?

It gives an explicit input contract — "Give exactly one of: lat + lon; an address; a 2020 census tract_geoid; or attendance_rules=true with no place" — and states exactly when the alternate mode applies: "use it when a user asks how zones work or whether a child must attend the zoned school." No ambiguity about selection or required combination.

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

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 delivers: NULL means SUPPRESSED not zero, page sizes (default 100, max 500), the `truncated` flag leading to a bulk_export block, NULL cells sorting last in either direction, and self-describing errors on bad filters. These are exactly the behavioral traits an agent needs and none are in 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.

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

Every sentence carries information and the purpose leads, but the content is packed into one dense paragraph with no separation between invocation rules, return shape, and pagination policy. It is efficient rather than bloated, yet scanning for a single rule is harder than it needs to be.

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, high-complexity query tool with an output schema and no annotations, the description covers filter construction, grain, projection, ordering, NULL handling, pagination limits, and the truncation escape hatch. It even explains the `columns` descriptor and `key_metric` echo, which it did not need to given the output schema.

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 100%, so the baseline is 3, and the description adds genuine meaning on top: the filters dict is a union across a value list and ANDs across keys, and the exact filter keys/enums live in describe_dataset — critical since `filters` is a free-form object with additionalProperties=true. It largely restates the year exclusivity and include_labels tradeoff that the schema already documents.

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 and resource ('Query one topic's gold facts with dimension labels joined in') and pins the return grain (labels on every row), which lets an agent distinguish it from siblings like aggregate and describe_dataset without opening a schema. The scope constraint (one topic) is front-loaded.

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?

Gives real routing guidance: 'see describe_dataset's filters for the exact keys and enum values' and 'do not loop pagination to dump a table' (route to bulk_export instead), plus the year vs year_min/max exclusivity rule. It never contrasts itself with the closest sibling, aggregate, so it stops short of explicit alternative selection.

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

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

With no annotations, the description carries the full burden and does so richly: fuzzy matching and ranking, the `ambiguous` tie flag, that it reads only the small dimension table (no fact scan), the matched_on taxonomy (consolidated_city, typo, city_system, county_system), and the instruction to surface `place_note`. These are non-obvious behaviors an agent could not infer from 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?

Front-loaded with purpose and the why before the behavioral detail. The matched_on examples are dense but each earns its place by disambiguating a real failure mode. It is longer than strictly necessary, with several parenthetical examples that could be trimmed.

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?

An output schema exists, so return fields need not be enumerated, yet the description still pre-empts the key output semantics an agent must act on (ambiguous, matched_on, place_note). Combined with the usage rationale, nothing an agent needs to call this 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 the description must compensate. It fully documents `kind` (district/school/county/demographic with worked examples) and richly illustrates `query` semantics via name/code examples. The `limit` parameter is never mentioned, leaving one of three parameters undocumented in both places.

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+resource ('Resolve a place or demographic NAME or CODE to its stable keys + labels') and immediately names the concrete artifacts it produces (district_code / school_code / county_fips / demographic). It also distinguishes itself from the sibling query_dataset by explaining that a wrong code guess returns an empty page, so an agent can tell why it should call this first.

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?

Clear context for use: converting human names or raw codes into filter keys before querying, with an explicit warning that guessing codes yields empty results. It also flags the kind='county' vs kind='district' distinction. There is no explicit 'when not to use this' or a named alternative for the reverse direction, so it falls short of a 5.

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

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.