fcc-broadband-mcp-server

Converts a latitude/longitude coordinate to a 15-digit census block FIPS code, plus county FIPS, county name, state FIPS, state code, and state name. This is the required prerequisite for fcc_search_availability since the broadband dataset is indexed by census block, not address. The block is resolved against 2010 census boundaries, the vintage the Form 477 deployment dataset is keyed by, so the returned blockFips can be passed straight to fcc_search_availability; a 2020-vintage block ID from another source will not match. Uses the FCC public Geo API — no authentication required.

{
  "type": "object",
  "properties": {
    "latitude": {
      "type": "number",
      "minimum": -90,
      "maximum": 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",
      "minimum": -180,
      "maximum": 180,
      "description": "Longitude of the location in decimal degrees (e.g., -122.3321 for Seattle, WA). Negative for western hemisphere."
    }
  },
  "required": [
    "latitude",
    "longitude"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

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

Queries broadband providers and advertised speeds at a census block from FCC Form 477 data (as of June 2021). Answers "which ISPs serve this location and what speeds do they offer?" — the core tool for address-level broadband lookup. Requires a 15-digit census block FIPS code; use fcc_geocode_block to convert coordinates first. Data reflects ISP-reported availability at the block level, which may overstate actual coverage for some addresses.

{
  "type": "object",
  "properties": {
    "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 — a 2020-vintage block ID matches no deployment row."
    },
    "tech_filter": {
      "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.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "0",
          "10",
          "11",
          "12",
          "20",
          "30",
          "40",
          "41",
          "42",
          "43",
          "50",
          "60",
          "70",
          "90"
        ]
      }
    },
    "min_speed_down": {
      "description": "Minimum advertised download speed in Mbps to include in results. Omit to return all providers regardless of speed.",
      "type": "number",
      "minimum": 0
    },
    "consumer": {
      "description": "Filter to consumer service (true) or business service (false). Omit to return both consumer and business offerings.",
      "type": "boolean"
    }
  },
  "required": [
    "block_fips"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

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

Returns a broadband coverage summary for a geography — population with zero, one, two, or three-plus providers at a given speed threshold, split by urban/rural and tribal/non-tribal segments. The primary tool for digital divide and equity analysis. Supports state, county, congressional district, census place, CBSA (metro area), tribal area, and national level. Data is from FCC Form 477 (as of June 2021). Use 100 Mbps as the speed threshold for BEAD program policy analysis.

{
  "type": "object",
  "properties": {
    "geography_type": {
      "type": "string",
      "enum": [
        "nation",
        "state",
        "county",
        "cd",
        "place",
        "cbsa",
        "tribal"
      ],
      "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."
    },
    "geography_id": {
      "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.",
      "type": "string"
    },
    "tech_filter": {
      "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.",
      "type": "string",
      "enum": [
        "acfosw",
        "f",
        "c",
        "a",
        "o",
        "s",
        "w"
      ]
    },
    "speed_down": {
      "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.",
      "type": "string",
      "enum": [
        "4",
        "10",
        "25",
        "100",
        "250",
        "1000",
        "0.2"
      ]
    },
    "urban_rural_filter": {
      "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.",
      "type": "string",
      "enum": [
        "all",
        "R",
        "U"
      ]
    },
    "tribal_filter": {
      "default": "all",
      "description": "Filter to tribal (\"T\") or non-tribal (\"N\") areas. Use \"T\" to assess Native American connectivity gaps.",
      "type": "string",
      "enum": [
        "all",
        "T",
        "N"
      ]
    }
  },
  "required": [
    "geography_type"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "geography": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Geography type (e.g., \"state\")."
        },
        "id": {
          "type": "string",
          "description": "FIPS GEOID (e.g., \"06\")."
        },
        "name": {
          "description": "Human-readable name if available.",
          "type": "string"
        }
      },
      "required": [
        "type",
        "id"
      ],
      "additionalProperties": false,
      "description": "The queried geography."
    },
    "techFilter": {
      "type": "string",
      "description": "Technology filter applied."
    },
    "speedDownMbps": {
      "type": "number",
      "description": "Download speed threshold used in Mbps."
    },
    "population": {
      "type": "object",
      "properties": {
        "noCoverage": {
          "type": "number",
          "description": "Population where zero providers offer service at the given speed."
        },
        "oneProvider": {
          "type": "number",
          "description": "Population with exactly one provider — no competitive choice."
        },
        "twoProviders": {
          "type": "number",
          "description": "Population with exactly two providers."
        },
        "threeOrMore": {
          "type": "number",
          "description": "Population with three or more providers."
        },
        "total": {
          "type": "number",
          "description": "Total population in the geography."
        }
      },
      "required": [
        "noCoverage",
        "oneProvider",
        "twoProviders",
        "threeOrMore",
        "total"
      ],
      "additionalProperties": false,
      "description": "Population counts by provider availability tier."
    },
    "coveragePct": {
      "type": "number",
      "description": "Percentage of population with at least one provider at the given speed."
    },
    "unservedPct": {
      "type": "number",
      "description": "Percentage with zero providers — FCC \"unserved\" definition."
    },
    "competitivePct": {
      "type": "number",
      "description": "Percentage with two or more providers."
    },
    "breakdown": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "urbanRural": {
            "type": "string",
            "enum": [
              "R",
              "U"
            ],
            "description": "\"R\" = rural, \"U\" = urban."
          },
          "tribal": {
            "type": "string",
            "enum": [
              "T",
              "N"
            ],
            "description": "\"T\" = tribal land, \"N\" = non-tribal."
          },
          "population": {
            "type": "object",
            "properties": {
              "noCoverage": {
                "type": "number",
                "description": "Population with no coverage in this segment."
              },
              "oneProvider": {
                "type": "number",
                "description": "Population with one provider in this segment."
              },
              "twoProviders": {
                "type": "number",
                "description": "Population with two providers in this segment."
              },
              "threeOrMore": {
                "type": "number",
                "description": "Population with three or more providers in this segment."
              },
              "total": {
                "type": "number",
                "description": "Total population in this segment."
              }
            },
            "required": [
              "noCoverage",
              "oneProvider",
              "twoProviders",
              "threeOrMore",
              "total"
            ],
            "additionalProperties": false,
            "description": "Population breakdown for this urban/rural × tribal segment."
          },
          "coveragePct": {
            "type": "number",
            "description": "Coverage percentage for this segment."
          },
          "unservedPct": {
            "type": "number",
            "description": "Unserved percentage for this segment."
          }
        },
        "required": [
          "urbanRural",
          "tribal",
          "population",
          "coveragePct",
          "unservedPct"
        ],
        "additionalProperties": false,
        "description": "One urban/rural × tribal/non-tribal segment."
      },
      "description": "Per-segment breakdown by urban/rural and tribal/non-tribal."
    },
    "dataVintage": {
      "type": "string",
      "description": "Data vintage — Form 477 data as of June 2021."
    },
    "appliedFilters": {
      "type": "object",
      "properties": {
        "geographyType": {
          "type": "string",
          "description": "Geographic aggregation level queried."
        },
        "geographyId": {
          "description": "FIPS GEOID queried. Absent for nation-level.",
          "type": "string"
        },
        "techFilter": {
          "type": "string",
          "description": "Technology filter applied."
        },
        "speedDownMbps": {
          "type": "number",
          "description": "Download speed threshold in Mbps."
        },
        "urbanRuralFilter": {
          "type": "string",
          "description": "Urban/rural filter applied."
        },
        "tribalFilter": {
          "type": "string",
          "description": "Tribal/non-tribal filter applied."
        }
      },
      "required": [
        "geographyType",
        "techFilter",
        "speedDownMbps",
        "urbanRuralFilter",
        "tribalFilter"
      ],
      "additionalProperties": false,
      "description": "Filters applied to this query."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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.",
              "examples": [
                "geography_not_found",
                "invalid_geography_combo",
                "invalid_geography_id_shape"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "geography",
        "techFilter",
        "speedDownMbps",
        "population",
        "coveragePct",
        "unservedPct",
        "competitivePct",
        "breakdown",
        "dataVintage",
        "appliedFilters"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Searches for ISPs by holding company name, filtered by state and technology type. Returns a deduplicated list of matching providers with hoconum identifiers for follow-up calls to fcc_get_provider. Answers "which ISPs serve Washington with fiber?" and "find all Comcast entities." Geographic filtering is state-level; sub-state granularity requires cross-referencing block data. Against the live FCC API the search reads a bounded window of deployment rows to find which holding companies match, so when scanTruncated comes back true the providers are a sample of the matches rather than every one of them and no true match count is available; a narrower filter raises the share of matches the sample surfaces but cannot make it complete, and only a deployment running the local Form 477 mirror returns every match. The sample is of which companies come back — every company that does carries its complete national footprint, since statesServed and techCodes are resolved per company rather than read off the window, at the cost of one lookup per provider returned. Data is from FCC Form 477 (as of June 2021).

{
  "type": "object",
  "properties": {
    "name_search": {
      "description": "Partial holding company name to search (case-insensitive). e.g., \"Comcast\", \"T-Mobile\", \"Frontier\". Omit to list all providers in a state.",
      "type": "string"
    },
    "state": {
      "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 — 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.",
      "type": "string",
      "pattern": "^[A-Z]{2}$"
    },
    "tech_filter": {
      "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 — 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.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "0",
          "10",
          "11",
          "12",
          "20",
          "30",
          "40",
          "41",
          "42",
          "43",
          "50",
          "60",
          "70",
          "90"
        ]
      }
    },
    "limit": {
      "default": 50,
      "description": "Maximum number of distinct providers to return.",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "providers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "hoconum": {
            "type": "string",
            "description": "Holding company number — use with fcc_get_provider for a national profile."
          },
          "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 — an acquired brand still filing under the parent number — and this is the name the matched rows carry, not necessarily every name filed under the number."
          },
          "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 — its complete footprint, resolved per company. Not narrowed by the state filter, and complete even when the provider list is a sample."
          },
          "techCodes": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "FCC technology code (e.g., \"50\" = fiber)."
            },
            "description": "Every technology code this holding company deployed nationally — 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."
          }
        },
        "required": [
          "hoconum",
          "holdingCompanyName",
          "statesServed",
          "techCodes"
        ],
        "additionalProperties": false,
        "description": "A deduplicated ISP holding company entry."
      },
      "description": "Matching providers, deduplicated by holding company."
    },
    "totalFound": {
      "type": "number",
      "description": "Providers in this response. Not the number matching the query — that is totalCount, and it is only knowable when the scan read every matching row."
    },
    "dataVintage": {
      "type": "string",
      "description": "Data vintage — Form 477 data as of June 2021."
    },
    "totalCount": {
      "description": "Distinct providers matching the query, before the limit. Present only when the scan read every matching row — absent when scanTruncated is true, because the true match count is then unknown.",
      "type": "number"
    },
    "truncated": {
      "description": "True when results were capped at the limit and more providers may exist. Absent when not capped.",
      "type": "boolean"
    },
    "shown": {
      "description": "Number of providers returned. Present when capped.",
      "type": "number"
    },
    "cap": {
      "description": "The limit that was applied. Present when capped.",
      "type": "number"
    },
    "scanTruncated": {
      "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 — statesServed and techCodes are resolved per company and stay complete. Absent when the scan read every matching row.",
      "type": "boolean"
    },
    "scanRowCap": {
      "description": "Raw upstream row ceiling that bound the scan. Present only when scanTruncated is true.",
      "type": "number"
    },
    "appliedFilters": {
      "type": "object",
      "properties": {
        "nameSearch": {
          "description": "Name fragment searched. Absent when no name search was used.",
          "type": "string"
        },
        "state": {
          "description": "State filter applied. Absent for nationwide searches.",
          "type": "string"
        },
        "techFilter": {
          "description": "Technology code filter applied. Absent when no tech filter was used.",
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": false,
      "description": "Filters applied to this query."
    },
    "notice": {
      "description": "Guidance about the result set — 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.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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.",
              "examples": [
                "live_search_timeout"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "providers",
        "totalFound",
        "dataVintage",
        "appliedFilters"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Returns a national-level coverage profile for a specific holding company (by hoconum): technologies deployed and the population covered at each download speed tier. Population figures come from the FCC provider summary table and count each person once, regardless of how many technologies the provider uses to reach them. Use fcc_search_providers to find valid hoconum values. Data is from FCC Form 477 (as of June 2021).

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

{
  "type": "object",
  "properties": {
    "hoconum": {
      "type": "string",
      "description": "Holding company number."
    },
    "holdingCompanyName": {
      "type": "string",
      "description": "Holding company name."
    },
    "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."
    },
    "speedTierPopulation": {
      "type": "array",
      "items": {
        "type": "object",
        "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."
          }
        },
        "required": [
          "tier",
          "population"
        ],
        "additionalProperties": false,
        "description": "A speed tier with its covered population."
      },
      "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."
    },
    "dataVintage": {
      "type": "string",
      "description": "Data vintage — Form 477 data as of June 2021."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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.",
              "examples": [
                "provider_not_found",
                "live_provider_timeout"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "hoconum",
        "holdingCompanyName",
        "techCodes",
        "techLabels",
        "speedTierPopulation",
        "dataVintage"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Compares broadband coverage metrics across multiple geographies of the same type and returns a ranked table sorted by unserved or underserved population. Answers "which counties in this state have the worst broadband access?" and drives BEAD funding prioritization. Provide up to 50 geography IDs, or set compare_all_states=true for all 50 states + DC. Data is from FCC Form 477 (as of June 2021).

{
  "type": "object",
  "properties": {
    "geography_type": {
      "type": "string",
      "enum": [
        "state",
        "county",
        "cd",
        "place",
        "cbsa",
        "tribal"
      ],
      "description": "Geographic level to compare. Must be uniform across all geographies in the comparison."
    },
    "geography_ids": {
      "description": "Array of FIPS GEOIDs to compare (up to 50). For all 50 states, omit and set compare_all_states=true.",
      "minItems": 2,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "compare_all_states": {
      "default": false,
      "description": "When true, compares all 50 states + DC. Overrides geography_ids. Requires geography_type=\"state\".",
      "type": "boolean"
    },
    "tech_filter": {
      "default": "acfosw",
      "description": "Technology filter. \"acfosw\" = any wired or fixed wireless. \"f\" = fiber only. \"c\" = cable only. \"a\" = DSL. \"s\" = satellite. \"w\" = fixed wireless.",
      "type": "string",
      "enum": [
        "acfosw",
        "f",
        "c",
        "a",
        "o",
        "s",
        "w"
      ]
    },
    "speed_down": {
      "default": "25",
      "description": "Download speed threshold in Mbps. 25 = FCC legacy standard. 100 = BEAD program standard.",
      "type": "string",
      "enum": [
        "4",
        "10",
        "25",
        "100",
        "250",
        "1000",
        "0.2"
      ]
    },
    "sort_by": {
      "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.",
      "type": "string",
      "enum": [
        "unserved_pct",
        "unserved_pop",
        "coverage_pct",
        "competitive_pct"
      ]
    }
  },
  "required": [
    "geography_type"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "geographyType": {
      "type": "string",
      "description": "Geography type compared."
    },
    "techFilter": {
      "type": "string",
      "description": "Technology filter applied."
    },
    "speedDownMbps": {
      "type": "number",
      "description": "Speed threshold in Mbps."
    },
    "sortBy": {
      "type": "string",
      "description": "Ranking field used."
    },
    "areas": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "FIPS GEOID."
          },
          "name": {
            "description": "Human-readable geography name if resolved (e.g., \"Pontotoc County, MS\").",
            "type": "string"
          },
          "rank": {
            "type": "number",
            "description": "Rank in the sorted comparison (1 = worst/lowest)."
          },
          "noCoverage": {
            "type": "number",
            "description": "Population with no providers at the given speed."
          },
          "oneProvider": {
            "type": "number",
            "description": "Population with exactly one provider."
          },
          "twoProviders": {
            "type": "number",
            "description": "Population with two providers."
          },
          "threeOrMore": {
            "type": "number",
            "description": "Population with three or more providers."
          },
          "total": {
            "type": "number",
            "description": "Total population."
          },
          "unservedPct": {
            "type": "number",
            "description": "Percentage with no coverage."
          },
          "coveragePct": {
            "type": "number",
            "description": "Percentage with at least one provider."
          },
          "competitivePct": {
            "type": "number",
            "description": "Percentage with two or more providers."
          }
        },
        "required": [
          "id",
          "rank",
          "noCoverage",
          "oneProvider",
          "twoProviders",
          "threeOrMore",
          "total",
          "unservedPct",
          "coveragePct",
          "competitivePct"
        ],
        "additionalProperties": false,
        "description": "Coverage metrics for one geography in the comparison."
      },
      "description": "Ranked comparison of geographies by the selected sort field."
    },
    "totalAreas": {
      "type": "number",
      "description": "Total number of areas compared."
    },
    "dataVintage": {
      "type": "string",
      "description": "Data vintage — Form 477 data as of June 2021."
    },
    "appliedFilters": {
      "type": "object",
      "properties": {
        "geographyType": {
          "type": "string",
          "description": "Geographic level compared."
        },
        "techFilter": {
          "type": "string",
          "description": "Technology filter applied."
        },
        "speedDownMbps": {
          "type": "number",
          "description": "Download speed threshold in Mbps."
        },
        "sortBy": {
          "type": "string",
          "description": "Field used for ranking."
        },
        "areasCompared": {
          "type": "number",
          "description": "Total number of geographies compared."
        }
      },
      "required": [
        "geographyType",
        "techFilter",
        "speedDownMbps",
        "sortBy",
        "areasCompared"
      ],
      "additionalProperties": false,
      "description": "Filters and parameters applied to this comparison."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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.",
              "examples": [
                "no_data_found",
                "invalid_all_states_combo",
                "missing_geography_ids",
                "invalid_geography_id_shape"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "geographyType",
        "techFilter",
        "speedDownMbps",
        "sortBy",
        "areas",
        "totalAreas",
        "dataVintage",
        "appliedFilters"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Finds geographic areas with limited or no broadband coverage at a given speed threshold, ranked by unserved population. The core tool for BEAD program analysis and broadband equity research. Accepts a state abbreviation to narrow scope or runs nationwide. Defaults to rural areas where underservice is most concentrated. Data is from FCC Form 477 (as of June 2021).

{
  "type": "object",
  "properties": {
    "state": {
      "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 — returns top areas only.",
      "type": "string",
      "pattern": "^[A-Z]{2}$"
    },
    "geography_type": {
      "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.",
      "type": "string",
      "enum": [
        "county",
        "cd",
        "place",
        "cbsa"
      ]
    },
    "speed_down": {
      "default": "25",
      "description": "Download speed threshold in Mbps for defining \"underserved.\" 25 = FCC legacy standard. 100 = BEAD program standard.",
      "type": "string",
      "enum": [
        "4",
        "10",
        "25",
        "100",
        "250",
        "1000",
        "0.2"
      ]
    },
    "tech_filter": {
      "default": "acfosw",
      "description": "Technology filter. \"acfosw\" = any wired or fixed wireless. \"f\" = fiber only. \"c\" = cable only.",
      "type": "string",
      "enum": [
        "acfosw",
        "f",
        "c",
        "a",
        "o",
        "s",
        "w"
      ]
    },
    "min_unserved_pop": {
      "default": 1,
      "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).",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "urban_rural_filter": {
      "default": "R",
      "description": "Defaults to rural (\"R\") — where underservice is most concentrated. Use \"U\" to find underserved urban areas (digital redlining research). Set to \"all\" for both.",
      "type": "string",
      "enum": [
        "all",
        "R",
        "U"
      ]
    },
    "limit": {
      "default": 20,
      "description": "Maximum number of areas to return, ranked by unserved population (descending).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "areas": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "FIPS GEOID of the geography."
          },
          "name": {
            "description": "Human-readable geography name if resolved (e.g., \"Pontotoc County, MS\").",
            "type": "string"
          },
          "rank": {
            "type": "number",
            "description": "Rank by unserved population (1 = most unserved)."
          },
          "noCoverage": {
            "type": "number",
            "description": "Population with zero providers at the given speed threshold."
          },
          "oneProvider": {
            "type": "number",
            "description": "Population with exactly one provider."
          },
          "total": {
            "type": "number",
            "description": "Total population in the geography."
          },
          "unservedPct": {
            "type": "number",
            "description": "Percentage of population with no coverage."
          },
          "coveragePct": {
            "type": "number",
            "description": "Percentage of population with at least one provider."
          }
        },
        "required": [
          "id",
          "rank",
          "noCoverage",
          "oneProvider",
          "total",
          "unservedPct",
          "coveragePct"
        ],
        "additionalProperties": false,
        "description": "An underserved area ranked by unserved population."
      },
      "description": "Ranked list of underserved areas."
    },
    "geographyType": {
      "type": "string",
      "description": "Geography type returned."
    },
    "speedDownMbps": {
      "type": "number",
      "description": "Speed threshold used in Mbps."
    },
    "urbanRuralFilter": {
      "type": "string",
      "description": "Urban/rural filter applied."
    },
    "dataVintage": {
      "type": "string",
      "description": "Data vintage — Form 477 data as of June 2021."
    },
    "totalFound": {
      "type": "number",
      "description": "Total number of areas found before applying the limit filter."
    },
    "truncated": {
      "description": "True when more areas matched than the limit returned. Absent when not truncated.",
      "type": "boolean"
    },
    "shown": {
      "description": "Number of areas returned after applying the limit. Present when truncated.",
      "type": "number"
    },
    "cap": {
      "description": "The limit that was applied. Present when truncated.",
      "type": "number"
    },
    "scanTruncated": {
      "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.",
      "type": "boolean"
    },
    "scanRowCap": {
      "description": "Raw upstream row ceiling that bound the scan. Present only when scanTruncated is true.",
      "type": "number"
    },
    "appliedFilters": {
      "type": "object",
      "properties": {
        "state": {
          "description": "State abbreviation filter applied. Absent for nationwide searches.",
          "type": "string"
        },
        "geographyType": {
          "type": "string",
          "description": "Geographic granularity queried."
        },
        "speedDownMbps": {
          "type": "number",
          "description": "Download speed threshold in Mbps."
        },
        "techFilter": {
          "type": "string",
          "description": "Technology filter applied."
        },
        "urbanRuralFilter": {
          "type": "string",
          "description": "Urban/rural filter applied."
        },
        "minUnservedPop": {
          "type": "number",
          "description": "Minimum unserved population filter applied."
        }
      },
      "required": [
        "geographyType",
        "speedDownMbps",
        "techFilter",
        "urbanRuralFilter",
        "minUnservedPop"
      ],
      "additionalProperties": false,
      "description": "Filters applied to this query."
    },
    "notice": {
      "description": "Guidance about the result set — 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.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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.",
              "examples": [
                "unknown_state"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "areas",
        "geographyType",
        "speedDownMbps",
        "urbanRuralFilter",
        "dataVintage",
        "totalFound",
        "appliedFilters"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Returns available data vintages: Form 477 filing periods (hardcoded Jun 2015 – Jun 2021, always available) and BDC as-of dates from the authenticated API (Jun 2022 onward, requires credentials). Call this before fcc_list_downloads to determine valid as_of_date values. Note: there is a data gap between June 2021 (last Form 477) and June 2022 (first BDC filing period).

{
  "type": "object",
  "properties": {
    "include_bdc": {
      "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.",
      "type": "boolean"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

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

Lists downloadable BDC data files for a specific as-of date — fixed availability by state and provider, mobile coverage, and challenge data — with file metadata (provider, state, technology, record count). Download URLs are included for each file. Requires FCC BDC API credentials (FCC_BDC_USERNAME and FCC_BDC_HASH_VALUE). Use fcc_list_filing_periods first to determine valid as_of_date values (BDC dates start June 2022); a date that is not on the calendar, or that falls before the first BDC period, is rejected without credentials, while a well-formed date the BDC API does not publish is rejected once credentials let the published set be read. One as-of date can carry thousands of per-provider files, so results come back a page at a time: totalFiles counts every file matching the filters, the response reports the offset and the count on this page, and it carries a nextOffset to pass back for the following page until the last one, which omits it.

{
  "type": "object",
  "properties": {
    "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."
    },
    "data_type": {
      "default": "availability",
      "description": "\"availability\" = ISP-reported coverage files (by state and provider). \"challenge\" = consumer and government dispute records.",
      "type": "string",
      "enum": [
        "availability",
        "challenge"
      ]
    },
    "category": {
      "description": "File category. \"State\" = per-state coverage files. \"Provider\" = per-provider files. \"Summary\" = aggregate coverage tables.",
      "type": "string",
      "enum": [
        "Summary",
        "State",
        "Provider"
      ]
    },
    "technology_type": {
      "description": "Filter to a specific technology type of coverage data.",
      "type": "string",
      "enum": [
        "Fixed Broadband",
        "Mobile Broadband",
        "Mobile Voice"
      ]
    },
    "state": {
      "description": "Filter to one state's files (2-letter abbreviation, e.g., \"WA\").",
      "type": "string",
      "pattern": "^[A-Z]{2}$"
    },
    "provider_name": {
      "description": "Partial provider holding company name to filter results (case-insensitive).",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "description": "Maximum number of files to return on one page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "offset": {
      "default": 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.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "as_of_date"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "fileId": {
            "type": "string",
            "description": "Unique file identifier."
          },
          "fileName": {
            "type": "string",
            "description": "File name."
          },
          "category": {
            "type": "string",
            "description": "File category (e.g., \"State\", \"Provider\", \"Summary\")."
          },
          "subcategory": {
            "description": "File subcategory when available.",
            "type": "string"
          },
          "technologyType": {
            "description": "Technology type covered (e.g., \"Fixed Broadband\", \"Mobile Broadband\").",
            "type": "string"
          },
          "stateName": {
            "description": "State name for state-level files.",
            "type": "string"
          },
          "stateAbbr": {
            "description": "State abbreviation for state-level files.",
            "type": "string"
          },
          "providerName": {
            "description": "Provider name for provider-level files.",
            "type": "string"
          },
          "fileSizeBytes": {
            "description": "File size in bytes when available.",
            "type": "number"
          },
          "recordCount": {
            "description": "Number of records in the file when available.",
            "type": "number"
          },
          "downloadUrl": {
            "type": "string",
            "description": "Direct download URL for the file."
          },
          "asOfDate": {
            "type": "string",
            "description": "As-of date for this file."
          }
        },
        "required": [
          "fileId",
          "fileName",
          "category",
          "downloadUrl",
          "asOfDate"
        ],
        "additionalProperties": false,
        "description": "A downloadable BDC file entry."
      },
      "description": "Downloadable BDC files on this page, in the order the BDC API lists them."
    },
    "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."
    },
    "asOfDate": {
      "type": "string",
      "description": "The queried as-of date."
    },
    "dataType": {
      "type": "string",
      "description": "Data type queried (availability or challenge)."
    },
    "offset": {
      "type": "number",
      "description": "Zero-based index of the first file on this page."
    },
    "pageSize": {
      "type": "number",
      "description": "Maximum files one page returns — the limit that was applied."
    },
    "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."
    },
    "nextOffset": {
      "description": "Offset to pass back for the next page. Omitted on the last page and when the offset is past the end.",
      "type": "number"
    },
    "truncated": {
      "type": "boolean",
      "description": "True when this page holds fewer files than totalFiles, so more pages exist."
    },
    "appliedFilters": {
      "type": "object",
      "properties": {
        "asOfDate": {
          "type": "string",
          "description": "As-of date queried."
        },
        "dataType": {
          "type": "string",
          "description": "Data type queried."
        },
        "category": {
          "description": "Category filter applied. Absent when not filtered.",
          "type": "string"
        },
        "technologyType": {
          "description": "Technology type filter applied. Absent when not filtered.",
          "type": "string"
        },
        "state": {
          "description": "State filter applied. Absent for all-state results.",
          "type": "string"
        },
        "providerName": {
          "description": "Provider name filter applied. Absent when not filtered.",
          "type": "string"
        }
      },
      "required": [
        "asOfDate",
        "dataType"
      ],
      "additionalProperties": false,
      "description": "Filters applied to this query."
    },
    "notice": {
      "type": "string",
      "description": "Where this page sits in the matching set and how to continue — or, when the page is empty, whether nothing matched the filters or the offset ran past the end."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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.",
              "examples": [
                "credentials_required",
                "invalid_as_of_date"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "files",
        "totalFiles",
        "asOfDate",
        "dataType",
        "offset",
        "pageSize",
        "count",
        "truncated",
        "appliedFilters",
        "notice"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}