fcc-broadband-mcp-server

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

Annotations already declare readOnlyHint and idempotentHint, so no side effects. The description adds valuable behavioral details: data source (FCC Form 477, June 2021), output format (ranked table sorted by unserved/underserved), and that compare_all_states overrides geography_ids. This provides good context beyond 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, front-loaded with the primary purpose, and includes essential details (data source, limits, use case) without extraneous information. Every sentence serves a purpose.

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, 1 required, 4 enums) and the presence of a complete output schema and annotations, the description covers all critical aspects: use case, data freshness, constraints (max 50 IDs), and a clear example. It is sufficiently complete for an agent to understand when and how to use 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%, with detailed descriptions for all 6 parameters including enums and defaults. The description adds contextual value by linking BEAD funding to sorting options, but does not significantly enhance understanding beyond what the schema already provides. 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 compares broadband coverage metrics across multiple geographies and returns a ranked table, with example questions like 'which counties in this state have the worst broadband access?' This uniquely distinguishes it from siblings like fcc_find_underserved, which focuses on finding underserved areas rather than comparing.

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 explicit context for when to use the tool: to compare geographies for BEAD funding prioritization, with clear limits (up to 50 IDs or compare_all_states=true). However, it does not mention when not to use it or list alternative tools, leaving some ambiguity for agents.

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 true. The description adds data source (FCC Form 477 as of June 2021) and default behavior, which is helpful but not extensive behavioral detail.

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 concise sentences, front-loaded with purpose, no wasted words. Every sentence adds value.

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 100% schema coverage and an output schema, the description adds overarching purpose and data freshness. No gaps for effective use.

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 baseline is 3. The description reiterates state and urban_rural defaults already in schema, adding no new parameter-specific insight beyond what the schema 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 clearly states the tool finds underserved areas at a speed threshold, ranked by unserved population, and identifies it as core for BEAD analysis. It does not explicitly differentiate from sibling tools, but the purpose is 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 mentions BEAD program analysis and equity research, and notes options for state or nationwide scope and rural default, but does not provide when-not-to-use or alternative tool recommendations against siblings.

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 provide readOnlyHint, openWorldHint, and idempotentHint. The description adds context about using the FCC public Geo API with no authentication, which is consistent and helpful. No contradictions.

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 that are concise and front-loaded. The first sentence states the core functionality and outputs; the second provides critical usage context. Every word 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 existence of an output schema and high schema description coverage, the description is complete. It covers prerequisites, the API used, and authentication requirements, leaving no significant gaps for an agent to misinterpret.

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 detailed descriptions for latitude and longitude (including ranges and sign conventions). The description doesn't add new parameter information beyond what the schema provides, 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/lng to a 15-digit census block FIPS code plus other geographic identifiers. It uses a specific verb ('converts') and resource ('coordinate to census block'), and distinguishes itself from sibling tools by noting it's a prerequisite for fcc_search_availability.

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 it is 'the required prerequisite for fcc_search_availability' and mentions 'no authentication required,' providing clear guidance on when to use it. However, it doesn't explicitly state when not to use it or mention 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. The description adds valuable behavioral context: data source (FCC Form 477, June 2021) and a specific usage recommendation. No destructive behavior indicated, consistent 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 four sentences, front-loaded with the core purpose, then adds use case, supported geographies, data source, and a specific threshold recommendation. Every sentence adds value with no 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 comprehensive schema (6 params with descriptions), annotations, and existence of an output schema, the description covers all needed context: purpose, geographies, data source, and policy relevance. No gaps remain for an agent to 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 schema already provides full parameter documentation. The description does not add additional meaning beyond what the schema offers, making a baseline score of 3 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 states it 'returns a broadband coverage summary' with specific breakdowns (provider counts, urban/rural, tribal/non-tribal). It identifies itself as 'the primary tool for digital divide and equity analysis,' clearly distinguishing it from siblings like fcc_compare_areas or fcc_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 provides clear usage context: it's the primary tool for digital divide analysis and recommends using 100 Mbps for BEAD policy analysis. However, it does not explicitly state when not to use it or contrast with alternative tools.

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, indicating safe, idempotent read operations. The description adds valuable context beyond annotations by noting the data source (FCC Form 477 as of June 2021), which helps an agent understand data freshness. No contradictions.

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, front-loaded with the tool's purpose, followed by usage guidance and data source. Every sentence adds value without any 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?

