Skip to main content
Glama

Search Broadband Providers

fcc_search_providers
Read-onlyIdempotent

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).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of distinct providers to return.
stateNo2-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.
name_searchNoPartial holding company name to search (case-insensitive). e.g., "Comcast", "T-Mobile", "Frontier". Omit to list all providers in a state.
tech_filterNoTechnology 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.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe limit that was applied. Present when capped.
errorNoPresent when the call failed. Absent on success.
shownNoNumber of providers returned. Present when capped.
noticeNoGuidance 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.
providersNoMatching providers, deduplicated by holding company.
truncatedNoTrue when results were capped at the limit and more providers may exist. Absent when not capped.
scanRowCapNoRaw upstream row ceiling that bound the scan. Present only when scanTruncated is true.
totalCountNoDistinct 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.
totalFoundNoProviders in this response. Not the number matching the query — that is totalCount, and it is only knowable when the scan read every matching row.
dataVintageNoData vintage — Form 477 data as of June 2021.
scanTruncatedNoTrue 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.
appliedFiltersNoFilters applied to this query.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `no_providers_found`: No providers matched the search criteria. `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."New value: +"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."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "no_providers_found",
      -  "live_search_timeout"
      -]New value: +[
      +  "live_search_timeout"
      +]
  2. Changed6 schema fields changed
    • 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": [
      +      "providers",
      +      "totalFound",
      +      "dataVintage",
      +      "appliedFilters"
      +    ]
      +  },
      +  {
      +    "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: `no_providers_found`: No providers matched the search criteria. `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": [
      +            "no_providers_found",
      +            "live_search_timeout"
      +          ],
      +          "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: -[
      -  "providers",
      -  "totalFound",
      -  "dataVintage",
      -  "appliedFilters"
      -]
  3. Changed2 schema fields changed
    • changedInput schema / properties / tech_filter / description
      Previous value: -"Technology codes to filter. 50=Fiber, 40–43=Cable, 10–12=DSL, 60=Satellite, 70=Fixed wireless. 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."New value: +"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."
    • changedInput schema / properties / tech_filter / items / enum
      Previous value: -[
      -  "10",
      -  "11",
      -  "12",
      -  "40",
      -  "41",
      -  "42",
      -  "43",
      -  "50",
      -  "60",
      -  "70"
      -]New value: +[
      +  "0",
      +  "10",
      +  "11",
      +  "12",
      +  "20",
      +  "30",
      +  "40",
      +  "41",
      +  "42",
      +  "43",
      +  "50",
      +  "60",
      +  "70",
      +  "90"
      +]
  4. Changed10 schema fields changed
    • changedInput schema / properties / state / description
      Previous value: -"2-letter state abbreviation (e.g., \"WA\") to limit results to providers serving that state."New value: +"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."
    • changedInput schema / properties / tech_filter / description
      Previous value: -"Technology codes to filter. 50=Fiber, 40–43=Cable, 10–12=DSL, 60=Satellite, 70=Fixed wireless. Omit for all technologies."New value: +"Technology codes to filter. 50=Fiber, 40–43=Cable, 10–12=DSL, 60=Satellite, 70=Fixed wireless. 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."
    • changedOutput schema / properties / notice / description
      Previous value: -"Recovery hint when no providers are found — suggests how to broaden the search. Absent on successful results."New value: +"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."
    • changedOutput schema / properties / providers / items / properties / holdingCompanyName / description
      Previous value: -"Holding company name."New value: +"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."
    • changedOutput schema / properties / providers / items / properties / statesServed / description
      Previous value: -"State abbreviations where this provider has reported filings."New value: +"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."
    • changedOutput schema / properties / providers / items / properties / techCodes / description
      Previous value: -"Technology codes reported by this provider."New value: +"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."
    • addedOutput schema / properties / scanRowCap
      Added value: +{
      +  "description": "Raw upstream row ceiling that bound the scan. Present only when scanTruncated is true.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / scanTruncated
      Added value: +{
      +  "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"
      +}
    • addedOutput schema / properties / totalCount
      Added value: +{
      +  "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"
      +}
    • changedOutput schema / properties / totalFound / description
      Previous value: -"Number of distinct providers returned."New value: +"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."
  5. Changed3 schema fields changed
    • addedOutput schema / properties / cap
      Added value: +{
      +  "description": "The limit that was applied. Present when capped.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / shown
      Added value: +{
      +  "description": "Number of providers returned. Present when capped.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / truncated
      Added value: +{
      +  "description": "True when results were capped at the limit and more providers may exist. Absent when not capped.",
      +  "type": "boolean"
      +}
  6. Changed3 schema fields changed
    • addedOutput schema / properties / appliedFilters
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Filters applied to this query.",
      +  "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.",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "type": "object"
      +}
    • changedOutput schema / properties / notice / description
      Previous value: -"Recovery hint when results are empty — suggests how to broaden the search."New value: +"Recovery hint when no providers are found — suggests how to broaden the search. Absent on successful results."
    • changedOutput schema / required
      Previous value: -[
      -  "providers",
      -  "totalFound",
      -  "dataVintage"
      -]New value: +[
      +  "providers",
      +  "totalFound",
      +  "dataVintage",
      +  "appliedFilters"
      +]
  7. First observed

TDQS

A4.3/5.0
Behavior5/5

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

The description goes far beyond the readOnlyHint and idempotentHint annotations. It discloses the bounded-window read behavior, the sampling caveat when scanTruncated is true, the absence of a true match count, and that each returned provider carries a complete national footprint due to per-company resolution. It also states the data source and vintage (Form 477 as of June 2021). This is rich behavioral disclosure that an agent needs to interpret results correctly.

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

Conciseness3/5

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

The description is a single dense paragraph with many caveats. While every sentence adds value, it lacks visual structure (e.g., bullet points) and is longer than ideal for quick scanning. The core purpose is front-loaded, but the behavioral caveats are packed into a lengthy middle section. It is not as concise as it could be, though the complexity warrants some length.

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 the tool's complexity (bounded window, sampling, per-company resolution) and the presence of an output schema, the description is remarkably complete. It covers the critical caveat about scanTruncated and the sample nature of results, the fact that per-company lookups inflate cost, and the data vintage. Nothing essential for correct invocation or result interpretation is missing.

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

Parameters3/5

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

The input schema already covers all parameters with detailed descriptions (100% coverage). The tool description adds little parameter-specific meaning beyond what the schema provides; it reinforces that name_search is partial and case-insensitive, but that is already in the schema. The description does explain how state and tech_filter interact (must hold on one filing), which is also present in the schema descriptions. Thus, the description adds marginal value, so a baseline 3 is appropriate.

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 clear statement: 'Searches for ISPs by holding company name, filtered by state and technology type. Returns a deduplicated list of matching providers with hoconum identifiers.' This names the verb, resource, and outcome. It also gives example queries ('which ISPs serve Washington with fiber?') and explicitly ties to the sibling fcc_get_provider for follow-up, distinguishing it from the other search tool fcc_search_availability by clarifying that this one searches providers (not availability).

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?

The description provides concrete usage context: it answers specific question types and states that state-level filtering is the granularity ('sub-state granularity requires cross-referencing block data'). It also implies when not to rely on it (when scanTruncated is true, results are a sample). However, it does not explicitly name alternative tools for other scenarios (e.g., fcc_search_availability for address-based searches), so it falls short of the highest bar.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.