feat: add descriptive error for ACS 1-year population threshold#145
Open
vijaygovindaraja wants to merge 2 commits intouscensusbureau:mainfrom
Open
feat: add descriptive error for ACS 1-year population threshold#145vijaygovindaraja wants to merge 2 commits intouscensusbureau:mainfrom
vijaygovindaraja wants to merge 2 commits intouscensusbureau:mainfrom
Conversation
Add a content-flattener utility that reduces token usage in MCP tool responses by: - Minifying JSON output (removing pretty-print whitespace from JSON.stringify calls that used `null, 2` formatting) - Stripping fields not useful for LLM reasoning (created_at, updated_at, parent_geography_level_id) - Filtering null values from response objects - Supporting result set truncation with count summaries Replace all 3 instances of `JSON.stringify(data, null, 2)` in tool responses with the new `flattenResponse()` helper: - search-data-tables.tool.ts - fetch-dataset-geography.tool.ts - resolve-geography-fips.tool.ts For a typical 100-item geography response, this reduces token usage by ~30-40% by eliminating indentation whitespace and null fields. Fixes uscensusbureau#70 Signed-off-by: V Govindarajan <vijay.govindarajan91@gmail.com>
ACS 1-year estimates are only available for areas with populations of 65,000+. When users query smaller areas, the Census API returns a generic 400 error with no explanation. This is a common source of confusion for data users. Two changes: 1. Update the tool description to proactively warn about the ACS 1-year population threshold, guiding LLM agents to suggest 5-year data for smaller geographies 2. When a 400 error is returned for an ACS 1-year dataset, provide a descriptive error message explaining the population threshold and suggesting ACS 5-year as an alternative This follows the approach discussed by @luke-keller-census and @annav-gov in the issue thread. Fixes uscensusbureau#35 Signed-off-by: V Govindarajan <vijay.govindarajan91@gmail.com>
Author
|
@luke-keller-census checking in on this one — adds descriptive errors for ACS 1-year population thresholds. |
Author
|
@luke-keller-census @curt-mitch-gov would you be able to take a look at this? |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
ACS 1-year estimates are only available for geographic areas with populations of 65,000+. When users query smaller areas, the Census API returns a generic 400 error with no explanation — a common source of confusion.
This PR adds two improvements following the approach discussed by @luke-keller-census and @annav-gov:
1. Proactive guidance in tool description
Added a note to the
fetch-aggregate-datatool description warning about the ACS 1-year population threshold and suggesting 5-year data as an alternative. This helps LLM agents avoid the error entirely.2. Descriptive error message on 400
When a 400 error is returned for an ACS 1-year dataset, the error message now explains:
acs/acs5insteadBefore:
After:
Fixes #35