fcc-broadband-mcp-server

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety profile. The description adds meaningful behavioral context: the tool returns a ranked table sorted by unserved or underserved population, and the data is from FCC Form 477 as of June 2021—a critical limitation for recency-sensitive decisions. This goes beyond the 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?

The description is four sentences, each contributing essential information: what it does, an example use case, key usage constraints, and data source. It is front-loaded with the core action and output, and there is no redundant or filler content. Every sentence 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?

Given the tool's complexity (6 parameters, 4 enums), the description covers the main usage scenarios, constraints, and data vintage. The output schema exists, so the description does not need to explain return values. Annotations cover safety, and the schema covers parameter details. The description adds the essential 'why' and 'how' context, making it complete for an agent to select and invoke the tool 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?

Schema description coverage is 100%, so the baseline is 3. The description mentions the 'up to 50 geography IDs' and 'compare_all_states=true' modes, but these are already detailed in the schema. It does not add meaningfully new parameter semantics beyond what the schema provides, though it reinforces the conceptual context of the sort_by options for BEAD funding.

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 compares broadband coverage metrics across multiple geographies of the same type and outputs a ranked table. It provides a concrete example question ('which counties in this state have the worst broadband access?') and distinguishes itself from siblings like fcc_get_coverage_summary by focusing on multi-geography comparison. The verb+resource+output structure is specific and unambiguous.

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 multiple geographies, answering ranking questions, and supporting BEAD funding prioritization. It also provides usage constraints (up to 50 IDs or compare_all_states=true, same geography type). However, it does not explicitly name alternatives or state when not to use it, 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?

Annotations already declare read-only and idempotent, so the description's disclosure of data vintage (FCC Form 477, June 2021), default rural filter, and ranking mechanism adds valuable behavioral context without contradicting 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?

Three sentences: main function, positioning, and scope/data source. Every sentence earns its place, with no fluff, and the most important purpose is front-loaded.

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 detailed input schema, the description covers the purpose, data source, and defaults. It could mention the BEAD speed threshold (100 Mbps) but the schema already does, so it's complete enough.

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 provides 100% coverage of parameter descriptions, including enums for speed_down, tech_filter, geography_type, and urban_rural_filter. The description only adds a high-level framing (rural defaults, ranking) but does not add new per-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 clearly states the tool's function with a specific verb ('Finds geographic areas...'), scope ('at a given speed threshold, ranked by unserved population'), and even distinguishes it from siblings via 'core tool for BEAD program analysis'. This gives it a clear identity.

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 positions the tool for BEAD program analysis and broadband equity research, and notes the state filter to narrow scope. It implies when to use it (for ranked underserved areas) but does not explicitly name alternatives or when not to use it, which would make it 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable context beyond annotations by disclosing the external dependency ('Uses the FCC public Geo API') and the lack of auth requirements. This goes beyond what the annotations alone provide, though it does not cover potential rate limits or error behavior, which would be nice but is not critical for a read-only lookup.

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 exactly two sentences, with the primary action and result front-loaded in the first sentence. The second sentence provides essential contextual guidance (prerequisite relationship, API type, auth) without any fluff or repetition of schema details. 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 clearly explains the tool's purpose, output fields, prerequisite usage, and external API dependence. Combined with the presence of an output schema (which the description need not duplicate), the description fully covers what an agent needs to know to invoke this tool correctly, especially in the context of the sibling tools like fcc_search_availability.

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 has 100% description coverage for both parameters (latitude and longitude), including examples and range constraints. The tool description itself does not add additional parameter-specific semantics beyond what the schema already captures, so it earns the baseline score of 3. There is no gap requiring compensation.

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 ('Converts') and clearly identifies the resource (a lat/long coordinate to census block FIPS plus related geographic identifiers). It distinguishes itself from sibling tools by explicitly mentioning the prerequisite relationship to fcc_search_availability, making its unique role evident.

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 states when to use this tool: 'This is the required prerequisite for fcc_search_availability since the broadband dataset is indexed by census block, not address.' This provides the exact context and rationale for choosing this tool over alternatives, effectively guiding the agent on when it should be invoked.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds valuable context: data source (FCC Form 477) and vintage (June 2021), plus national-level scope, which goes beyond what annotations provide.

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?

Two sentences with no wasted words. The main action and outcome are front-loaded, followed by a practical instruction and data provenance. Every sentence contributes to understanding the tool.

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 single-parameter lookup with an output schema present, the description is complete. It states what the response contains (states, technologies, speed tiers), the required input, and the data source, leaving no obvious gaps for an agent to misuse the 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 covers hoconum fully with an example and provenance from fcc_search_providers. The description reinforces this by explicitly linking the parameter to the search tool, adding semantic context that the schema alone does not provide.

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 starts with 'Returns a national-level coverage profile for a specific holding company', clearly stating verb, resource, and scope. It enumerates the specific data points (states served, technologies deployed, speed tiers) which distinguishes it from sibling tools like fcc_get_coverage_summary.

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?

