/** * @fileoverview Tool to compare variables across multiple geographies at the same level. * @module mcp-server/tools/definitions/census-compare-geographies */ import { z } from '@cyanheads/mcp-ts-core'; import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors'; export declare const censusCompareGeographies: import("@cyanheads/mcp-ts-core").ToolDefinition; geography_level: z.ZodString; within: z.ZodOptional, z.ZodString]>>; within_county: z.ZodOptional, z.ZodString]>>; geographies: z.ZodOptional>; predicates: z.ZodOptional>; dataset: z.ZodOptional; year: z.ZodOptional; sort_by: z.ZodOptional; sort_dir: z.ZodOptional>; limit: z.ZodOptional; }, z.core.$strip>, z.ZodObject<{ rows: z.ZodArray; applied_filters: z.ZodOptional>; record: z.ZodOptional>; rank: z.ZodNumber; }, z.core.$strip>>; }, z.core.$strip>, readonly [{ readonly reason: "dataset_not_found"; readonly code: JsonRpcErrorCode.NotFound; readonly when: "Dataset code is not recognized."; readonly recovery: "Call census_list_datasets to discover valid dataset codes like acs/acs5."; }, { readonly reason: "missing_api_key"; readonly code: JsonRpcErrorCode.Unauthorized; readonly when: "CENSUS_API_KEY is not configured or the key is invalid."; readonly thrownBy: "service"; readonly recovery: "Set the CENSUS_API_KEY environment variable and restart the server. Register a free key at api.census.gov/data/key_signup.html."; }, { readonly reason: "geography_not_supported"; readonly code: JsonRpcErrorCode.ValidationError; readonly when: "The requested geography level does not exist in this dataset and year."; readonly recovery: "Call census_list_geographies to see supported geography levels for this dataset and year."; }, { readonly reason: "parent_required"; readonly code: JsonRpcErrorCode.ValidationError; readonly when: "The geography level requires a parent FIPS but within, or within_county, was not provided."; readonly recovery: "Add the within parameter with the state FIPS from census_resolve_geography state_fips. For tract or block-group levels also add within_county from census_resolve_geography county_fips."; }, { readonly reason: "parent_not_accepted"; readonly code: JsonRpcErrorCode.ValidationError; readonly when: "within or within_county names a parent the geography level does not sit within."; readonly recovery: "Drop the parent this level does not name. Levels such as urban area, zip code tabulation area, and metropolitan statistical area/micropolitan statistical area are compared nationally with no scope at all; census_list_geographies shows the parents each level takes."; }, { readonly reason: "year_not_available"; readonly code: JsonRpcErrorCode.ValidationError; readonly when: "The dataset does not serve the requested vintage year."; readonly thrownBy: "service"; readonly recovery: "Retry with a year from available_years in census_list_datasets; the error names the years this dataset serves."; }, { readonly reason: "variable_not_found"; readonly code: JsonRpcErrorCode.NotFound; readonly when: "One or more variable codes are not found in this dataset and year."; readonly thrownBy: "service"; readonly recovery: "Use census_search_variables or census_get_variable to confirm codes for this dataset and year."; }, { readonly reason: "variables_unavailable"; readonly code: JsonRpcErrorCode.ServiceUnavailable; readonly when: "The variable metadata endpoint returned an unparseable response for this dataset and year."; readonly retryable: true; readonly thrownBy: "service"; readonly recovery: "Retry the request; if it persists, the Census metadata endpoint is temporarily unavailable."; }, { readonly reason: "predicate_not_supported"; readonly code: JsonRpcErrorCode.ValidationError; readonly when: "A key in predicates is not a variable in this dataset and year."; readonly recovery: "Remove the unrecognized key. Call census_search_variables on this dataset and year for the codes it does define — predicate names are vintage-specific, so NAICS2017 and NAICS2022 belong to different years."; }, { readonly reason: "ambiguous_rows"; readonly code: JsonRpcErrorCode.ValidationError; readonly when: "The dataset publishes several records per geography and the comparison pinned none of them, so every geography would occupy several ranks with different values."; readonly recovery: "Add the record column named in the error to predicates to pin one record — on pep/charv that is MONTH, where \"7\" selects the July estimate and \"4\" the April estimates base. census_query_data returns every record for a single geography if you need to see them first."; }, { readonly reason: "no_data"; readonly code: JsonRpcErrorCode.NotFound; readonly when: "No geographies were returned for the query, or no row matched any entry in the geographies list."; readonly recovery: "Confirm the level is populated for this dataset and year with census_list_geographies, and that any geographies entries are valid FIPS codes from census_resolve_geography."; }, { readonly reason: "upstream_error"; readonly code: JsonRpcErrorCode.ServiceUnavailable; readonly when: "Census API was unreachable or returned an error."; readonly retryable: true; readonly thrownBy: "service"; readonly recovery: "Retry the request; if the error persists, the Census API may be temporarily unavailable."; }], { readonly totalCount: z.ZodNumber; readonly truncated: z.ZodBoolean; readonly sortVariable: z.ZodString; readonly dataset: z.ZodString; readonly year: z.ZodNumber; readonly notice: z.ZodOptional; }>; //# sourceMappingURL=census-compare-geographies.tool.d.ts.map