fcc-broadband-mcp-server

List BDC Downloads

fcc_list_downloads

Read-onlyIdempotent

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum number of files to return on one page.
`state`	No	Filter to one state's files (2-letter abbreviation, e.g., "WA").
`offset`	No	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`	No	File category. "State" = per-state coverage files. "Provider" = per-provider files. "Summary" = aggregate coverage tables.
`data_type`	No	"availability" = ISP-reported coverage files (by state and provider). "challenge" = consumer and government dispute records.	availability
`as_of_date`	Yes	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`	No	Partial provider holding company name to filter results (case-insensitive).
`technology_type`	No	Filter to a specific technology type of coverage data.

Output Schema

TableJSON Schema

Name	Required	Description
`count`	No	Files actually returned on this page. Zero both when nothing matched and when the offset is past the end; the notice says which.
`error`	No	Present when the call failed. Absent on success.
`files`	No	Downloadable BDC files on this page, in the order the BDC API lists them.
`notice`	No	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.
`offset`	No	Zero-based index of the first file on this page.
`asOfDate`	No	The queried as-of date.
`dataType`	No	Data type queried (availability or challenge).
`pageSize`	No	Maximum files one page returns — the limit that was applied.
`truncated`	No	True when this page holds fewer files than totalFiles, so more pages exist.
`nextOffset`	No	Offset to pass back for the next page. Omitted on the last page and when the offset is past the end.
`totalFiles`	No	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`	No	Filters applied to this query.

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedAug 25, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "files",
+      "totalFiles",
+      "asOfDate",
+      "dataType",
+      "offset",
+      "pageSize",
+      "count",
+      "truncated",
+      "appliedFilters",
+      "notice"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "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"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "files",
-  "totalFiles",
-  "asOfDate",
-  "dataType",
-  "offset",
-  "pageSize",
-  "count",
-  "truncated",
-  "appliedFilters",
-  "notice"
-]

Changed11 schema fields changedAug 13, 2026

addedInput schema / properties / limit

Added value: +{
+  "default": 50,
+  "description": "Maximum number of files to return on one page.",
+  "maximum": 200,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / offset

Added value: +{
+  "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.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

addedOutput schema / properties / count

Added value: +{
+  "description": "Files actually returned on this page. Zero both when nothing matched and when the offset is past the end; the notice says which.",
+  "type": "number"
+}

changedOutput schema / properties / files / description

Previous value: -"Downloadable BDC files matching the filters."New value: +"Downloadable BDC files on this page, in the order the BDC API lists them."

addedOutput schema / properties / nextOffset

Added value: +{
+  "description": "Offset to pass back for the next page. Omitted on the last page and when the offset is past the end.",
+  "type": "number"
+}

changedOutput schema / properties / notice / description

Previous value: -"Recovery hint when no files are found — suggests how to broaden the search. Absent on successful results."New value: +"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."

addedOutput schema / properties / offset

Added value: +{
+  "description": "Zero-based index of the first file on this page.",
+  "type": "number"
+}

addedOutput schema / properties / pageSize

Added value: +{
+  "description": "Maximum files one page returns — the limit that was applied.",
+  "type": "number"
+}

changedOutput schema / properties / totalFiles / description

Previous value: -"Total number of files returned after filtering."New value: +"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."

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when this page holds fewer files than totalFiles, so more pages exist.",
+  "type": "boolean"
+}

changedOutput schema / required

Previous value: -[
-  "files",
-  "totalFiles",
-  "asOfDate",
-  "dataType",
-  "appliedFilters"
-]New value: +[
+  "files",
+  "totalFiles",
+  "asOfDate",
+  "dataType",
+  "offset",
+  "pageSize",
+  "count",
+  "truncated",
+  "appliedFilters",
+  "notice"
+]

Changed3 schema fields changedMay 30, 2026

addedOutput schema / properties / appliedFilters

Added value: +{
+  "additionalProperties": false,
+  "description": "Filters applied to this query.",
+  "properties": {
+    "asOfDate": {
+      "description": "As-of date queried.",
+      "type": "string"
+    },
+    "category": {
+      "description": "Category filter applied. Absent when not filtered.",
+      "type": "string"
+    },
+    "dataType": {
+      "description": "Data type queried.",
+      "type": "string"
+    },
+    "providerName": {
+      "description": "Provider name filter applied. Absent when not filtered.",
+      "type": "string"
+    },
+    "state": {
+      "description": "State filter applied. Absent for all-state results.",
+      "type": "string"
+    },
+    "technologyType": {
+      "description": "Technology type filter applied. Absent when not filtered.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "asOfDate",
+    "dataType"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / notice

Added value: +{
+  "description": "Recovery hint when no files are found — suggests how to broaden the search. Absent on successful results.",
+  "type": "string"
+}

changedOutput schema / required

Previous value: -[
-  "files",
-  "totalFiles",
-  "asOfDate",
-  "dataType"
-]New value: +[
+  "files",
+  "totalFiles",
+  "asOfDate",
+  "dataType",
+  "appliedFilters"
+]

First observedMay 29, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already mark the operation as read-only and idempotent. The description adds meaningful behavior beyond that: the need for FCC_BDC_USERNAME/FCC_BDC_HASH_VALUE credentials, the specific error behavior for invalid dates (before credentials vs. after reading the published set), and the pagination structure (totalFiles, offset, count, nextOffset). No contradictions with annotations.

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

Conciseness5/5

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

The description is long but every sentence earns its place: purpose first, then credentials, then date validation, then pagination. It is front-loaded with the core action and avoids redundancy with the schema. The structure logically guides the agent from setup to execution.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists (so return values are documented elsewhere) and annotations cover safety, the description covers all essential operational context: valid date sources, credential requirements, pagination mechanics, and file categories. Nothing an agent needs to call this tool correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents each parameter. The description adds semantic value by explaining the pagination semantics (nextOffset, totalFiles) which clarifies how to use offset and limit, and by linking as_of_date to the filing periods tool. It does not repeat schema text but enriches context around the parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Lists downloadable BDC data files for a specific as-of date') and enumerates the types of files covered (availability, mobile coverage, challenge data) plus the metadata returned. It differentiates itself from siblings by mentioning a prerequisite (fcc_list_filing_periods) and focusing on file downloads, which is distinct from coverage summaries or searches.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly instructs to call fcc_list_filing_periods first to obtain valid as_of_date values, and explains the credential requirement. It details pagination handling (offset, count, nextOffset) so the agent knows how to iterate. It does not name alternative tools to avoid, but the workflow guidance is clear and actionable.

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

All fcc-broadband-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.