Description explicitly tells users to 'Use fcc_search_providers to find valid hoconum values', providing a direct alternative for obtaining the required parameter. This is clear usage guidance for a one-parameter lookup, covering the main prerequisite.

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, idempotentHint=true, and openWorldHint=false, establishing a safe read operation. The description adds meaningful context about credential requirements and the inclusion of download URLs and metadata, without contradicting the annotations. It does not elaborate on pagination or error behavior, but this is not critical given 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 three sentences long, starts with the core purpose, then details outputs, then covers credentials and prerequisite. Every sentence adds distinct value with no redundancy or fluff.

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 tool's complexity (6 params, output schema present, read-only annotations), the description covers purpose, scope, credential requirements, and prerequisite. It might have mentioned pagination or limits, but the presence of an output schema and the simple listing nature make the current description sufficient.

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 has 100% description coverage, with all six parameters documented including examples and cross-references to fcc_list_filing_periods. The description itself does not add additional parameter-level detail beyond what is in the schema, so a baseline 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 lists downloadable BDC data files for a specific as-of date, specifying the types of data and that it includes file metadata and download URLs. It distinguishes itself from sibling tools by focusing on file downloads rather than queries or summaries, and explicitly references fcc_list_filing_periods for date validation.

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 provides a clear prerequisite, 'Use fcc_list_filing_periods first to determine valid as_of_date values,' and notes the need for FCC BDC API credentials. It implies the tool is for downloading files rather than analyzing coverage, but does not explicitly enumerate what other tools should be used for instead.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the data is 'as of June 2021' and 'reflects ISP-reported availability at the block level, which may overstate actual coverage for some addresses.' This is a meaningful data-quality caveat that helps set expectations.

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 with no redundancy: sentence 1 states purpose and data source, sentence 2 clarifies the use case and prerequisite, sentence 3 provides data limitations. It is front-loaded, skimmable, and every sentence 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?

Given the 4 parameters, 1 required, and the presence of an output schema, the description covers the essential context: how to obtain the required input (via fcc_geocode_block), what data vintage to expect (June 2021), and a key accuracy limitation. With an output schema available, not explaining return values is acceptable.

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%, with each parameter already documented in detail (e.g., block_fips pattern, tech_filter enum codes, consumer filter). The description adds no parameter-level semantics beyond the schema; it only repeats the block_fips requirement. Per the calibration baseline, a 3 is appropriate when the schema carries the load.

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 opens with a specific verb and resource: 'Queries broadband providers and advertised speeds at a census block from FCC Form 477 data.' It also answers the core question ('which ISPs serve this location and what speeds do they offer?') and frames it as the 'core tool for address-level broadband lookup,' distinguishing it from sibling tools that target other scopes.

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: when you have a census block FIPS code, this is the tool to use. It explicitly names a prerequisite/alternative: 'use fcc_geocode_block to convert coordinates first.' However, it does not explicitly state when not to use this tool versus other siblings like fcc_search_providers or fcc_get_coverage_summary, so it misses the full when-not 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 already declare readOnlyHint and idempotentHint, but the description adds valuable behavioral context: it states deduplication of results, identifies the output includes hoconum identifiers, provides data provenance (FCC Form 477 as of June 2021), and clarifies geographic filtering scope. This goes well beyond the minimal annotation info.

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 purpose, and every sentence adds distinct useful information (purpose, output details, examples, limitations/data source). No fluff or redundancy, making it appropriately sized 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 annotations cover safety, the description is complete: it explains what the tool does, what it returns (deduplicated list with identifiers), provides usage examples, notes data freshness and limitations, and indicates the follow-up tool. No critical gaps remain for an agent to select and invoke the tool 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?

Schema coverage is 100% with each parameter already documented. The description restates general filtering by state/technology but does not add new parameter-specific meaning beyond the schema. It does not elaborate on `limit`, `name_search`, or the tech code semantics beyond what is in the schema, so baseline 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 uses a specific verb ('Searches for ISPs') and names the resource (holding company name, state, technology type). It clearly distinguishes this from sibling tools by mentioning 'hoconum identifiers for follow-up calls to fcc_get_provider' and providing concrete example queries, making it evident that this is a provider discovery tool rather than a coverage or geocoding tool.

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 usage context via examples ('which ISPs serve Washington with fiber?') and notes the follow-up tool (fcc_get_provider), implying when to use this tool. It also mentions a limitation (state-level granularity) that signals when not to use it for sub-state queries, but it does not explicitly contrast with alternative sibling tools like fcc_search_availability.

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