fcc-broadband-mcp-server

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

The description adds useful behavioral context beyond the annotations: it returns a ranked table, sorts by unserved/underserved population, and notes the data vintage (FCC Form 477 as of June 2021). The read-only and idempotent hints are already provided, so the description's additional details about output and data recency are valuable.

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

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

The description is two sentences long, front-loaded with the main purpose and output, then provides a use case and key usage modes. No filler or redundant information; every clause earns its place.

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

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

The description covers the core use case, the comparison scope, data source recency, and the alternative mode (compare_all_states). With a rich schema and output schema present, the description doesn't need to explain every parameter, and it sufficiently contextualizes when to use the tool for an agent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the max size of geography_ids and the compare_all_states override, but it doesn't add semantic meaning beyond what the schema already provides for parameters like sort_by, speed_down, and tech_filter. The schema descriptions are already thorough.

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

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

The description clearly states the tool's function with a specific verb ('Compares') and resource ('broadband coverage metrics across multiple geographies') while producing a ranked table. It also provides a concrete use case ('which counties in this state have the worst broadband access?') that distinguishes it from sibling tools focused on single-area queries.

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

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

The description gives clear context for when to use this tool (comparing geographies of the same type, BEAD funding prioritization) and explicit usage instructions (provide up to 50 IDs or set compare_all_states=true). It doesn't explicitly mention alternative sibling tools, but the purpose is distinct enough that an agent can infer when to choose this over others.

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

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

Annotations already disclose readOnly and idempotent behavior. The description adds valuable context: data source and vintage ('FCC Form 477 (as of June 2021)') and the default to rural areas. These go beyond annotations and help the agent set expectations about data freshness.

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

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

Three sentences, each carrying distinct information: core function and ranking, intended use and scope, and data source. No fluff or redundancy; front-loaded with the most important information.

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

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

For a read-only query tool with an output schema and fully documented parameters, the description supplies essential high-level context: purpose, ranking, scope options, default behavior, and data vintage. It is complete enough for an agent to understand when and why to use this tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions general concepts like 'speed threshold' and 'state abbreviation,' but these do not add meaning beyond what the parameter descriptions already provide. No additional parameter semantics are introduced.

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

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

The description clearly states the tool 'Finds geographic areas with limited or no broadband coverage at a given speed threshold, ranked by unserved population.' It distinguishes itself by positioning as 'the core tool for BEAD program analysis and broadband equity research,' which is unique among sibling tools.

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

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

Provides clear usage context ('BEAD program analysis and broadband equity research') and explains scope selection (state abbreviation or nationwide). It does not explicitly mention alternatives or exclusions, but the context is strong enough to guide appropriate use.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description reveals the tool uses the FCC public Geo API with no authentication required, and clarifies that results are resolved against 2010 census boundaries. This adds meaningful behavioral context not available from annotations alone.

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

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

The description is three sentences long, front-loaded with the primary purpose, and each sentence adds essential context (prerequisite, vintage, API details). No word is wasted, making it highly concise and well-structured.

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

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

Given the output schema exists and the tool is relatively simple, the description sufficiently covers the key contextual aspects: the purpose, the relationship to fcc_search_availability, the vintage boundary, and the lack of authentication. It is complete for an effective agent decision.

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

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

Schema description coverage is 100% and the schema already provides clear definitions for latitude and longitude including bounds and examples. The description adds no additional parameter-specific semantics beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool converts lat/long to a 15-digit census block FIPS code plus ancillary geographic identifiers. It also distinguishes itself by explicitly noting it is a prerequisite for fcc_search_availability, differentiating it from sibling tools.

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

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

Explicitly states when to use this tool: as the required prerequisite for fcc_search_availability because the broadband dataset is indexed by census block. It also warns about vintage mismatches (2010 vs 2020), providing clear guidance on when this specific tool is appropriate.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description doesn't need to restate safety. It adds valuable context: the data is from FCC Form 477 as of June 2021, indicating a potential data vintage limitation, and it returns summary counts rather than raw records. No contradiction 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.

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

