fcc-broadband-mcp-server

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['geography_type'], 'properties': {'sort_by': {'enum': ['unserved_pct', 'unserved_pop', 'coverage_pct', 'competitive_pct'], 'type': 'string', 'default': 'unserved_pct', 'description': '"unserved_pct" = share of population with no broadband (default). "unserved_pop" = raw headcount for BEAD funding. "coverage_pct" = share with any coverage. "competitive_pct" = share with 2+ providers. Every option ranks worst-first, so rank 1 is the highest unserved share or headcount, or the lowest coverage or competitive share.'}, 'speed_down': {'enum': ['4', '10', '25', '100', '250', '1000', '0.2'], 'type': 'string', 'default': '25', 'description': 'Download speed threshold in Mbps. 25 = FCC legacy standard. 100 = BEAD program standard.'}, 'tech_filter': {'enum': ['acfosw', 'f', 'c', 'a', 'o', 's', 'w'], 'type': 'string', 'default': 'acfosw', 'description': 'Technology filter. "acfosw" = any wired or fixed wireless. "f" = fiber only. "c" = cable only. "a" = DSL. "s" = satellite. "w" = fixed wireless.'}, 'geography_ids': {'type': 'array', 'items': {'type': 'string'}, 'maxItems': 50, 'minItems': 2, 'description': 'Array of FIPS GEOIDs to compare (up to 50). For all 50 states, omit and set compare_all_states=true.'}, 'geography_type': {'enum': ['state', 'county', 'cd', 'place', 'cbsa', 'tribal'], 'type': 'string', 'description': 'Geographic level to compare. Must be uniform across all geographies in the comparison.'}, 'compare_all_states': {'type': 'boolean', 'default': False, 'description': 'When true, compares all 50 states + DC. Overrides geography_ids. Requires geography_type="state".'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['geographyType', 'techFilter', 'speedDownMbps', 'sortBy', 'areas', 'totalAreas', 'dataVintage', 'appliedFilters']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'areas': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'rank', 'noCoverage', 'oneProvider', 'twoProviders', 'threeOrMore', 'total', 'unservedPct', 'coveragePct', 'competitivePct'], 'properties': {'id': {'type': 'string', 'description': 'FIPS GEOID.'}, 'name': {'type': 'string', 'description': 'Human-readable geography name if resolved (e.g., "Pontotoc County, MS").'}, 'rank': {'type': 'number', 'description': 'Rank in the sorted comparison (1 = worst/lowest).'}, 'total': {'type': 'number', 'description': 'Total population.'}, 'noCoverage': {'type': 'number', 'description': 'Population with no providers at the given speed.'}, 'coveragePct': {'type': 'number', 'description': 'Percentage with at least one provider.'}, 'oneProvider': {'type': 'number', 'description': 'Population with exactly one provider.'}, 'threeOrMore': {'type': 'number', 'description': 'Population with three or more providers.'}, 'unservedPct': {'type': 'number', 'description': 'Percentage with no coverage.'}, 'twoProviders': {'type': 'number', 'description': 'Population with two providers.'}, 'competitivePct': {'type': 'number', 'description': 'Percentage with two or more providers.'}}, 'description': 'Coverage metrics for one geography in the comparison.', 'additionalProperties': False}, 'description': 'Ranked comparison of geographies by the selected sort field.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['no_data_found', 'invalid_all_states_combo', 'missing_geography_ids', 'invalid_geography_id_shape'], 'description': 'Machine-readable failure mode. Declared by this tool: `no_data_found`: No area table data found for any of the requested geography IDs. `invalid_all_states_combo`: compare_all_states=true used with geography_type other than "state". `missing_geography_ids`: No geography_ids provided and compare_all_states is false. `invalid_geography_id_shape`: A geography_ids entry has a digit count that does not match the geography_type (state=2, county=5, cd=4, cbsa=5, place=7). Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'sortBy': {'type': 'string', 'description': 'Ranking field used.'}, 'techFilter': {'type': 'string', 'description': 'Technology filter applied.'}, 'totalAreas': {'type': 'number', 'description': 'Total number of areas compared.'}, 'dataVintage': {'type': 'string', 'description': 'Data vintage â\x80\x94 Form 477 data as of June 2021.'}, 'geographyType': {'type': 'string', 'description': 'Geography type compared.'}, 'speedDownMbps': {'type': 'number', 'description': 'Speed threshold in Mbps.'}, 'appliedFilters': {'type': 'object', 'required': ['geographyType', 'techFilter', 'speedDownMbps', 'sortBy', 'areasCompared'], 'properties': {'sortBy': {'type': 'string', 'description': 'Field used for ranking.'}, 'techFilter': {'type': 'string', 'description': 'Technology filter applied.'}, 'areasCompared': {'type': 'number', 'description': 'Total number of geographies compared.'}, 'geographyType': {'type': 'string', 'description': 'Geographic level compared.'}, 'speedDownMbps': {'type': 'number', 'description': 'Download speed threshold in Mbps.'}}, 'description': 'Filters and parameters applied to this comparison.', 'additionalProperties': False}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'limit': {'type': 'integer', 'default': 20, 'maximum': 100, 'minimum': 1, 'description': 'Maximum number of areas to return, ranked by unserved population (descending).'}, 'state': {'type': 'string', 'pattern': '^[A-Z]{2}$', 'description': '2-letter USPS state or territory code (e.g., "WY", "MS", "PR") to limit scope. An unrecognized code is rejected, not ignored. Omit for nationwide search â\x80\x94 returns top areas only.'}, 'speed_down': {'enum': ['4', '10', '25', '100', '250', '1000', '0.2'], 'type': 'string', 'default': '25', 'description': 'Download speed threshold in Mbps for defining "underserved." 25 = FCC legacy standard. 100 = BEAD program standard.'}, 'tech_filter': {'enum': ['acfosw', 'f', 'c', 'a', 'o', 's', 'w'], 'type': 'string', 'default': 'acfosw', 'description': 'Technology filter. "acfosw" = any wired or fixed wireless. "f" = fiber only. "c" = cable only.'}, 'geography_type': {'enum': ['county', 'cd', 'place', 'cbsa'], 'type': 'string', 'default': 'county', 'description': 'Geographic granularity for results. "county" is most useful for policy analysis and BEAD eligibility. "cd" = congressional district. "place" = census-designated place. "cbsa" = metro area.'}, 'min_unserved_pop': {'type': 'integer', 'default': 1, 'maximum': 9007199254740991, 'minimum': 0, 'description': 'Minimum population with no coverage to include. Defaults to 1, which keeps fully covered areas out of a ranking of underserved ones. Set to 0 to rank every area regardless of unserved population, or higher to drop small gaps (e.g., 500 keeps only areas with at least 500 unserved residents).'}, 'urban_rural_filter': {'enum': ['all', 'R', 'U'], 'type': 'string', 'default': 'R', 'description': 'Defaults to rural ("R") â\x80\x94 where underservice is most concentrated. Use "U" to find underserved urban areas (digital redlining research). Set to "all" for both.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['areas', 'geographyType', 'speedDownMbps', 'urbanRuralFilter', 'dataVintage', 'totalFound', 'appliedFilters']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'cap': {'type': 'number', 'description': 'The limit that was applied. Present when truncated.'}, 'areas': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'rank', 'noCoverage', 'oneProvider', 'total', 'unservedPct', 'coveragePct'], 'properties': {'id': {'type': 'string', 'description': 'FIPS GEOID of the geography.'}, 'name': {'type': 'string', 'description': 'Human-readable geography name if resolved (e.g., "Pontotoc County, MS").'}, 'rank': {'type': 'number', 'description': 'Rank by unserved population (1 = most unserved).'}, 'total': {'type': 'number', 'description': 'Total population in the geography.'}, 'noCoverage': {'type': 'number', 'description': 'Population with zero providers at the given speed threshold.'}, 'coveragePct': {'type': 'number', 'description': 'Percentage of population with at least one provider.'}, 'oneProvider': {'type': 'number', 'description': 'Population with exactly one provider.'}, 'unservedPct': {'type': 'number', 'description': 'Percentage of population with no coverage.'}}, 'description': 'An underserved area ranked by unserved population.', 'additionalProperties': False}, 'description': 'Ranked list of underserved areas.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['unknown_state'], 'description': 'Machine-readable failure mode. Declared by this tool: `unknown_state`: The state input is two uppercase letters but is not a USPS state or territory abbreviation. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'shown': {'type': 'number', 'description': 'Number of areas returned after applying the limit. Present when truncated.'}, 'notice': {'type': 'string', 'description': 'Guidance about the result set â\x80\x94 how to broaden the filters when nothing matched, and how to narrow the query when the upstream scan hit its row ceiling. Absent when neither applies.'}, 'truncated': {'type': 'boolean', 'description': 'True when more areas matched than the limit returned. Absent when not truncated.'}, 'scanRowCap': {'type': 'number', 'description': 'Raw upstream row ceiling that bound the scan. Present only when scanTruncated is true.'}, 'totalFound': {'type': 'number', 'description': 'Total number of areas found before applying the limit filter.'}, 'dataVintage': {'type': 'string', 'description': 'Data vintage â\x80\x94 Form 477 data as of June 2021.'}, 'geographyType': {'type': 'string', 'description': 'Geography type returned.'}, 'scanTruncated': {'type': 'boolean', 'description': 'True when the upstream row scan stopped at its ceiling before reaching the end of the matching data, so totalFound and the ranking cover only the portion that was scanned. Absent when the scan read every matching row.'}, 'speedDownMbps': {'type': 'number', 'description': 'Speed threshold used in Mbps.'}, 'appliedFilters': {'type': 'object', 'required': ['geographyType', 'speedDownMbps', 'techFilter', 'urbanRuralFilter', 'minUnservedPop'], 'properties': {'state': {'type': 'string', 'description': 'State abbreviation filter applied. Absent for nationwide searches.'}, 'techFilter': {'type': 'string', 'description': 'Technology filter applied.'}, 'geographyType': {'type': 'string', 'description': 'Geographic granularity queried.'}, 'speedDownMbps': {'type': 'number', 'description': 'Download speed threshold in Mbps.'}, 'minUnservedPop': {'type': 'number', 'description': 'Minimum unserved population filter applied.'}, 'urbanRuralFilter': {'type': 'string', 'description': 'Urban/rural filter applied.'}}, 'description': 'Filters applied to this query.', 'additionalProperties': False}, 'urbanRuralFilter': {'type': 'string', 'description': 'Urban/rural filter applied.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['latitude', 'longitude'], 'properties': {'latitude': {'type': 'number', 'maximum': 90, 'minimum': -90, 'description': 'Latitude of the location in decimal degrees (e.g., 47.6062 for Seattle, WA). Must be within the continental US, Alaska, Hawaii, or US territories.'}, 'longitude': {'type': 'number', 'maximum': 180, 'minimum': -180, 'description': 'Longitude of the location in decimal degrees (e.g., -122.3321 for Seattle, WA). Negative for western hemisphere.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['blockFips', 'censusVintage', 'countyFips', 'countyName', 'stateFips', 'stateCode', 'stateName']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['block_not_found'], 'description': 'Machine-readable failure mode. Declared by this tool: `block_not_found`: No census block found at the given coordinates â\x80\x94 may be over water or outside US coverage. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'blockFips': {'type': 'string', 'description': '15-digit census block FIPS code on 2010 census boundaries (e.g., "530330081002024"). Pass this to fcc_search_availability to look up broadband providers.'}, 'stateCode': {'type': 'string', 'description': '2-letter state abbreviation (e.g., "WA").'}, 'stateFips': {'type': 'string', 'description': '2-digit state FIPS code (e.g., "53" for Washington).'}, 'stateName': {'type': 'string', 'description': 'Full state name (e.g., "Washington").'}, 'countyFips': {'type': 'string', 'description': '5-digit county FIPS code (e.g., "53033" for King County, WA).'}, 'countyName': {'type': 'string', 'description': 'Human-readable county name (e.g., "King").'}, 'censusVintage': {'type': 'string', 'description': 'Decennial census whose block boundaries blockFips belongs to. Always "2010" â\x80\x94 the vintage the Form 477 deployment dataset behind fcc_search_availability is keyed by.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['geography_type'], 'properties': {'speed_down': {'enum': ['4', '10', '25', '100', '250', '1000', '0.2'], 'type': 'string', 'default': '25', 'description': 'Minimum download speed threshold in Mbps. 25 = FCC legacy broadband definition. 100 = BEAD program standard (use this for current policy analysis). "0.2" = any service above 200 Kbps.'}, 'tech_filter': {'enum': ['acfosw', 'f', 'c', 'a', 'o', 's', 'w'], 'type': 'string', 'default': 'acfosw', 'description': 'Technology filter. "acfosw" = any wired or fixed wireless (recommended baseline). "f" = fiber only. "c" = cable only. "a" = ADSL/DSL only. "s" = satellite only. "w" = fixed wireless only. Mix letters for combinations, e.g., "fc" = fiber or cable.'}, 'geography_id': {'type': 'string', 'description': 'FIPS GEOID for the geography. State: 2-digit (e.g., "06" for California). County: 5-digit (e.g., "06037" for LA County). Congressional district: 4-digit state+district (e.g., "0601"). CBSA: 5-digit code. Place: 7-digit state+place (e.g., "0644000"). Omit for nation-level queries.'}, 'tribal_filter': {'enum': ['all', 'T', 'N'], 'type': 'string', 'default': 'all', 'description': 'Filter to tribal ("T") or non-tribal ("N") areas. Use "T" to assess Native American connectivity gaps.'}, 'geography_type': {'enum': ['nation', 'state', 'county', 'cd', 'place', 'cbsa', 'tribal'], 'type': 'string', 'description': 'Geographic aggregation level. "nation" = US-wide totals (geography_id not needed). "cd" = congressional district. "place" = census-designated place. "cbsa" = core-based statistical area (metro area). "tribal" = tribal land area.'}, 'urban_rural_filter': {'enum': ['all', 'R', 'U'], 'type': 'string', 'default': 'all', 'description': 'Filter to urban ("U") or rural ("R") areas only, or "all" for both combined. Rural breakdown is key for BEAD program analysis.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['geography', 'techFilter', 'speedDownMbps', 'population', 'coveragePct', 'unservedPct', 'competitivePct', 'breakdown', 'dataVintage', 'appliedFilters']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['geography_not_found', 'invalid_geography_combo', 'invalid_geography_id_shape'], 'description': 'Machine-readable failure mode. Declared by this tool: `geography_not_found`: No area data found for the given geography ID and type. `invalid_geography_combo`: geography_id is omitted for a non-nation type, or geography_type is "nation" but geography_id is provided. `invalid_geography_id_shape`: geography_id digit count does not match the geography_type (state=2, county=5, cd=4, cbsa=5, place=7). Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'breakdown': {'type': 'array', 'items': {'type': 'object', 'required': ['urbanRural', 'tribal', 'population', 'coveragePct', 'unservedPct'], 'properties': {'tribal': {'enum': ['T', 'N'], 'type': 'string', 'description': '"T" = tribal land, "N" = non-tribal.'}, 'population': {'type': 'object', 'required': ['noCoverage', 'oneProvider', 'twoProviders', 'threeOrMore', 'total'], 'properties': {'total': {'type': 'number', 'description': 'Total population in this segment.'}, 'noCoverage': {'type': 'number', 'description': 'Population with no coverage in this segment.'}, 'oneProvider': {'type': 'number', 'description': 'Population with one provider in this segment.'}, 'threeOrMore': {'type': 'number', 'description': 'Population with three or more providers in this segment.'}, 'twoProviders': {'type': 'number', 'description': 'Population with two providers in this segment.'}}, 'description': 'Population breakdown for this urban/rural Ã\x97 tribal segment.', 'additionalProperties': False}, 'urbanRural': {'enum': ['R', 'U'], 'type': 'string', 'description': '"R" = rural, "U" = urban.'}, 'coveragePct': {'type': 'number', 'description': 'Coverage percentage for this segment.'}, 'unservedPct': {'type': 'number', 'description': 'Unserved percentage for this segment.'}}, 'description': 'One urban/rural Ã\x97 tribal/non-tribal segment.', 'additionalProperties': False}, 'description': 'Per-segment breakdown by urban/rural and tribal/non-tribal.'}, 'geography': {'type': 'object', 'required': ['type', 'id'], 'properties': {'id': {'type': 'string', 'description': 'FIPS GEOID (e.g., "06").'}, 'name': {'type': 'string', 'description': 'Human-readable name if available.'}, 'type': {'type': 'string', 'description': 'Geography type (e.g., "state").'}}, 'description': 'The queried geography.', 'additionalProperties': False}, 'population': {'type': 'object', 'required': ['noCoverage', 'oneProvider', 'twoProviders', 'threeOrMore', 'total'], 'properties': {'total': {'type': 'number', 'description': 'Total population in the geography.'}, 'noCoverage': {'type': 'number', 'description': 'Population where zero providers offer service at the given speed.'}, 'oneProvider': {'type': 'number', 'description': 'Population with exactly one provider â\x80\x94 no competitive choice.'}, 'threeOrMore': {'type': 'number', 'description': 'Population with three or more providers.'}, 'twoProviders': {'type': 'number', 'description': 'Population with exactly two providers.'}}, 'description': 'Population counts by provider availability tier.', 'additionalProperties': False}, 'techFilter': {'type': 'string', 'description': 'Technology filter applied.'}, 'coveragePct': {'type': 'number', 'description': 'Percentage of population with at least one provider at the given speed.'}, 'dataVintage': {'type': 'string', 'description': 'Data vintage â\x80\x94 Form 477 data as of June 2021.'}, 'unservedPct': {'type': 'number', 'description': 'Percentage with zero providers â\x80\x94 FCC "unserved" definition.'}, 'speedDownMbps': {'type': 'number', 'description': 'Download speed threshold used in Mbps.'}, 'appliedFilters': {'type': 'object', 'required': ['geographyType', 'techFilter', 'speedDownMbps', 'urbanRuralFilter', 'tribalFilter'], 'properties': {'techFilter': {'type': 'string', 'description': 'Technology filter applied.'}, 'geographyId': {'type': 'string', 'description': 'FIPS GEOID queried. Absent for nation-level.'}, 'tribalFilter': {'type': 'string', 'description': 'Tribal/non-tribal filter applied.'}, 'geographyType': {'type': 'string', 'description': 'Geographic aggregation level queried.'}, 'speedDownMbps': {'type': 'number', 'description': 'Download speed threshold in Mbps.'}, 'urbanRuralFilter': {'type': 'string', 'description': 'Urban/rural filter applied.'}}, 'description': 'Filters applied to this query.', 'additionalProperties': False}, 'competitivePct': {'type': 'number', 'description': 'Percentage with two or more providers.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['hoconum'], 'properties': {'hoconum': {'type': 'string', 'pattern': '^\\d+$', 'description': 'Holding company number from fcc_search_providers â\x80\x94 digits only, e.g. "130317" for Comcast Corporation.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['hoconum', 'holdingCompanyName', 'techCodes', 'techLabels', 'speedTierPopulation', 'dataVintage']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['provider_not_found', 'live_provider_timeout'], 'description': 'Machine-readable failure mode. Declared by this tool: `provider_not_found`: No provider found with the given hoconum. `live_provider_timeout`: A live FCC Open Data lookup exceeded its 30-second budget; the queries are point lookups, so a retry reaches the same result. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'hoconum': {'type': 'string', 'description': 'Holding company number.'}, 'techCodes': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Technology codes this provider reports nationally. Empty when the provider reports no population coverage (e.g. business-only carriers).'}, 'techLabels': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Human-readable technology descriptions.'}, 'dataVintage': {'type': 'string', 'description': 'Data vintage â\x80\x94 Form 477 data as of June 2021.'}, 'holdingCompanyName': {'type': 'string', 'description': 'Holding company name.'}, 'speedTierPopulation': {'type': 'array', 'items': {'type': 'object', 'required': ['tier', 'population'], 'properties': {'tier': {'type': 'string', 'description': 'Download speed threshold (e.g., "25 Mbps").'}, 'population': {'type': 'number', 'description': 'People covered at or above this download speed, counted once each.'}}, 'description': 'A speed tier with its covered population.', 'additionalProperties': False}, 'description': 'National covered population by download speed tier, from the FCC all-technology rollup. Tiers with no coverage are omitted; empty when the provider reports no population coverage.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['as_of_date'], 'properties': {'limit': {'type': 'integer', 'default': 50, 'maximum': 200, 'minimum': 1, 'description': 'Maximum number of files to return on one page.'}, 'state': {'type': 'string', 'pattern': '^[A-Z]{2}$', 'description': 'Filter to one state\'s files (2-letter abbreviation, e.g., "WA").'}, 'offset': {'type': 'integer', 'default': 0, 'maximum': 9007199254740991, 'minimum': 0, 'description': 'Zero-based index of the first file to return, within the files matching the filters. Start at 0 and follow the nextOffset each response carries.'}, 'category': {'enum': ['Summary', 'State', 'Provider'], 'type': 'string', 'description': 'File category. "State" = per-state coverage files. "Provider" = per-provider files. "Summary" = aggregate coverage tables.'}, 'data_type': {'enum': ['availability', 'challenge'], 'type': 'string', 'default': 'availability', 'description': '"availability" = ISP-reported coverage files (by state and provider). "challenge" = consumer and government dispute records.'}, 'as_of_date': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$', 'description': 'BDC as-of date in YYYY-MM-DD format (e.g., "2024-06-30"). Get valid dates from fcc_list_filing_periods with include_bdc=true.'}, 'provider_name': {'type': 'string', 'description': 'Partial provider holding company name to filter results (case-insensitive).'}, 'technology_type': {'enum': ['Fixed Broadband', 'Mobile Broadband', 'Mobile Voice'], 'type': 'string', 'description': 'Filter to a specific technology type of coverage data.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['files', 'totalFiles', 'asOfDate', 'dataType', 'offset', 'pageSize', 'count', 'truncated', 'appliedFilters', 'notice']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'count': {'type': 'number', 'description': 'Files actually returned on this page. Zero both when nothing matched and when the offset is past the end; the notice says which.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['credentials_required', 'invalid_as_of_date'], 'description': 'Machine-readable failure mode. Declared by this tool: `credentials_required`: FCC_BDC_USERNAME or FCC_BDC_HASH_VALUE environment variables are not set. `invalid_as_of_date`: The as_of_date is not a date on the calendar, falls before the first BDC filing period, or is not among the as-of dates the BDC API publishes. The first two are caught without credentials; the third needs them, since only the credentialed endpoint knows the published set. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'files': {'type': 'array', 'items': {'type': 'object', 'required': ['fileId', 'fileName', 'category', 'downloadUrl', 'asOfDate'], 'properties': {'fileId': {'type': 'string', 'description': 'Unique file identifier.'}, 'asOfDate': {'type': 'string', 'description': 'As-of date for this file.'}, 'category': {'type': 'string', 'description': 'File category (e.g., "State", "Provider", "Summary").'}, 'fileName': {'type': 'string', 'description': 'File name.'}, 'stateAbbr': {'type': 'string', 'description': 'State abbreviation for state-level files.'}, 'stateName': {'type': 'string', 'description': 'State name for state-level files.'}, 'downloadUrl': {'type': 'string', 'description': 'Direct download URL for the file.'}, 'recordCount': {'type': 'number', 'description': 'Number of records in the file when available.'}, 'subcategory': {'type': 'string', 'description': 'File subcategory when available.'}, 'providerName': {'type': 'string', 'description': 'Provider name for provider-level files.'}, 'fileSizeBytes': {'type': 'number', 'description': 'File size in bytes when available.'}, 'technologyType': {'type': 'string', 'description': 'Technology type covered (e.g., "Fixed Broadband", "Mobile Broadband").'}}, 'description': 'A downloadable BDC file entry.', 'additionalProperties': False}, 'description': 'Downloadable BDC files on this page, in the order the BDC API lists them.'}, 'notice': {'type': 'string', 'description': 'Where this page sits in the matching set and how to continue â\x80\x94 or, when the page is empty, whether nothing matched the filters or the offset ran past the end.'}, 'offset': {'type': 'number', 'description': 'Zero-based index of the first file on this page.'}, 'asOfDate': {'type': 'string', 'description': 'The queried as-of date.'}, 'dataType': {'type': 'string', 'description': 'Data type queried (availability or challenge).'}, 'pageSize': {'type': 'number', 'description': 'Maximum files one page returns â\x80\x94 the limit that was applied.'}, 'truncated': {'type': 'boolean', 'description': 'True when this page holds fewer files than totalFiles, so more pages exist.'}, 'nextOffset': {'type': 'number', 'description': 'Offset to pass back for the next page. Omitted on the last page and when the offset is past the end.'}, 'totalFiles': {'type': 'number', 'description': 'Files matching the filters across every page, not just this one. Compare against the count enrichment field to see how much of the set this page holds.'}, 'appliedFilters': {'type': 'object', 'required': ['asOfDate', 'dataType'], 'properties': {'state': {'type': 'string', 'description': 'State filter applied. Absent for all-state results.'}, 'asOfDate': {'type': 'string', 'description': 'As-of date queried.'}, 'category': {'type': 'string', 'description': 'Category filter applied. Absent when not filtered.'}, 'dataType': {'type': 'string', 'description': 'Data type queried.'}, 'providerName': {'type': 'string', 'description': 'Provider name filter applied. Absent when not filtered.'}, 'technologyType': {'type': 'string', 'description': 'Technology type filter applied. Absent when not filtered.'}}, 'description': 'Filters applied to this query.', 'additionalProperties': False}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'include_bdc': {'type': 'boolean', 'default': False, 'description': 'When true, also fetches BDC as-of dates from the authenticated API (requires FCC_BDC_USERNAME and FCC_BDC_HASH_VALUE). When false (default), returns only hardcoded Form 477 periods.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['periods', 'form477Count', 'bdcCount', 'hasBdcCredentials', 'dataNote']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'description': 'Machine-readable failure mode.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'periods': {'type': 'array', 'items': {'type': 'object', 'required': ['asOfDate', 'source'], 'properties': {'source': {'enum': ['form477', 'bdc'], 'type': 'string', 'description': '"form477" = legacy ISP-reported data (2015â\x80\x932021). "bdc" = Broadband Data Collection (2022+).'}, 'asOfDate': {'type': 'string', 'description': 'Filing period as-of date in YYYY-MM-DD format (e.g., "2021-06-30").'}, 'publicationDate': {'type': 'string', 'description': 'Date the dataset was published, if available.'}}, 'description': 'A filing period entry.', 'additionalProperties': False}, 'description': 'Available filing periods sorted newest first.'}, 'bdcCount': {'type': 'number', 'description': 'Number of BDC periods returned (0 when credentials not configured or include_bdc=false).'}, 'dataNote': {'type': 'string', 'description': 'Note on data availability and the Form 477 vs. BDC gap.'}, 'form477Count': {'type': 'number', 'description': 'Number of Form 477 periods returned (always available).'}, 'hasBdcCredentials': {'type': 'boolean', 'description': 'Whether BDC API credentials are configured in this deployment.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['block_fips'], 'properties': {'consumer': {'type': 'boolean', 'description': 'Filter to consumer service (true) or business service (false). Omit to return both consumer and business offerings.'}, 'block_fips': {'type': 'string', 'pattern': '^\\d{15}$', 'description': '15-digit census block FIPS code on 2010 census boundaries, the vintage this Form 477 dataset is keyed by (e.g., "530330081002024"). Obtain from fcc_geocode_block using address coordinates â\x80\x94 a 2020-vintage block ID matches no deployment row.'}, 'tech_filter': {'type': 'array', 'items': {'enum': ['0', '10', '11', '12', '20', '30', '40', '41', '42', '43', '50', '60', '70', '90'], 'type': 'string'}, 'description': 'Technology codes to filter, from the complete Form 477 taxonomy: 0=All other, 10=Asymmetric xDSL, 11=ADSL2, 12=VDSL, 20=Symmetric xDSL, 30=Other copper wireline, 40=Cable modem, 41=Cable modem DOCSIS 1/1.1/2.0, 42=Cable modem DOCSIS 3.0, 43=Cable modem DOCSIS 3.1, 50=Fiber to the end user, 60=Satellite, 70=Terrestrial fixed wireless, 90=Electric power line. Omit to return all technologies.'}, 'min_speed_down': {'type': 'number', 'minimum': 0, 'description': 'Minimum advertised download speed in Mbps to include in results. Omit to return all providers regardless of speed.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['blockFips', 'providers', 'totalProviders', 'dataVintage', 'appliedFilters']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['block_not_found'], 'description': 'Machine-readable failure mode. Declared by this tool: `block_not_found`: No providers in the FCC dataset for this census block. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'notice': {'type': 'string', 'description': 'Recovery hint when no providers are found â\x80\x94 suggests how to broaden the query. Absent on successful results.'}, 'blockFips': {'type': 'string', 'description': 'The queried census block FIPS code.'}, 'providers': {'type': 'array', 'items': {'type': 'object', 'required': ['providerId', 'providerName', 'holdingCompanyName', 'hoconum', 'stateAbbr', 'techCode', 'techLabel', 'maxDownloadMbps', 'maxUploadMbps', 'consumer', 'business'], 'properties': {'hoconum': {'type': 'string', 'description': 'Holding company number â\x80\x94 use with fcc_get_provider for a national profile.'}, 'business': {'type': 'boolean', 'description': 'Whether this offering serves businesses.'}, 'consumer': {'type': 'boolean', 'description': 'Whether this offering serves consumers.'}, 'techCode': {'type': 'string', 'description': 'FCC Form 477 technology code (e.g., "50" = fiber, "43" = cable DOCSIS 3.1, "60" = satellite).'}, 'stateAbbr': {'type': 'string', 'description': 'State where coverage is reported.'}, 'techLabel': {'type': 'string', 'description': 'Human-readable technology description.'}, 'providerId': {'type': 'string', 'description': 'FCC provider registration number (FRN).'}, 'providerName': {'type': 'string', 'description': 'Registered provider name.'}, 'maxUploadMbps': {'type': 'number', 'description': 'Maximum advertised upload speed in Mbps.'}, 'maxDownloadMbps': {'type': 'number', 'description': 'Maximum advertised download speed in Mbps.'}, 'holdingCompanyName': {'type': 'string', 'description': 'Parent holding company name (e.g., "Comcast").'}}, 'description': 'One ISP offering at this census block.', 'additionalProperties': False}, 'description': 'ISP offerings reported for this census block.'}, 'dataVintage': {'type': 'string', 'description': 'Data vintage â\x80\x94 all Form 477 data on FCC Open Data is as of June 2021. For newer BDC data, use fcc_list_downloads.'}, 'appliedFilters': {'type': 'object', 'properties': {'techFilter': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Technology codes applied as a filter. Absent when no tech filter was used.'}, 'minSpeedDown': {'type': 'number', 'description': 'Minimum advertised download speed filter in Mbps. Absent when no speed filter was used.'}, 'consumerFilter': {'type': 'boolean', 'description': 'Consumer/business filter applied. true = consumer only, false = business only. Absent when both were returned.'}}, 'description': 'Filters applied to this query.', 'additionalProperties': False}, 'totalProviders': {'type': 'number', 'description': 'Total number of distinct holding companies offering service at this block.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'limit': {'type': 'integer', 'default': 50, 'maximum': 200, 'minimum': 1, 'description': 'Maximum number of distinct providers to return.'}, 'state': {'type': 'string', 'pattern': '^[A-Z]{2}$', 'description': '2-letter state abbreviation (e.g., "WA") to limit results to providers serving that state. Matches individual deployment filings, so every filter given must hold on one filing together â\x80\x94 a provider is returned for state="WA" with tech_filter=["50"] only if it filed fiber in Washington, not if it filed fiber elsewhere and something else in Washington.'}, 'name_search': {'type': 'string', 'description': 'Partial holding company name to search (case-insensitive). e.g., "Comcast", "T-Mobile", "Frontier". Omit to list all providers in a state.'}, 'tech_filter': {'type': 'array', 'items': {'enum': ['0', '10', '11', '12', '20', '30', '40', '41', '42', '43', '50', '60', '70', '90'], 'type': 'string'}, 'description': 'Technology codes to filter, from the complete Form 477 taxonomy: 0=All other, 10=Asymmetric xDSL, 11=ADSL2, 12=VDSL, 20=Symmetric xDSL, 30=Other copper wireline, 40=Cable modem, 41=Cable modem DOCSIS 1/1.1/2.0, 42=Cable modem DOCSIS 3.0, 43=Cable modem DOCSIS 3.1, 50=Fiber to the end user, 60=Satellite, 70=Terrestrial fixed wireless, 90=Electric power line. Omit for all technologies. Matches individual deployment filings like state does, so pairing this with name_search narrows to filings made under the matched name â\x80\x94 a holding company that files some technologies under an acquired brand name can come back empty here while its techCodes list the technology. To ask what one company deploys, search the name alone and read techCodes off the result.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['providers', 'totalFound', 'dataVintage', 'appliedFilters']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'cap': {'type': 'number', 'description': 'The limit that was applied. Present when capped.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['live_search_timeout'], 'description': 'Machine-readable failure mode. Declared by this tool: `live_search_timeout`: A live FCC Open Data provider search exceeded its 30-second budget, on either the bounded windowed read or one of the per-provider footprint lookups; both are shapes that answer in seconds or not at all, so a retry reaches the same result. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'shown': {'type': 'number', 'description': 'Number of providers returned. Present when capped.'}, 'notice': {'type': 'string', 'description': 'Guidance about the result set â\x80\x94 that the list was capped at the limit, that the upstream scan returned a sample rather than every match, and how to broaden the search when nothing matched. Absent when none applies.'}, 'providers': {'type': 'array', 'items': {'type': 'object', 'required': ['hoconum', 'holdingCompanyName', 'statesServed', 'techCodes'], 'properties': {'hoconum': {'type': 'string', 'description': 'Holding company number â\x80\x94 use with fcc_get_provider for a national profile.'}, 'techCodes': {'type': 'array', 'items': {'type': 'string', 'description': 'FCC technology code (e.g., "50" = fiber).'}, 'description': 'Every technology code this holding company deployed nationally â\x80\x94 its complete set, resolved per company. Not narrowed by tech_filter, and complete even when the provider list is a sample. Drawn from block-level deployment filings, so it can exceed the technologies fcc_get_provider reports, which counts only those with reported covered population.'}, 'statesServed': {'type': 'array', 'items': {'type': 'string', 'description': 'State abbreviation (e.g., "WA").'}, 'description': 'Every state, district, and territory this holding company filed deployments in nationally â\x80\x94 its complete footprint, resolved per company. Not narrowed by the state filter, and complete even when the provider list is a sample.'}, 'holdingCompanyName': {'type': 'string', 'description': 'Holding company name as filed on the deployment rows this search matched. One holding company number can carry more than one name in Form 477 â\x80\x94 an acquired brand still filing under the parent number â\x80\x94 and this is the name the matched rows carry, not necessarily every name filed under the number.'}}, 'description': 'A deduplicated ISP holding company entry.', 'additionalProperties': False}, 'description': 'Matching providers, deduplicated by holding company.'}, 'truncated': {'type': 'boolean', 'description': 'True when results were capped at the limit and more providers may exist. Absent when not capped.'}, 'scanRowCap': {'type': 'number', 'description': 'Raw upstream row ceiling that bound the scan. Present only when scanTruncated is true.'}, 'totalCount': {'type': 'number', 'description': 'Distinct providers matching the query, before the limit. Present only when the scan read every matching row â\x80\x94 absent when scanTruncated is true, because the true match count is then unknown.'}, 'totalFound': {'type': 'number', 'description': 'Providers in this response. Not the number matching the query â\x80\x94 that is totalCount, and it is only knowable when the scan read every matching row.'}, 'dataVintage': {'type': 'string', 'description': 'Data vintage â\x80\x94 Form 477 data as of June 2021.'}, 'scanTruncated': {'type': 'boolean', 'description': 'True when the upstream row scan stopped at its ceiling before reaching the end of the matching data, so the providers returned are a sample of the matches rather than the complete set. Bounds which companies came back, not what each one reports â\x80\x94 statesServed and techCodes are resolved per company and stay complete. Absent when the scan read every matching row.'}, 'appliedFilters': {'type': 'object', 'properties': {'state': {'type': 'string', 'description': 'State filter applied. Absent for nationwide searches.'}, 'nameSearch': {'type': 'string', 'description': 'Name fragment searched. Absent when no name search was used.'}, 'techFilter': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Technology code filter applied. Absent when no tech filter was used.'}}, 'description': 'Filters applied to this query.', 'additionalProperties': False}}, 'additionalProperties': False}