For a tool with one required parameter and an existing output schema (indicated by context signals), the description fully covers purpose, parameter retrieval, and data provenance. It is self-contained and eliminates ambiguity for an AI 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 coverage is 100% and already describes the hoconum parameter, but the description adds semantic meaning by explaining it as a holding company number from fcc_search_providers and giving an example ('130152' for Comcast), providing further guidance 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 returns a national-level coverage profile for a specific holding company, detailing states, technologies, and location counts per speed tier. It distinguishes itself from the sibling tool fcc_search_providers by directing users to that tool for finding valid hoconum values.

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 says when to use this tool (to get a provider profile) and provides guidance on how to obtain the required hoconum parameter via fcc_search_providers, offering clear context and an alternative.

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 mark the tool as readOnly and idempotent. The description adds that download URLs are included and that credentials are required, providing useful behavioral context 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 concise with two sentences. The first sentence clearly states the purpose and content, and the second adds essential usage guidance. No unnecessary words.

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 (not shown but noted), the description sufficiently covers what the tool does, prerequisites, and constraints. It mentions dependency on another tool and required credentials, making it complete 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 baseline is 3. The description adds value by explaining the tool's content (e.g., 'fixed availability by state and provider, mobile coverage, and challenge data') and noting file metadata (provider, state, technology, record count), which complements the schema definitions.

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' and specifies the types of data (by state and provider, mobile coverage, challenge data) and included metadata (provider, state, technology, record count). It distinguishes itself from sibling tools like fcc_compare_areas or fcc_search_availability by being focused on listing downloads.

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 advises to use fcc_list_filing_periods first to determine valid as_of_date values, and mentions required credentials (FCC_BDC_USERNAME and FCC_BDC_HASH_VALUE). It does not explicitly state when not to use the tool, but the context is clear.

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 description adds behavioral context beyond annotations: Form 477 periods are hardcoded and always available, BDC requires authenticated API credentials, and there is a data gap. These details are consistent with readOnlyHint and idempotentHint.

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 concise (three sentences), front-loaded with the main purpose, and each sentence adds necessary information without redundancy.

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 has an output schema, the description appropriately covers purpose, usage order, data gap, and credential requirements. It is complete for a list tool with one parameter.

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 covers all parameters, but the description adds value by explaining that include_bdc=true triggers API authentication and returns BDC dates, while false returns only hardcoded Form 477 periods. This clarifies the parameter's effect 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 returns available data vintages for Form 477 and BDC filing periods, specifies the action (list), and distinguishes from sibling tool fcc_list_downloads by noting it should be called first to determine valid as_of_date values.

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 advises calling this before fcc_list_downloads, explains the two data sources and the data gap, and notes credential requirements for BDC. It lacks an explicit statement of when not to use, but the context is clear.

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 annotations (readOnlyHint, idempotentHint), the description adds that data is from June 2021, ISP-reported at the block level, and may overstate actual coverage. 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?

Three sentences with no redundancy. The first sentence immediately states the tool's function, the second frames the use case, and the third provides critical context and prerequisites. Every sentence adds value.

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 complexity (4 parameters, output schema exists), the description covers the purpose, prerequisite, data source and limitation, and parameter meanings. It does not need to explain return values because the output schema handles that.

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%, but the description adds meaningful context: it explains the consumer/business filter, tech code mapping (e.g., 50=Fiber), and the purpose of min_speed_down. This enriches understanding beyond the schema's descriptions.

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 states it queries broadband providers and advertised speeds at a census block, with a clear question it answers ('which ISPs serve this location?'). It distinguishes itself from sibling tools like fcc_geocode_block (a prerequisite) and implies it is the core tool for address-level lookup.

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 says when to use (address-level broadband lookup) and names a prerequisite tool (fcc_geocode_block). It doesn't list alternatives among siblings, but the context of sibling tool names and the specific use case provide enough guidance. The data caveat also helps set expectations.

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 and idempotent. Description adds that results are deduplicated, include identifiers, and data is from June 2021. No contradictions.

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?

Four sentences, front-loaded with core function, examples second, limitations third. No 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?

For a search tool with 4 params and output schema, it covers purpose, parameters, return format, limitations, and data source. Adequate for agent selection and invocation.

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 baseline 3. Description adds examples for name_search, maps tech_filter codes to technology types, and explains limit max. Provides extra context beyond 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 action ('searches for ISPs'), the resource ('by holding company name'), and what it returns (deduplicated list with hoconum identifiers). It distinguishes from siblings by specifying follow-up with fcc_get_provider and gives example 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?

It provides explicit example questions, explains when to use (search by name/state/tech), and notes limitations (state-level only, need block data for sub-state). It also mentions the data source and date, aiding in deciding currentness.

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