The description is two sentences, front-loaded with the core return value, then adding context about geography types, data source, and usage guidance. Every sentence earns its place, and there is no redundant or vague wording.

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

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

Given the rich input schema and output schema presence, the description covers the essential context: what the tool returns, what geography levels it supports, the data vintage, and how to use it for BEAD analysis. This is complete enough for an agent to select and invoke correctly.

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

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

The input schema provides 100% description coverage for all six parameters, including defaults and enums. The description adds a policy-specific speed recommendation (100 Mbps for BEAD) but does not explain individual parameters, so the schema carries the weight. This meets the baseline for high schema coverage.

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

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

The description clearly states the tool returns a broadband coverage summary with specific detail: population counts by provider tiers at a speed threshold, split by urban/rural and tribal/non-tribal. It also identifies itself as the primary tool for digital divide analysis, distinguishing it from siblings like search_availability or find_underserved.

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

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

The description gives strong usage context: it is 'the primary tool for digital divide and equity analysis' and specifically recommends using 100 Mbps for BEAD policy analysis. It does not explicitly list when not to use it, but the guidance is clear enough for an agent to select it over alternatives.

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

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

The annotations already declare readOnlyHint and idempotentHint, so the description adds value by explaining deduplication of population counts across technologies, the data source (FCC Form 477 as of June 2021), and the national-level scope. These details go beyond the structured annotations without contradiction.

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

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

The description uses four sentences, each adding distinct information: primary purpose, population counting nuance, validation path, and data vintage. It is concise and front-loaded with the main verb and resource, with no wasteful phrases.

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

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

For a simple one-parameter read-only tool with an output schema, the description covers the purpose, data semantics, prerequisite lookup, and data source. It does not need to explain return values because the output schema exists, and it includes the dedup nuance that is otherwise non-obvious.

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

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

The schema already fully documents the hoconum parameter with pattern, description, and example. The tool description mentions 'by hoconum' and points to fcc_search_providers, but this is largely redundant with the schema's description. Since schema coverage is 100%, the baseline score of 3 is appropriate.

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

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

The description clearly specifies the action: 'Returns a national-level coverage profile for a specific holding company' by hoconum, including technologies and population per download speed tier. It distinguishes this from siblings (e.g., fcc_search_providers) by focusing on retrieving a profile for a known provider rather than searching or comparing areas.

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

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

The description gives a clear context for when to use this tool: when you need a provider's national coverage profile. It also points to fcc_search_providers as a prerequisite for finding valid hoconum values, but it does not explicitly state when to avoid this tool in favor of alternatives, leaving some implicit guidance.

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

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

Annotations declare readOnly, idempotent, and closed-world behavior. The description adds crucial context: credential requirements, pagination semantics, and edge-case rejection behavior before and after credentials are validated. No contradiction 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.

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

The description is a single dense paragraph with no filler. Every sentence contributes value: purpose, file scope, metadata, credentials, prerequisites, error behavior, and pagination. It is front-loaded with the core function and then provides necessary detail.

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

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

The description covers auth, prerequisite tool usage, error modes, pagination, and file scope. With an output schema present, it correctly omits detailed return-value explanations while still mentioning key fields like totalFiles, offset, and nextOffset.

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

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

The input schema already provides 100% coverage with detailed descriptions for all 8 parameters. The description adds high-level context about the large result set, which justifies the need for pagination parameters, and reinforces the offset/nextOffset workflow described in the schema.

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

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

The description clearly identifies the tool as listing downloadable BDC data files with metadata and download URLs for a specific as-of date. It uses a specific verb+resource ('Lists downloadable BDC data files') and distinguishes from sibling tools like fcc_list_filing_periods, which lists calendar periods rather than files.

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

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

