census-mcp-server

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds substantial behavior beyond that: suppressed values are decoded to readable labels, unset predicates use Census-chosen defaults with per-row applied_filters, and unpinned multi-record datasets fail with ambiguous_rows rather than returning duplicate ranks. This covers failure modes and default behavior that the agent would otherwise have to discover at runtime.

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?

At around 350 words the description is long, but every sentence carries a distinct piece of guidance: scope, ranking, suppressed values, predicate defaults, ambiguous_rows, and GEOID construction. It is front-loaded with the core purpose and examples before moving to edge cases, which is appropriate for a complex 11-parameter 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?

Given the tool's complexity – 11 parameters, nested predicates, multiple dataset families, and subtle failure modes – the description covers the critical traps (default predicate categories, ambiguous_rows, bare GEOID ambiguity) and points to sibling tools for valid values. The presence of an output schema covers return-shape details, so nothing essential is left for the agent to guess.

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 already has exhaustive descriptions for all 11 parameters (100% coverage), so the baseline is 3. The description nonetheless adds practical value by explaining the ACS margin-of-error convention, the MONTH pinning example for pep/charv, and how to construct GEOIDs from census_resolve_geography fields. It does not restate the schema, and the added examples are directly actionable.

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 ('Compare one or more variables across multiple geographies at the same level'), provides three concrete query examples, and emphasizes sorted/ranked output, which clearly separates it from a plain data retrieval tool. It also states scope behavior ('Omit within to compare all geographies nationally'), making the tool's job unmistakable.

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 contexts: ranking states/counties/tracts, comparing within a state vs nationally, and using named geography sets. It references sibling tools for prerequisites (census_resolve_geography, census_list_predicate_values, census_search_variables), but it does not explicitly say when to prefer census_query_data or when this tool is inappropriate, so exclusions are absent.

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 readOnlyHint=true already signaling safety, the description adds valuable behavioral detail: ACS datasets return estimate_code and moe_code siblings while other dataset families do not, and predicate codes are resolved to confirm filter dimensions. No contradiction with annotations.

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 slightly longer than minimal but each sentence carries distinct value: primary purpose, use cases, dataset-family differences, and routing to a sibling tool. The key purpose is front-loaded in the first sentence.

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 read-only metadata lookup tool with an output schema and full schema coverage, the description covers purpose, use cases, alternatives, and cross-dataset behavioral differences. Nothing essential is missing for an agent to select and invoke it 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 coverage is 100%, so the baseline is 3 and the schema already documents all parameters. The description adds useful examples and output behavior, but does not materially deepen parameter semantics beyond what the schema provides.

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: 'Fetch full metadata for one or more Census variable codes,' and enumerates the returned fields. It also contrasts with census_list_predicate_values, making it easy to distinguish from 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?

It explicitly says when to use the tool: 'Use to confirm a variable code before building a query, or to look up what a known code means.' It also names an alternative for a related case: predicate values should go to census_list_predicate_values.

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?

Annotations already provide readOnlyHint=true and openWorldHint=false, so the description adds context beyond those: it discloses that datasets have supported vintage years and that each entry names required predicates and geography levels, which vary by dataset. This tells the agent what kind of information the tool returns without contradicting the annotations.

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

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

The four-sentence description is efficient: purpose, when-to-use, downstream output consumption, and the nature of each returned entry. The enumeration of dataset types is slightly listy but adds useful context. The core purpose is front-loaded in the first sentence.

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 list tool with one optional parameter, no required parameters, a read-only annotation, and an output schema, the description is complete. It covers what the tool does, when to use it, what the returned entries contain, and how to use the dataset_id afterward. No critical information 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?

There is only one parameter, filter, and the schema already fully describes it ('Keyword to filter datasets by name or description. Omit to list all datasets.'), giving 100% schema coverage. The description adds output-related context (dataset_id reuse) but not additional input semantics, so the baseline 3 applies.

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 'Browse available Census Bureau datasets', a clear verb+resource pair, and explicitly names the dataset families covered (ACS5, ACS1, population estimates, decennial census, business datasets). It frames itself as the discovery/starting point, distinguishing it from sibling list tools like census_list_geographies and census_list_predicate_values.

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 selection condition: 'Use as the starting point when the right dataset is unknown.' It also explains what each dataset description contains (required predicates, geography levels) so an agent can judge fit, and notes that the resulting dataset_id is fed into other census tools. It does not explicitly list exclusions, but the starting-point framing strongly implies when not to use it.

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?

Annotations already declare readOnlyHint=true, so the description need not repeat that. It adds useful context beyond annotations: the output is intended as input for census_query_data and census_compare_geographies, and it warns that not all datasets support all geography levels. This enriches the behavioral profile without contradicting any annotation.

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 sentences with no filler. The main purpose is front-loaded, followed by usage context and a practical note about output reusability. Every sentence earns its place, and the description is well-structured for quick scanning.

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 the tool's simplicity, the presence of an output schema, and annotations covering read-only behavior, the description is complete. It explains when to use it, what it returns (geography levels and required parent geographies), and how to use the result. No critical information 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 100%: both year and dataset have clear descriptions, including the default behavior for year and the pointer to census_list_datasets for valid dataset codes. The tool description does not add any additional parameter-level meaning beyond what the schema already provides, so a baseline 3 is appropriate.

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 ('List') and resource ('geography levels available for a given Census dataset and year'), and immediately clarifies the tool's role as a pre-query validation step. It distinguishes itself from siblings like census_query_data by emphasizing it returns valid inputs for those 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 instructs 'Use before querying to confirm that the target geography level exists' and gives a concrete reason (ACS1 omits sub-state levels). It also notes the returned values are valid inputs to other tools, effectively stating when to use it and how the output connects to follow-up calls.

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?

The annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds substantial behavioral detail: dictionary lists are shared classifications, codes that return no rows are dropped, and the response source field indicates whether that check ran. It also warns that dictionary lists run to thousands of codes and benefit from query narrowing, which goes well beyond the structured annotations.

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: core purpose is front-loaded, then usage context, then behavioral caveats, then practical guidance. No filler or restatement of the title.

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 tool with six parameters, two required, and an output schema, the description covers purpose, when to use it, how to avoid pitfalls, parameter relationships, and post-call behavior. The presence of an output schema means return-value documentation is already handled elsewhere, so nothing essential 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 100%, so the baseline is 3, but the description goes much further. It explains the special behavior of within_naics for TAXSTAT and TYPOP on ecnbasic, gives concrete query examples, notes case-sensitivity for predicate, and explains why dataset and year must align. This adds real operational meaning beyond the raw parameter descriptions.

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: 'List the codes a Census filter dimension accepts'. It also explains the exact use case (writing predicates without guessing) and connects to sibling tools by addressing the gap left when census_query_data or census_compare_geographies reports a dimension unset.

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 says when to use the tool — when a dimension was left unset — and names discovery alternatives: census_list_datasets for datasets and census_search_variables for predicate dimensions. It also explains the vintage-dependent routing between dictionary value lists and live endpoint enumeration, so an agent knows how the tool behaves in each case.

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?

Annotations provide readOnlyHint=true and openWorldHint=false, and the description adds substantial behavior beyond those: suppression codes are decoded into human-readable reasons, omitted predicates are filled with Census defaults and echoed in applied_filters, and pep/charv can return a geography on multiple rows distinguished by a record field. This far exceeds the annotation-only baseline with no contradiction.

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 appropriately dense for a complex tool: it front-loads the core action, then covers preparation, dataset-specific behavior, defaults, and multi-row results without fluff. Each section adds distinct information an agent needs, and the structure moves from general to specific cleanly.

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 the tool's complexity — 8 parameters, multiple dataset families, nested predicates, and an output schema that exists — the description covers all high-risk behaviors: FIPS construction, variable selection, suppression handling, default predicate values, and duplicate rows. The helper tool names fill the remaining gaps, so an agent can invoke this correctly in nearly all cases.

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?

Even though schema coverage is 100% and the input schema is already detailed, the tool description adds significant meaning beyond the schema: FIPS width and padding rules, ACS E/M suffix pairing, how to request stable geography keys via GEO_ID, and the consequences of omitting predicates. This gives an agent the operational judgment needed to construct valid queries.

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 and resource ('Query a Census dataset for one or more variables at a specific geography') and immediately distinguishes this from sibling helpers by routing FIPS conversion to census_resolve_geography. It also adds dataset-specific behavior such as ACS MOE pairing, suppression decoding, and pep/charv duplicate rows, so an agent knows exactly what this 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?

The description explicitly directs agents to sibling tools when preparation is needed: census_resolve_geography for FIPS codes, census_list_geographies for valid levels, census_search_variables for variable codes, and census_list_predicate_values for predicate codes. It lacks a direct 'do not use this when...' statement, but the routing is clear enough to guide correct selection among the siblings.

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?

Beyond the readOnlyHint, the description discloses auto-detection scope (state/county/place/tract only), explicit override behavior, ambiguity errors (ambiguous_name), county_scope_unsupported errors, and Census padding conventions. No contradiction with annotations.

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 three-sentence description front-loads the purpose, uses concrete examples, and packs downstream routing and auto-detection caveats into a compact, high-density text. 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 resolver with an output schema, a read-only annotation, and only one required parameter, the description plus parameter docs cover use cases, disambiguation, error states, and downstream integration. Nothing needed 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?

The input schema already documents all three parameters at 100% coverage, so the baseline is 3. The description adds downstream field mapping (state_fips to parent_fips, fips_summary to geography_fips), but this mostly concerns output values rather than input parameter semantics, so it does not push beyond the schema's substantial parameter descriptions.

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-resource pair: 'Resolve a place name or street address to Census FIPS identifiers.' It provides concrete examples and explicitly ties the output codes to census_query_data and census_compare_geographies, which distinguishes it from all sibling data-retrieval 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?

It directly says 'Use before querying when you have a place name rather than raw FIPS codes,' giving an explicit precondition and routing decision. It also explains how the returned fields map into downstream tools, so an agent knows exactly when this tool is the necessary first step.

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?

Even with readOnlyHint=true, the description adds substantial behavioral detail: ACS returns both E-suffix and M-suffix codes while other dataset families do not, it can locate predicate codes, and it explains how to respond when total_matches exceeds the limit. These are meaningful behaviors not visible from annotations alone.

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 well-organized, front-loads the core purpose, and each sentence contributes either a use case, a dataset nuance, or search guidance. There is no filler or repetition of schema details.

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 the output schema exists and the tool is a straightforward search operation, the description covers everything an agent needs: what to search for, what results look like, dataset-specific behavior, special predicate-code usage, and how to handle overly broad results.

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 100%, so the baseline is 3. The description adds value by clarifying that queries search across labels and concept groups, providing realistic example queries, and explaining dataset-specific output behavior, which enriches the meaning of the query and dataset parameters beyond 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 states a specific verb (search), resource (Census variables), and scope (keyword across variable labels and concept groups). It goes further by explaining the practical transformation from a concept like 'median household income' to a variable code, clearly differentiating it from sibling tools like census_get_variable or census_query_data.

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, actionable context: use this to convert concepts to variable codes, to get both estimates and margins of error on ACS, and to find predicate codes like NAICS2017. It does not explicitly state when not to use it or name alternatives, but the examples strongly imply its niche among the sibling tools.

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