Skip to main content
Glama

fcc-broadband-mcp-server

by io.github.cyanheads

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
NameRequiredDescriptionDefault
limitNoMaximum number of files to return on one page.
stateNoFilter to one state's files (2-letter abbreviation, e.g., "WA").
offsetNoZero-based index of the first file to return, within the files matching the filters. Start at 0 and follow the nextOffset each response carries.
categoryNoFile category. "State" = per-state coverage files. "Provider" = per-provider files. "Summary" = aggregate coverage tables.
data_typeNo"availability" = ISP-reported coverage files (by state and provider). "challenge" = consumer and government dispute records.availability
as_of_dateYesBDC 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_nameNoPartial provider holding company name to filter results (case-insensitive).
technology_typeNoFilter to a specific technology type of coverage data.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
countNoFiles actually returned on this page. Zero both when nothing matched and when the offset is past the end; the notice says which.
errorNoPresent when the call failed. Absent on success.
filesNoDownloadable BDC files on this page, in the order the BDC API lists them.
noticeNoWhere 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.
offsetNoZero-based index of the first file on this page.
asOfDateNoThe queried as-of date.
dataTypeNoData type queried (availability or challenge).
pageSizeNoMaximum files one page returns — the limit that was applied.
truncatedNoTrue when this page holds fewer files than totalFiles, so more pages exist.
nextOffsetNoOffset to pass back for the next page. Omitted on the last page and when the offset is past the end.
totalFilesNoFiles 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.
appliedFiltersNoFilters applied to this query.

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 toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.4/5.0
Disambiguation5/5

Each tool targets a distinct resource and action: geocoding, availability lookup, provider search, provider details, coverage summaries, area comparisons, underserved analysis, data version listing, and file downloads. No two tools have overlapping purposes.

Naming Consistency5/5

All tools follow the `fcc_` prefix plus a clear verb_noun pattern (e.g., `fcc_geocode_block`, `fcc_search_availability`, `fcc_list_downloads`). Naming is consistent snake_case with a predictable structure.

Tool Count5/5

9 tools is well-scoped for a domain-specific data server. Each tool earns its place, covering the core workflow of geocoding, availability, provider lookup, coverage analysis, and data file access without redundancy.

Completeness4/5

The tool set covers the essential lifecycle: geocode → search availability, search providers → get provider, coverage summaries, comparisons, and data file discovery. Minor gaps exist (e.g., no direct address search, but geocoding prerequisites handle it), but the surface is comprehensive for FCC broadband analysis.

Resources