The description explicitly instructs to call fcc_list_filing_periods first to determine valid as_of_date values, and explains error behavior for invalid dates versus unpublished dates. It also provides clear pagination usage guidance, telling the agent to follow nextOffset until it is omitted.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to restate safety. It adds valuable context: hardcoded periods are always available, BDC requires authentication, and there is a data gap between June 2021 and June 2022. This goes beyond annotations without contradicting them.

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

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

Three sentences convey all key facts: data sources, time ranges, availability, credentials, ordering, and a data gap. No redundancy or filler. Information is front-loaded with the primary output, making it highly scannable.

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

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

The description covers the essential preconditions (auth for BDC), sequencing (before fcc_list_downloads), and the data gap that could invalidate reasoning. Output schema exists, so return format need not be explained. For a list tool with one optional parameter, this is exceptionally complete.

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

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

Schema description covers the include_bdc parameter fully (100% coverage), so the baseline is 3. The description does add context about the parameter's purpose (determining valid as_of_date values), but this is marginal and largely restates the schema's explanation of credentials. No significant new parameter semantics beyond the schema.

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

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

The description uses a specific verb 'returns' and identifies the resource as 'available data vintages' including Form 477 and BDC periods. It distinguishes itself from fcc_list_downloads by explicitly positioning this as the precursor to determine valid as_of_date values, making its purpose unmistakable.

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

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

Explicitly instructs 'Call this before fcc_list_downloads to determine valid as_of_date values', providing a clear when-to-use directive and naming the relevant sibling. It also notes the BDC branch requires credentials, offering important context for whether to invoke this tool at all.

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

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

Beyond the readOnly/idempotent annotations, the description warns that ISP-reported availability may overstate actual coverage and notes the June 2021 vintage. This provides decision-relevant caveats without contradicting the annotations.

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

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

The description is four sentences, front-loaded with the core query and answer, then prerequisite and caveat. None of the sentences are filler.

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

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

With output schema present and annotations indicating read-only/idempotent behavior, the description's caveat about data overstatement and the geocoding prerequisite make it self-sufficient for an agent to decide when and how to call it.

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

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

Schema coverage is 100%, so the baseline is 3. The description restates the 15-digit FIPS requirement but adds no new parameter-level detail beyond what the schema already provides.

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

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

The description uses 'Queries' with a specific resource (broadband providers and advertised speeds at a census block) and explicitly answers a concrete question. It positions itself as 'the core tool for address-level broadband lookup,' distinguishing it from the sibling geocoder and other FCC tools.

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

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

It clearly states the prerequisite (15-digit census block FIPS, get from fcc_geocode_block) and the data vintage. It doesn't explicitly name exclusions or alternative tools beyond the geocoder, so it falls short of a 5.

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

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

Even with readOnlyHint and idempotentHint annotations, the description adds crucial behavioral details: the search reads a bounded window, so results may be a sample when scanTruncated is true, and each returned provider carries its full national footprint at the cost of one lookup per provider. This goes far beyond the annotations.

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

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

The description is long but every sentence earns its place, covering sampling behavior, deduplication, filter semantics, and data source. It is front-loaded with the core purpose and structured logically, making it easy for an agent to parse.

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

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

The tool has complex behavior (bounded window reads, sampling, per-company resolution) and the description thoroughly explains these caveats, including what scanTruncated means and when results are incomplete. Given an output schema exists, the description is remarkably complete.

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

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

Schema description coverage is 100% and the schema already explains state and tech_filter semantics in detail (e.g., matching on individual filings). The tool description adds little beyond the schema, so the baseline of 3 is appropriate; it does not materially enrich parameter understanding.

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

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

The description begins with a specific verb ('Searches for ISPs') and names the resource (holding company) and filters (state and technology type). It also differentiates from siblings by stating it returns hoconum identifiers for follow-up calls to fcc_get_provider and answering concrete questions like 'which ISPs serve Washington with fiber?'.

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

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

It explicitly states when to use the tool via example questions and provides a when-not through 'Geographic filtering is state-level; sub-state granularity requires cross-referencing block data.' It also names an alternative for complete results: 'only a deployment running the local Form 477 mirror returns every match.'

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